---
title: "getDocuments"
url: "https://developers.zinnia.com/apis/documents-0-3-0/versions/43d1ee7b-44e7-4303-b0cd-ca813c63b625/operations/getDocuments"
---

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

# getDocuments

`GET` `/document/v2/documents`

Operation ID: `getDocuments`

this is an endpoint to get a list of document metadata

## Query parameters

- `source` (string, optional) - Source of the document
- `clientCode` (string, optional) - Carrier code of the document
- `contractNumber` (string, optional) - This will be conditional mandatory. Either of contract number or date range is required in order to retrieve the documents.
- `documentDate` (string, date-time, optional) - Date on which document has been added in Zinnia system
- `documentStartDate` (string, date-time, optional) - 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
- `documentEndDate` (string, date-time, optional) - 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
- `documentType` (string, optional) - Type of the document
- `importStartDate` (string, date-time, optional) - 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
- `importEndDate` (string, date-time, optional) - 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
- `masterNumber` (string, optional) - Unique number assigned to the agent
- `docStatus` (string, optional) - Status of the document. Can be provided in comma separated value. Default will be 'active'
- `caseId` (string, optional) - Unique number assigned to case
- `documentNumber` (string, optional) - Document number
- `recipient` (string, optional) - Recipient of the document
- `zinniaLiveCaseId` (string, optional) - Unique case ID in the Zinnia system associated with the document
- `periods` (array, optional) - Periods of the document

## Header parameters

- `Authorization` (string, required) - This will be passed as Bearer plus "token" as generated by above token API.

## Responses

- `200` - OK
- `400` - Bad Request
- `401` - Unauthorized
- `404` - Not Found

## OpenAPI definition

```yaml
openapi: 3.0.1
info:
  title: Enterprise Documents API
  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
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: []
security:
  - Auth0: []
components:
  schemas:
    Recipient:
      type: string
      enum:
        - Agent
        - Client
    InlineResponse200:
      type: object
      properties:
        count:
          type: number
        items:
          type: array
          items:
            $ref: "#/components/schemas/DocumentMetadata"
      required:
        - count
        - items
    InlineResponse400:
      type: object
      properties:
        xCorrelationId:
          type: string
        status:
          type: number
        errorDesc:
          type: string
        errorDetailedDesc:
          type: string
      required:
        - xCorrelationId
        - status
        - errorDesc
        - errorDetailedDesc
    InlineResponse401:
      type: object
      properties:
        message:
          type: string
      required:
        - message
    InlineResponse404:
      type: object
      properties:
        message:
          type: string
      required:
        - message
    DocumentMetadata:
      type: object
      properties:
        documentID:
          type: string
        pageCount:
          type: string
        documentDate:
          format: date-time
          type: string
        importDate:
          format: date-time
          type: string
        fileName:
          type: string
        fileType:
          type: string
        displayName:
          type: string
        sourceFileName:
          type: string
        status:
          type: string
        documentType:
          type: string
        contractNumber:
          type: string
        masterNumber:
          type: string
        repMan:
          type: string
        clientID:
          type: string
        history:
          type: boolean
        docStatus:
          type: string
        documentNumber:
          type: string
        caseId:
          type: number
        zinniaLiveCaseId:
          type: string
        docPopUrl:
          type: string
        attachmentType:
          type: string
        periodYear:
          type: string
        periodQuarter:
          type: string
      required:
        - documentID
        - pageCount
        - documentDate
        - importDate
        - fileName
        - fileType
        - displayName
        - sourceFileName
        - status
        - documentType
        - contractNumber
        - masterNumber
        - repMan
        - clientID
        - history
        - docStatus
        - documentNumber
        - caseId
        - zinniaLiveCaseId
        - docPopUrl
        - attachmentType
        - periodYear
        - periodQuarter
  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
```