openapi: 3.0.3
info:
  title: api-onboarding Account Usage Document Images API
  version: v1
servers:
- url: /onboarding
  description: Relative URL
- url: https://api.currencycloud.com/onboarding
  description: Production server (uses live data)
- url: https://devapi.currencycloud.com/onboarding
  description: Dev server (uses test data)
tags:
- name: Document Images
paths:
  /v1/forms/{form_id}/documents/{document_id}/document_images:
    post:
      summary: Create Document Image
      description: Records an image of a document that's required for the specified application form. For more information, see the "Uploading documents" section of <a href="../guides/integration-guides/onboarding-api-pilot">our guide.</a>
      tags:
      - Document Images
      x-api-group: Onboard
      security:
      - AuthToken: []
      parameters:
      - name: form_id
        description: Form UUID
        in: path
        required: true
        schema:
          type: string
      - name: document_id
        in: path
        description: Document UUID
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Document image attached
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/document_image'
        '422':
          description: Form is already submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validation_error_response'
        '404':
          description: Document not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/not_found_response'
        '400':
          description: Invalid side in request params
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_document_image_request'
    get:
      summary: Get Document Images
      description: Returns all document images for the specified document.
      tags:
      - Document Images
      x-api-group: Onboard
      security:
      - AuthToken: []
      parameters:
      - name: form_id
        description: Form UUID
        in: path
        required: true
        schema:
          type: string
      - name: document_id
        in: path
        description: Document UUID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Retrieves document images
          content:
            application/json:
              schema:
                type: object
                properties:
                  document_images:
                    type: array
                    items:
                      $ref: '#/components/schemas/document_image'
        '404':
          description: Document image not found with incorrect form id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/not_found_response'
  /v1/forms/{form_id}/documents/{document_id}/document_images/{document_image_id}:
    delete:
      summary: Delete Document Image
      description: Deletes the specified image of a document attached to the specified form.
      tags:
      - Document Images
      x-api-group: Onboard
      security:
      - AuthToken: []
      parameters:
      - name: form_id
        description: Form UUID
        in: path
        required: true
        schema:
          type: string
      - name: document_id
        in: path
        description: Document UUID
        required: true
        schema:
          type: string
      - name: document_image_id
        description: Document Image UUID.
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deletes the document image
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                      document_image_id:
                        description: Document Image UUID.
                        type: string
                    required:
                    - message
                    - document_image_id
        '422':
          description: Form is already submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validation_error_response'
        '404':
          description: Document image not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/not_found_response'
components:
  schemas:
    document_image:
      type: object
      properties:
        id:
          type: string
          description: Document image UUID.
        side:
          type: string
          description: Image of which document side.
        created_at:
          description: Date the document image entity was created.
          type: string
          format: date-time
        updated_at:
          description: Date the document image entity was last updated.
          type: string
          format: date-time
    not_found_response:
      type: object
      properties:
        status:
          type: string
        error_code:
          type: string
        reason:
          type: string
        error_messages:
          type: object
          nullable: true
      required:
      - status
      - error_code
      - reason
      - error_messages
    validation_error_response:
      type: object
      properties:
        status:
          type: string
        error_code:
          type: string
        reason:
          type: string
        error_messages:
          type: object
      required:
      - status
      - error_code
      - reason
      - error_messages
    create_document_image_request:
      type: object
      properties:
        image:
          description: Image encoder used e.g. base64.
          type: string
          format: byte
        side:
          description: Image of which document side.
          type: string
          enum:
          - front
          - back
          - face
      required:
      - image
      - side
  securitySchemes:
    AuthToken:
      type: apiKey
      in: header
      name: X-Auth-Token