---
title: "Uploads a document and saves its metadata"
url: "https://developers.zinnia.com/apis/documents-0-3-0/versions/43d1ee7b-44e7-4303-b0cd-ca813c63b625/operations/UploadDocuments"
---

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

# Uploads a document and saves its metadata

`POST` `/document/v3/documents`

Operation ID: `UploadDocuments`

Accepts a file with metadata and returns a document Id

## Header parameters

- `x-correlation-id` (string, optional)

## Request body

Content types: `multipart/form-data`

## Responses

- `201` - document stored successfully
- `400` - document storage failed
- `403` - Unauthorized access

## 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:
    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"
security:
  - Auth0: []
components:
  schemas:
    Metadata:
      required:
        - docClassification
        - fileType
        - documentType
        - documentTypeDescription
        - docCategory
      type: object
      properties:
        zinniaLiveCaseId:
          type: string
          description: Zinnia Live Case ID. Either of policy number, Application Id or ZL
            case Id is required.
          example: ZLC09876
        appId:
          type: string
          description: Application ID. Either of policy number, Application Id or ZL case
            Id is required.
          example: EDJ041120240000000001
        docClassification:
          type: string
          description: Document classification to identify document type
          example: OUTBOUND
          enum:
            - OUTBOUND
            - INBOUND
        source:
          type: string
          description: Source of the document
          example: Email
        docCategory:
          type: string
          description: Document category
          example: NEW_BUSINESS
          enum:
            - NEW_BUSINESS
            - POST_ISSUE
            - DEATH
            - CORRESPONDENCE
            - AGENT
            - SUITABILITY
        fileType:
          type: string
          description: File type
          example: PDF
        documentType:
          type: string
          enum:
            - NB_STATE_REPLACEMENT
            - NB_CONVERSION
            - NB_APPLICATION
            - COST_DISCLOSURE
            - NON_CONTRACTUAL
            - AGENT_REPORT
            - ACCELERATED_BENEFIT_RIDER
            - SURRENDER_COMPARISION
            - CONSENT_PAPERLESS
            - TERMS_OF_USE
            - TERMS_CONDITIONS
            - CHARITY_ELECTION_FORMS
            - AUTHORIZATION_FORMS
            - HIPPA
            - HIV_CONSENT_FORM_ALL_STATE
            - AMENDMENT
            - DISCLOSURES
            - NB_STATE_REPLACEMENT_NOTICE
            - TRUSTEE_STATEMENT
            - TERMS_OF_USE
            - NOTICE_AND_CONSENT
            - PRIVACY_POLICY
            - GLBA_PRIVACY_NOTICE
            - FCRA
            - MIB_PRE_NOTICE
            - ID_VERIFICATION_NOTICE
            - HIPAA
            - ACCELERATED_BENEFIT_RIDER
            - BUYER_GUIDE
            - ILLUSTRATION
            - SUITABILITY
            - APPLICATION
            - SIGNED_APPLICATION
            - REPLACEMENTS_ACKNOWLEDGEMENT
            - 1035_EXCHANGE_SURRENDER
            - EVIDENCE_DOCUMENT
            - AMENDMENT
            - ELECTRONIC_FUNDS_TRANSFER
            - SUPPLEMENTAL_APPLICATION
            - CONFORMING_ILLUSTRATION
            - SIGNED_ILLUSTRATION
            - OVERFLOW_ADDITIONAL_INFORMATION
        documentDate:
          type: string
          description: Date of the document
          format: date-time
        documentTypeDescription:
          type: string
          description: Description of the document type. Refer the mapping sheet shared
            along with specification
          example: Address Change Letter
        planCode:
          type: string
          description: Plan code
          example: "235"
        policyNumber:
          type: string
          description: Policy number. Either of policy number, Application Id or ZL case
            Id is required.
          example: "23576001"
        pageCount:
          type: integer
          description: Total page count
          format: int64
          example: 5
        docAccessLevel:
          type: string
          description: Specifies who can access the document based on their role.
          example: CLIENT_COPY
          enum:
            - CLIENT_COPY
            - AGENT_COPY
        sourceFileName:
          type: string
          description: Source file name
          example: 052725FTADHOCLETTERS_R_20485_1207637_711.pdf
    DocumentUploadResponse:
      type: object
      properties:
        documentId:
          type: string
          description: Unique ID
          example: 670e23dfab593b4387210b81
        correlationId:
          type: string
          description: Unique ID for correlating requests
          example: 123e4567-e89b-12d3-a456-426614174000
        message:
          type: string
          description: Response message
          example: Document uploaded successfully
        statusCode:
          type: integer
          description: Status code of the response
          format: int32
          example: 200
        success:
          type: boolean
    DocumentUploadBadRequest:
      type: object
      properties:
        correlationId:
          type: string
          description: Unique ID for correlating requests
          example: 123e4567-e89b-12d3-a456-426614174000
        message:
          type: string
          description: Error message
          example: Invalid request payload
        statusCode:
          type: integer
          description: Status code of the response
          format: int32
          example: 400
        success:
          type: boolean
          example: false
    DocumentUploadForbidden:
      type: object
      properties:
        correlationId:
          type: string
          description: Unique ID for correlating requests
          example: 123e4567-e89b-12d3-a456-426614174000
        message:
          type: string
          description: Error message
          example: Forbidden
        statusCode:
          type: integer
          description: Status code of the response
          format: int32
          example: 403
        success:
          type: boolean
          example: false
  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
```