Zinnia Enterprise Documents API

openapi: 3.0.1
info:
  title: Enterprise Documents API
  description: "The Enterprise Document Service (EDS) API is the system of record for documents\nacross the Zinnia life insurance\
    \ and annuity platform. Store a document once, then\nretrieve, update, and search it for the full duration of its retention\
    \ period. The API\ncovers carrier-issued correspondence and annual tax forms.\n\n## Overview\n\nA document in EDS has\
    \ two parts:\n\n- **Content** — the file itself.\n- **Metadata** — structured business information describing what the\
    \ file is and what it relates to.\n\nEach document is identified by a `documentId`, assigned at upload. Treat it as an\n\
    opaque handle: store it and pass it back on every subsequent call for that document.\n\nTax forms are managed separately\
    \ from the general document collection. They are never\nreturned by Search Documents and are accessible only through the\
    \ two Tax Form operations.\n\n## Operations\n\n<table border=\"1\" style=\"border-collapse: collapse; width: 100%;\">\n\
    \  <thead>\n    <tr>\n      <th style=\"border: 1px solid #ddd; padding: 8px; text-align: left;\">Operation</th>\n   \
    \   <th style=\"border: 1px solid #ddd; padding: 8px; text-align: left;\">Method and path</th>\n      <th style=\"border:\
    \ 1px solid #ddd; padding: 8px; text-align: left;\">Purpose</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td\
    \ style=\"border: 1px solid #ddd; padding: 8px;\">Upload Document</td>\n      <td style=\"border: 1px solid #ddd; padding:\
    \ 8px;\"><code>POST /document/v3/documents</code></td>\n      <td style=\"border: 1px solid #ddd; padding: 8px;\">Store\
    \ a new file with its business metadata and receive a <code>documentId</code>.</td>\n    </tr>\n    <tr>\n      <td style=\"\
    border: 1px solid #ddd; padding: 8px;\">Get Document Metadata</td>\n      <td style=\"border: 1px solid #ddd; padding:\
    \ 8px;\"><code>GET /document/v3/documents/{documentId}</code></td>\n      <td style=\"border: 1px solid #ddd; padding:\
    \ 8px;\">Retrieve full metadata for a document, optionally including version history.</td>\n    </tr>\n    <tr>\n    \
    \  <td style=\"border: 1px solid #ddd; padding: 8px;\">Update Document</td>\n      <td style=\"border: 1px solid #ddd;\
    \ padding: 8px;\"><code>PUT /document/v3/documents/{documentId}</code></td>\n      <td style=\"border: 1px solid #ddd;\
    \ padding: 8px;\">Update metadata, optionally replace the file content, and create a new version.</td>\n    </tr>\n  \
    \  <tr>\n      <td style=\"border: 1px solid #ddd; padding: 8px;\">Download Document</td>\n      <td style=\"border: 1px\
    \ solid #ddd; padding: 8px;\"><code>GET /document/v3/documents/{documentId}/download</code></td>\n      <td style=\"border:\
    \ 1px solid #ddd; padding: 8px;\">Retrieve document content, returned Base64-encoded in a JSON envelope.</td>\n    </tr>\n\
    \    <tr>\n      <td style=\"border: 1px solid #ddd; padding: 8px;\">Search Documents</td>\n      <td style=\"border:\
    \ 1px solid #ddd; padding: 8px;\"><code>POST /document/v3/documents/search</code></td>\n      <td style=\"border: 1px\
    \ solid #ddd; padding: 8px;\">Find documents by carrier, policy, case, agent, type, status, date range, and identifier\
    \ tags.</td>\n    </tr>\n    <tr>\n      <td style=\"border: 1px solid #ddd; padding: 8px;\">Get Tax Forms</td>\n    \
    \  <td style=\"border: 1px solid #ddd; padding: 8px;\"><code>GET /document/v3/tax-forms</code></td>\n      <td style=\"\
    border: 1px solid #ddd; padding: 8px;\">List tax forms available for a contract.</td>\n    </tr>\n    <tr>\n      <td\
    \ style=\"border: 1px solid #ddd; padding: 8px;\">Download Tax Form</td>\n      <td style=\"border: 1px solid #ddd; padding:\
    \ 8px;\"><code>GET /document/v3/tax-forms/{formId}/download</code></td>\n      <td style=\"border: 1px solid #ddd; padding:\
    \ 8px;\">Retrieve a tax form as a Base64-encoded PDF.</td>\n    </tr>\n  </tbody>\n</table>\n\n<h2>Authentication and\
    \ authorization</h2>\n\nEvery endpoint requires a JWT bearer token in the `Authorization` header:\n`Authorization: Bearer\
    \ {token}`.\n\nThe `Bearer` prefix is case-sensitive and must include the trailing space exactly as shown.\n\nTokens are\
    \ machine-to-machine (M2M) access tokens issued by the Zinnia identity provider.\nContact your Zinnia representative to\
    \ obtain credentials.\n\n**Note:** M2M access tokens are valid for 24 hours from issuance and may be reused for\nany number\
    \ of requests within that window.\n\n## Version history\n\n- **`3.0.0` (Latest)**\n  - Initial published v3 release. All\
    \ paths use the `/document/v3/...` prefix. Includes the seven Document and Tax Form operations, complete request/response\
    \ schemas, parameter definitions, error responses, and worked examples."
  version: 3.0.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
tags:
- name: Documents V3
  description: ''
- name: TaxForms V3
  description: ''
- name: Documents V2
  description: ''
- name: TaxForms V2
  description: ''
paths:
  /document/v2/documents:
    get:
      operationId: getDocuments
      summary: ''
      description: this is an endpoint to get a list of document metadata
      parameters:
      - name: Authorization
        required: true
        in: header
        schema:
          type: string
        description: This will be passed as Bearer plus "token" as generated by above token API.
        example: Bearer eykjsfjfjasdasdad
      - name: source
        required: false
        in: query
        schema:
          type: string
        description: Source of the document
        example: correspondence
      - name: clientCode
        required: false
        in: query
        schema:
          type: string
        description: Carrier code of the document
        example: EVGL
      - name: contractNumber
        required: false
        in: query
        schema:
          type: string
        description: This will be conditional mandatory. Either of contract number or date range is required in order to retrieve
          the documents.
        example: A000000071
      - name: documentDate
        required: false
        in: query
        schema:
          format: date-time
          type: string
        description: Date on which document has been added in Zinnia system
        example: '2025-01-01T10:20:00'
      - name: documentStartDate
        required: false
        in: query
        schema:
          format: date-time
          type: string
        description: This will be conditional mandatory. Either of contract number or date range is required in order to retrieve
          the documents. Date to define the document list based on document date range. Document Start Date
        example: '2025-01-01T10:20:00'
      - name: documentEndDate
        required: false
        in: query
        schema:
          format: date-time
          type: string
        description: This will be conditional mandatory. Either of contract number or date range is required in order to retrieve
          the documents. Date to define the document list based on document date range. Document End Date
        example: '2025-03-01T10:20:20'
      - name: documentType
        required: false
        in: query
        schema:
          type: string
        description: Type of the document
        example: NB Application
      - name: importStartDate
        required: false
        in: query
        schema:
          format: date-time
          type: string
        description: This will be conditional mandatory. Either of contract number or date range is required in order to retrieve
          the documents. Date to define the document list based on import date range
        example: '2023-01-01T15:41:16'
      - name: importEndDate
        required: false
        in: query
        schema:
          format: date-time
          type: string
        description: This will be conditional mandatory. If document start date is provided, then it should be madatorily
          provided. Date to define the document list based on import date range
        example: '2023-03-01T15:41:16'
      - name: masterNumber
        required: false
        in: query
        schema:
          type: string
        description: Unique number assigned to the agent
        example: MA00186973
      - name: docStatus
        required: false
        in: query
        schema:
          type: string
        description: Status of the document. Can be provided in comma separated value. Default will be 'active'
        example: Active,Removed,Archived
      - name: caseId
        required: false
        in: query
        schema:
          type: string
        description: Unique number assigned to case
        example: 0987654321
      - name: documentNumber
        required: false
        in: query
        schema:
          type: string
        description: Document number
        example: '1234567890'
      - name: recipient
        required: false
        in: query
        schema:
          $ref: '#/components/schemas/Recipient'
        description: Recipient of the document
        example: Agent
      - name: zinniaLiveCaseId
        required: false
        in: query
        schema:
          type: string
        description: Unique case ID in the Zinnia system associated with the document
        example: ZLC09876
      - name: periods
        required: false
        in: query
        description: Periods of the document
        example:
        - PeriodYear: '2020'
          PeriodQuarters:
          - Q1
          - Q2
          - Q3
          - Q4
        schema:
          type: array
          items:
            type: object
            properties:
              PeriodYear:
                type: string
              PeriodQuarters:
                type: array
                items:
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InlineResponse200'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InlineResponse400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InlineResponse401'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InlineResponse404'
      tags:
      - Documents V2
      security:
      - Auth0: []
  /document/v2/documents/{documentId}:
    get:
      operationId: getDocument
      summary: ''
      description: this is an endpoint to get a specific documents metadata
      parameters:
      - name: Authorization
        required: true
        in: header
        schema:
          type: string
        description: This will be passed as Bearer plus "token" as generated by above token API.
        example: Bearer eykjsfjfjasdasdad
      - name: documentId
        required: true
        in: path
        schema:
          type: string
        description: Unique number assigned to the document
        example: '1234567890'
      - name: docType
        required: true
        in: query
        schema:
          type: string
        description: Type of the document
        example: NB Application
      - name: source
        required: false
        in: query
        schema:
          type: string
        description: Source of the document
        example: correspondence
      - name: clientCode
        required: false
        in: query
        schema:
          type: string
        description: Carrier code of the document
        example: EVGL
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InlineResponse400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InlineResponse401'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InlineResponse404'
      tags:
      - Documents V2
      security:
      - Auth0: []
  /document/v2/documents/{documentId}/download:
    get:
      operationId: downloadDocument-v2
      summary: ''
      description: this is an endpoint to download a document
      parameters:
      - name: documentId
        required: true
        in: path
        schema:
          type: string
        description: Unique number assigned to the document
        example: '1234567890'
      - name: Authorization
        required: true
        in: header
        schema:
          type: string
        description: This will be passed as Bearer plus "token" as generated by above token API.
        example: Bearer eykjsfjfjasdasdad
      - name: source
        required: false
        in: query
        schema:
          type: string
        description: Source of the document
        example: correspondence
      - name: clientCode
        required: false
        in: query
        schema:
          type: string
        description: Carrier code of the document
        example: EVGL
      - name: policyNumber
        required: false
        in: query
        schema:
          type: string
        description: Policy number associated with the document, used for identification
        example: '1234567890'
      - name: planCode
        required: false
        in: query
        schema:
          type: string
        description: Plan code associated with the document, used for identification
        example: '1234567890'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadDocumentResponse'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/DownloadDocumentResponse'
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InlineResponse4001'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InlineResponse401'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InlineResponse404'
      tags:
      - Documents V2
      security:
      - Auth0: []
  /document/v2/taxForms:
    get:
      operationId: getTaxForms-v2
      summary: ''
      description: This is an endpoint to get a list of tax-forms from SOVOS
      parameters:
      - name: Authorization
        required: true
        in: header
        example: Bearer <token>
        description: Authorization token
        schema:
          type: string
      - name: clientCode
        in: query
        example: EVGL
        description: Client code for the carrier/client
        schema:
          type: string
      - name: contractNumber
        required: true
        in: query
        description: Contract number for the document/tax-form
        example: '1234567898'
        schema:
          type: string
      - name: taxYear
        required: false
        in: query
        description: Tax-year for the form (defaults to current year-1)
        example: '2023'
        schema:
          type: string
      - name: numYears
        required: false
        in: query
        example: 1
        description: Number of years of forms to query in reverse chronological order from taxyear (incl). Min=1 and Max=5
        schema:
          minimum: 1
          maximum: 5
          default: 1
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxFormsResponse200'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InlineResponse400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InlineResponse401'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InlineResponse404'
      tags:
      - TaxForms V2
      security:
      - Auth0: []
  /document/v2/taxForms/{formId}:
    get:
      operationId: downloadTaxForm-v2
      summary: ''
      description: This is an endpoint to download a tax-form from SOVOS
      parameters:
      - name: Authorization
        required: true
        in: header
        example: Bearer <token>
        description: Authorization token
        schema:
          type: string
      - name: formId
        required: true
        in: path
        example: '123456'
        description: Form id for the tax-form
        schema:
          type: string
      - name: clientCode
        in: query
        example: EVGL
        description: Client code for the carrier/client
        schema:
          type: string
      - name: contractNumber
        required: true
        in: query
        example: '1234567898'
        description: Contract number for the document/tax-form
        schema:
          type: string
      - name: fChar
        required: true
        in: query
        example: R
        description: Unique string character associated with the tax-form name
        schema:
          type: string
      - name: taxYear
        required: false
        in: query
        example: '2023'
        description: Tax-year for the form (defaults to current year-1)
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadDocumentResponse'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/DownloadDocumentResponse'
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InlineResponse400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InlineResponse401'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InlineResponse404'
      tags:
      - TaxForms V2
      security:
      - Auth0: []
  /document/v3/documents:
    post:
      security:
      - Auth0: []
      tags:
      - Documents V3
      summary: Uploads a document and saves its metadata
      description: Accepts a file with metadata and returns a document Id
      operationId: UploadDocuments
      parameters:
      - name: x-correlation-id
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - metadata
              - file
              type: object
              properties:
                file:
                  type: string
                  format: binary
                metadata:
                  $ref: '#/components/schemas/Metadata'
      responses:
        '201':
          description: document stored successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadResponse'
        '400':
          description: document storage failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadBadRequest'
        '403':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadForbidden'
  /document/v3/documents/{documentId}:
    get:
      security:
      - Auth0: []
      tags:
      - Documents V3
      summary: Gets metadata for a document
      description: Fetches metadata details, including version history if requested
      operationId: getMetadataByDocumentId
      parameters:
      - name: Authorization
        required: true
        in: header
        example: Bearer <token>
        description: Authorization token
        schema:
          type: string
      - name: documentId
        in: path
        required: true
        schema:
          type: string
        description: Unique ID in EDS db
        example: 670e23dfab593b4387210b81
      - name: x-correlation-id
        in: header
        required: false
        schema:
          type: string
        description: Unique ID for correlating requests
        example: 1760f822-dcbf-49fc-a623-a1998383f4b9
      - name: isAllVersionsNeeded
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: Indicates if all versions are required in the response
        example: true
      - name: documentType
        in: query
        required: false
        description: Type of document indicating its purpose
        example: NB Application
        schema:
          type: string
      - name: documentClassification
        in: query
        required: false
        schema:
          type: string
          description: Classification of the document, e.g., OUTBOUND OR INBOUND
          example: OUTBOUND
          enum:
          - OUTBOUND
          - INBOUND
      - name: parentCarrierCode
        in: query
        required: false
        description: Client code associated with the document
        example: EVGL
        schema:
          type: string
      responses:
        '200':
          description: document metadata retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataByIdResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: docType should not be empty
                  statusCode:
                    type: integer
                    example: 400
                  correlationId:
                    type: string
                    example: 123e4567-e89b-12d3-a456-426614174000
                  success:
                    type: string
                    example: 'false'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Access denied for document metadata fetch
                  statusCode:
                    type: integer
                    example: 403
                  correlationId:
                    type: string
                    example: 123e4567-e89b-12d3-a456-426614174000
                  success:
                    type: string
                    example: 'false'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Document not found
                  statusCode:
                    type: integer
                    example: 404
                  correlationId:
                    type: string
                    example: 123e4567-e89b-12d3-a456-426614174000
                  success:
                    type: string
                    example: 'false'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Error occurred while fetching metadata
                  statusCode:
                    type: integer
                    example: 500
                  correlationId:
                    type: string
                    example: 123e4567-e89b-12d3-a456-426614174000
                  success:
                    type: string
                    example: 'false'
    put:
      security:
      - Auth0: []
      tags:
      - Documents V3
      summary: updates document content or metadata
      description: modifies metadata and optionally replaces the file
      operationId: updateDocuments
      parameters:
      - name: x-correlation-id
        in: header
        required: false
        schema:
          type: string
      - name: documentId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - metadata
              type: object
              properties:
                file:
                  type: string
                  format: binary
                metadata:
                  $ref: '#/components/schemas/MetadataUpdate'
      responses:
        '204':
          description: Document updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    type: string
                    description: Unique ID for correlating requests
                    example: 123e4567-e89b-12d3-a456-426614174000
                  message:
                    type: string
                    example: Document updated successfully
                  statusCode:
                    type: integer
                    format: int32
                    example: 204
                  success:
                    type: boolean
                    example: true
        '400':
          description: Document update failed due to bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    type: string
                    example: 123e4567-e89b-12d3-a456-426614174000
                  message:
                    type: string
                    example: Invalid metadata provided
                  statusCode:
                    type: integer
                    format: int32
                    example: 400
                  success:
                    type: boolean
                    example: false
        '403':
          description: Unauthorized access
          content:
            application/json:
              schema:
                type: object
                properties:
                  correlationId:
                    type: string
                    example: 123e4567-e89b-12d3-a456-426614174000
                  message:
                    type: string
                    example: Access denied to update document
                  statusCode:
                    type: integer
                    format: int32
                    example: 403
                  success:
                    type: boolean
                    example: false
  /document/v3/documents/{documentId}/download:
    get:
      security:
      - Auth0: []
      tags:
      - Documents V3
      summary: Retrieves a document by ID
      description: Downloads a document based on its unique identifier
      operationId: downloadDocument-v3
      parameters:
      - name: Authorization
        required: true
        in: header
        example: Bearer <token>
        description: Authorization token
        schema:
          type: string
      - name: documentId
        in: path
        required: true
        description: Unique ID in EDS DB
        example: 670e23dfab593b4387210b81
        schema:
          type: string
      - name: x-correlation-id
        in: header
        required: false
        description: Unique ID for correlating requests
        example: 123e4567-e89b-12d3-a456-426614174000
        schema:
          type: string
      - name: documentClassification
        in: query
        required: false
        schema:
          type: string
          enum:
          - OUTBOUND
          - INBOUND
        description: Classification of the document, e.g., OUTBOUND or INBOUND
        example: OUTBOUND
      - name: parentCarrierCode
        in: query
        required: false
        description: Client code associated with the document
        example: EVGL
        schema:
          type: string
      - name: policyNumber
        in: query
        required: false
        description: Policy number associated with the document
        example: '23109168'
        schema:
          type: string
      - name: planCode
        in: query
        required: false
        description: Plan code
        example: '565'
        schema:
          type: string
      responses:
        '200':
          description: document downloaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentDownloadResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Access denied for document download
                  statusCode:
                    type: integer
                    example: 403
                  correlationId:
                    type: string
                    example: 123e4567-e89b-12d3-a456-426614174000
                  success:
                    type: boolean
                    example: false
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Document not found
                  statusCode:
                    type: integer
                    example: 404
                  correlationId:
                    type: string
                    example: 123e4567-e89b-12d3-a456-426614174000
                  success:
                    type: boolean
                    example: false
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: An unexpected error occurred while downloading document
                  statusCode:
                    type: integer
                    example: 500
                  correlationId:
                    type: string
                    example: 123e4567-e89b-12d3-a456-426614174000
                  success:
                    type: boolean
                    example: false
  /document/v3/documents/search:
    post:
      security:
      - Auth0: []
      tags:
      - Documents V3
      summary: Searches for documents
      description: finds documents based on filters like document classification, document type, policy number etc
      operationId: searchDocuments
      parameters:
      - name: Author

# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zinnia/refs/heads/main/openapi/zinnia-documents-openapi.yml