---
title: "Searches for a service request form based on the provided criteria"
url: "https://developers.zinnia.com/apis/documents-0-3-0/versions/43d1ee7b-44e7-4303-b0cd-ca813c63b625/operations/searchServiceRequestForms"
---

> Full API specification: https://developers.zinnia.com/apis/documents-0-3-0/versions/43d1ee7b-44e7-4303-b0cd-ca813c63b625.md

# Searches for a service request form based on the provided criteria

`POST` `/document/v3/service-request-form/search`

Operation ID: `searchServiceRequestForms`

Searches for a service request form using the given details. Results will be returned based on the specified search criteria.

## Query parameters

- `limit` (integer, int32, optional)
- `offset` (integer, int32, optional)
- `x-correlation-id` (string, optional)

## Request body (required)

Content types: `application/json`

## Responses

- `200` - service request forms retrieved successfully
- `400` - service request forms retrieval failed
- `403` - Forbidden
- `500` - Internal server error

## OpenAPI definition

```yaml
openapi: 3.0.1
info:
  title: Enterprise Documents API
  version: 3.1.0
servers:
  - url: https://dev.api.zinnia.io
    description: Dev Environment
  - url: https://qa.api.zinnia.io
    description: QA Environment
  - url: https://uat.api.zinnia.io
    description: UAT Environment
  - url: https://api.zinnia.io
    description: PROD Environment
paths:
  /document/v3/service-request-form/search:
    post:
      security:
        - Auth0: []
      tags:
        - ServiceRequestForms V3
      summary: Searches for a service request form based on the provided criteria
      description: Searches for a service request form using the given details.
        Results will be returned based on the specified search criteria.
      operationId: searchServiceRequestForms
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            format: int32
            default: 10
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            format: int32
            default: 0
        - name: x-correlation-id
          in: query
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ServiceRequestFormSearchRequest"
        required: true
      responses:
        "200":
          description: service request forms retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchServiceRequestFormResponse"
        "400":
          description: service request forms retrieval failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InvalidRequest:
                  summary: Invalid input
                  description: InvalidRequest
                  value:
                    correlationId: 123e4567-e89b-12d3-a456-426614174000
                    success: false
                    message: Invalid request format
                    statusCode: 400
                MissingField:
                  summary: Missing required field
                  description: MissingField
                  value:
                    correlationId: 123e4567-e89b-12d3-a456-426614174000
                    success: false
                    message: "'documentType' is required"
                    statusCode: 400
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                AccessDenied:
                  summary: Access denied
                  description: AccessDenied
                  value:
                    correlationId: 123e4567-e89b-12d3-a456-426614174000
                    success: false
                    message: Service request form access denied
                    statusCode: 403
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                UnexpectedError:
                  summary: Unexpected server error
                  description: UnexpectedError
                  value:
                    correlationId: 123e4567-e89b-12d3-a456-426614174000
                    success: false
                    message: An unexpected error occurred
                    statusCode: 500
security:
  - Auth0: []
components:
  schemas:
    ServiceRequestFormSearchRequest:
      required:
        - parentCarrierCode
      type: object
      properties:
        parentCarrierCode:
          type: string
          description: client code associated with the document search
          example: EVGL
        formId:
          type: string
          description: Id to the specific form instance
          example: 123456 CA
        stateApplicable:
          type: string
          description: State where the form is applicable or valid
          example: NY
        formCategory:
          type: string
          description: Category of the form
          example: Financial
        formType:
          type: string
          description: Type of form
          example: Redemption
        formSubType:
          type: string
          description: More specific classification under the form type
          example: Full Surrender
        orderBy:
          type: string
          description: The field used to sort the search results; defaults to 'createDate'
            if not specified
          example: createDate
        orderByDirection:
          type: string
          description: Direction of the sort order for search results, either ascending or
            descending
          example: DESC
          enum:
            - ASC
            - DESC
    SearchServiceRequestFormResponse:
      type: object
      properties:
        count:
          type: integer
          description: Number of total documents found matching the search criteria
          format: int64
          example: 100
        documents:
          type: array
          items:
            $ref: "#/components/schemas/MetadataSRFSearchResponse"
        correlationId:
          type: string
          description: Unique ID for correlating requests
          example: 123e4567-e89b-12d3-a456-426614174000
    ErrorResponse:
      type: object
      properties:
        correlationId:
          type: string
          description: Unique ID for correlating requests
          example: 123e4567-e89b-12d3-a456-426614174000
        message:
          type: string
          description: Response message
          example: No document types found/Invalid request/Access denied for document
            metadata fetch
        statusCode:
          type: integer
          description: status code
          format: int32
        success:
          type: boolean
        errorCode:
          type: string
          description: Machine-readable error code, present on timeouts and unhandled
            errors.
          enum:
            - GATEWAY_TIMEOUT
            - DB_TIMEOUT
            - INTERNAL_ERROR
    MetadataSRFSearchResponse:
      type: object
      properties:
        id:
          type: string
          description: id
          example: 67124697f3bef2497b6accfb
        formId:
          type: string
          description: Id to the specific form instance
          example: 01 12345 3456 US
        formStatus:
          type: integer
          description: Status of the form
          format: int32
          example: 1
        formName:
          type: string
          description: Name of the form
          example: Annuity Payout Benefits Form
        publicFormUrl:
          type: string
          description: Publicly accessible URL where the form can be viewed or downloaded
          example: https//:zinnia.srf.com
        uploadedDate:
          type: string
          description: Date and time when the form was uploaded
          format: date-time
          example: 2025-03-10T15:58:56.081Z
        formCategory:
          type: string
          description: Category that describes the purpose of the form
          example: Withdrawal
        stateApplicable:
          type: string
          description: State where the form is applicable or valid
          example: NY
        fileType:
          type: string
          description: The type of file format for the form
          example: PDF
        formVersion:
          type: string
          description: Version number of the form
          example: "1"
        formType:
          type: string
          description: Type of the form
          example: Redemption
        formSubType:
          type: string
          description: Further classification of the form type
          example: Full Surrender
        barcodeContent:
          type: string
          description: Barcode data used for identifying or scanning the form
          example: 13qwf312wfw312fqe2jtyktym
  securitySchemes:
    Auth0:
      type: openIdConnect
      openIdConnectUrl: https://login.zinnia.com/.well-known/openid-configuration
      x-kong-security-openid-connect:
        config:
          run_on_preflight: true
          scopes_claim:
            - https://api.zinnia.io/permissions
          audience_claim:
            - aud
          audience_required:
            - https://api.zinnia.io
          client_id:
            - bGOIRPRq2ZnjCujDXC7ikwR5ez7VH5GZ
          auth_methods:
            - bearer
          scopes: []
        enabled: true
        protocols:
          - grpc
          - grpcs
          - http
          - https
```