---
title: "Gets metadata for a document"
url: "https://developers.zinnia.com/apis/documents-0-3-0/versions/43d1ee7b-44e7-4303-b0cd-ca813c63b625/operations/getMetadataByDocumentId"
---

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

# Gets metadata for a document

`GET` `/document/v3/documents/{documentId}`

Operation ID: `getMetadataByDocumentId`

Fetches metadata details, including version history if requested

## Path parameters

- `documentId` (string, required) - Unique ID in EDS db

## Query parameters

- `isAllVersionsNeeded` (boolean, optional) - Indicates if all versions are required in the response
- `documentType` (string, optional) - Type of document indicating its purpose
- `documentClassification` (string, optional)
- `parentCarrierCode` (string, optional) - Client code associated with the document

## Header parameters

- `Authorization` (string, required) - Authorization token
- `x-correlation-id` (string, optional) - Unique ID for correlating requests

## Responses

- `200` - document metadata retrieved successfully
- `400` - Bad Request
- `403` - Forbidden
- `404` - Not found
- `500` - Internal Server Error

## 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/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"
security:
  - Auth0: []
components:
  schemas:
    MetadataByIdResponse:
      type: object
      properties:
        metadata:
          $ref: "#/components/schemas/MetadataResponse"
        correlationId:
          type: string
          description: Unique ID for correlating requests
          example: 123e4567-e89b-12d3-a456-426614174000
    MetadataResponse:
      type: object
      properties:
        source:
          type: string
          description: Source system or origin of the document
          example: Email
        documentId:
          type: string
          description: Unique ID in EDS db
          example: 670e23dfab593b4387210b81
        formNumber:
          type: string
          description: Form number associated with the document
          example: FORM123
        fileType:
          type: string
          description: Type of file, e.g., pdf, doc, etc.
          example: pdf
        documentClassification:
          type: string
          description: Classification of the document, e.g., OUTBOUND or INBOUND
          example: OUTBOUND
          enum:
            - OUTBOUND
            - INBOUND
        documentType:
          type: string
          description: Type of document indicating its purpose
          example: NB Application
        documentCategory:
          type: string
          description: Category of the document, such as New Business or Claim
          example: New Business
        documentTypeDescription:
          type: string
          description: Description of the document type
          example: Deferred Annuity Application
        documentStatus:
          type: integer
          description: Indicates the current status of the document. '1' for ACTIVE, '0'
            for INACTIVE.
          format: int32
          example: 1
        version:
          type: string
          description: Version of the document
          example: "1"
        documentDate:
          type: string
          description: Date of the document
          format: date-time
          example: 2024-03-18T14:30:00.000Z
        zinniaLiveCaseId:
          type: string
          description: Zinnia Live Case ID
          example: ZLC09876
        planCode:
          type: string
          description: Plan code
          example: "565"
        policyNumber:
          type: string
          description: Policy number associated with the document
          example: "23109168"
        brokerMasterNumber:
          type: string
          description: Broker master number associated with the document
          example: BKR123456
        repMasterNumber:
          type: string
          description: Representative master number associated with the document
          example: REP987654
        agentExternalID:
          type: string
          description: External ID of the agent associated with the document
          example: AGT12345
        brokerExternalID:
          type: string
          description: External ID of the broker associated with the document
          example: BRK12345
        mailTrackingNumber:
          type: string
          description: Mail tracking number
          example: TRK123456
        deliveryMethod:
          type: string
          description: Delivery method
          example: Email
        emailFrom:
          type: string
          description: Email address
          example: XHbN8@example.com
        emailTo:
          type: string
          description: Email address
          example: XHbN8@example.com
        emailSubject:
          type: string
          description: Email subject
          example: Deferred Annuity Application
        appId:
          type: string
          description: Application ID
          example: APP123456
        mailShipDate:
          type: string
          description: Mail ship date
          format: date-time
          example: 2024-03-18T14:30:00.000Z
        participantAccountNumber:
          type: string
          description: Account number of the participant
          example: "123456789"
        sourceFileName:
          type: string
          description: Name of the file in source system
          example: files/123456.pdf
        displayName:
          type: string
          description: Display name of the document
          example: Deferred Annuity Application
        distributionChannel:
          type: string
          description: Distribution channel through which the document was delivered
          example: Online Portal
        periodYear:
          type: integer
          description: Year of the document period
          format: int32
          example: 2024
        periodQuarter:
          type: string
          description: Quarter of the document period in Q1-Q4 format
          example: Q2
        documentNumber:
          type: string
          description: Document number associated with the document (if present) else
            document Id
          example: 670e23dfab593b4387210b81 or 20241230-M-463066
        documentVersions:
          type: array
          description: Previous versions of the document
          items:
            $ref: "#/components/schemas/MetadataResponse"
        scenario:
          type: string
          description: Scenario
          example: duplicate
          enum:
            - duplicate
            - replace
        linkedDocumentId:
          type: string
          description: Linked document ID
          example: 693e23dfab593b4387210k92
        importDate:
          type: string
          format: date-time
          description: Document creation timestamp(in UTC timezone)
          example: 2024-09-23T10:30:00.000Z
  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
```