> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beltic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add File to Document IDV

> Add a file to the IDV document and receive a pre-signed S3 URL for upload



## OpenAPI

````yaml POST /v1/identity/documents/idvs/{id}/files
openapi: 3.1.0
info:
  title: Beltic Identity API
  version: 1.0.0
  description: >-
    # Identity API


    The Beltic Identity API provides identity management capabilities including
    accounts, sessions, document verification, and identity verifications.


    ## Key Features


    - **Account Management**: Create and manage identity accounts

    - **Session Management**: Create and manage verification sessions with
    lifecycle controls

    - **Document Verification**: Submit and process identity documents
    (government IDs, proof of address)

    - **Identity Verification**: Run identity, address, and business
    verifications

    - **JSON:API Format**: All responses follow JSON:API specification


    ## Authentication


    All endpoints require authentication. Include your API key in the
    `X-Api-Key` header:

    ```

    X-Api-Key: YOUR_API_KEY

    ```


    ## Response Format


    All responses follow the JSON:API specification for consistent data
    structures.
  contact:
    name: Beltic API Support
    email: engineering@beltic.com
servers:
  - url: https://api.beltic.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Accounts
    description: Account management operations
  - name: Sessions
    description: Session management operations
  - name: Session Devices
    description: Session device management operations
  - name: Document Addresses
    description: Proof of address document management operations
  - name: Document IDVs
    description: Government ID verification document management operations
  - name: Verifications
    description: Base verification resource operations
externalDocs:
  description: Beltic Platform Documentation
  url: https://docs.beltic.com
paths:
  /v1/identity/documents/idvs/{id}/files:
    post:
      tags:
        - Document IDVs
      summary: Add file to IDV document
      description: >-
        Add a file to the IDV document and receive a pre-signed S3 URL for
        upload
      parameters:
        - schema:
            type: string
            format: uuid
            description: The unique identifier of the document
            example: 123e4567-e89b-12d3-a456-426614174000
          required: true
          description: The unique identifier of the document
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddIdvFileRequest'
      responses:
        '200':
          description: File added successfully, pre-signed URL provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddIdvFileResponse'
        '400':
          description: Bad Request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - Resource already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    AddIdvFileRequest:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              enum:
                - file
              description: Resource type
            attributes:
              allOf:
                - $ref: '#/components/schemas/IdvFileInfoRequest'
                - description: File metadata
          required:
            - type
            - attributes
      required:
        - data
    AddIdvFileResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              enum:
                - file
              description: Resource type
            id:
              type: string
              format: uuid
              description: Unique identifier for the file
              example: 123e4567-e89b-12d3-a456-426614174000
            attributes:
              allOf:
                - $ref: '#/components/schemas/IdvFileInfoResponse'
                - description: File metadata
          required:
            - type
            - id
            - attributes
        meta:
          type: object
          properties:
            presigned_upload_url:
              type: string
              format: uri
              description: Presigned URL for uploading the file to S3
              example: https://s3.amazonaws.com/beltic-documents/...
            expires_in:
              type: integer
              exclusiveMinimum: 0
              description: Seconds until the presigned URL expires
              example: 3600
          required:
            - presigned_upload_url
            - expires_in
          description: Upload URL metadata
      required:
        - data
        - meta
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/JsonApiError'
        meta:
          type: object
          additionalProperties: {}
      required:
        - errors
    IdvFileInfoRequest:
      type: object
      properties:
        filename:
          type: string
      required:
        - filename
    IdvFileInfoResponse:
      type: object
      properties:
        id:
          type: string
        filename:
          type: string
        content_type:
          type:
            - string
            - 'null'
        byte_size:
          type:
            - number
            - 'null'
        checksum:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - pending_upload
            - uploaded
            - failed
            - deleted
        url:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            Presigned download URL (valid for 15 minutes, null if pending
            upload)
          example: https://s3.amazonaws.com/...?X-Amz-Signature=...
      required:
        - id
        - filename
        - status
        - url
    JsonApiError:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        code:
          type: string
        title:
          type: string
        detail:
          type: string
        source:
          type: object
          properties:
            pointer:
              type: string
            parameter:
              type: string
            header:
              type: string
        meta:
          type: object
          additionalProperties: {}
      required:
        - status
        - title
        - detail
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: |-
        API key for authentication.
        Access https://console.beltic.com/ to obtain your API key.

````