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

# Create a Document Scan

> Asynchronously scan a document using form-data upload



## OpenAPI

````yaml POST /document/scan/async
openapi: 3.0.1
info:
  title: Ready Health API
  description: ''
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.readyhealth.com
security:
  - ApiKeyAuth: []
paths:
  /document/scan/async:
    post:
      description: Asynchronously scan a document using form-data upload
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/NewScan'
        required: true
      responses:
        '201':
          description: The document is pending processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResponse'
              examples:
                Initial response:
                  summary: Initial response
                  value:
                    id: '123'
                    scanStatus: PENDING
                    fields: null
                    validations: null
                Completed scan:
                  summary: Completed scan
                  value:
                    id: '123'
                    scanStatus: SUCCESS
                    fields: {}
                    validations: {}
components:
  schemas:
    NewScan:
      required:
        - external_id
        - file
      type: object
      properties:
        external_id:
          description: UUID of the document owner
          type: string
          format: uuid
        file:
          description: The document as a binary file stream
          type: string
          format: binary
        validation:
          description: >-
            If set to `true`, a contextually relevant set of validations will be
            returned. Default is set to `false` and will not return any
            validations.
          type: boolean
        context:
          description: 'These fields are required only if `validation: true`.'
          type: object
          properties:
            first_name:
              description: ''
              type: string
            middle_name:
              description: ''
              type: string
            last_name:
              description: ''
              type: string
            date_of_birth:
              description: Format of YYYY-MM-DD
              type: string
              format: date
            requirement:
              description: >-
                The name of the requirement, for examples `hepatitis_b`,
                `covid`, `tuberculosis`, etc. These relate to document category,
                with the exception of aggregated category (e.g. `immunization`)
                which is not a valid requirement. [Refer
                here](https://docs.readyhealth.com/guides/mapping) for more
                information.
              type: string
            source_validation:
              description: When enabled, validates against the primary source.
              type: boolean
    ScanResponse:
      type: object
      properties:
        id:
          description: ''
          type: string
        externalUser:
          description: Candidate information
          type: object
          properties:
            externalId:
              description: ''
              type: string
              format: uuid
            createdAt:
              description: ''
              type: string
              format: date-time
            updatedAt:
              description: ''
              type: string
              format: date-time
            deletedAt:
              description: ''
              type: string
              format: date-time
        validationResult:
          description: One of `VALID` or `INVALID`
          type: string
        scanStatus:
          description: One of `PENDING`, `IN_PROGRESS`, `FAILED` or `SUCCESS`.
          type: string
        createdAt:
          description: ''
          type: string
          format: date-time
        updatedAt:
          description: ''
          type: string
          format: date-time
        deletedAt:
          description: ''
          type: string
          format: date-time
        fields:
          description: >-
            See the [document field
            schema](https://docs.readyhealth.com/guides/schema) for the
            attributes to expect once the latest scan is complete.
          type: object
        validations:
          description: >-
            See the [document validations
            schema](https://docs.readyhealth.com/guides/validations) for the
            objects to expect once the latest validation is complete.
          type: object
        tasks:
          description: ''
          type: object
          properties:
            id:
              description: ''
              type: string
            actionType:
              description: One of `SCAN` or `FIELD_VALIDATION`
              type: string
            status:
              description: One of `PENDING`, `IN_PROGRESS`, `FAILED` or `SUCCESS`.
              type: string
            startedAt:
              description: ''
              type: string
              format: date-time
            completedAt:
              description: ''
              type: string
              format: date-time
            createdAt:
              description: ''
              type: string
              format: date-time
            updatedAt:
              description: ''
              type: string
              format: date-time
            deletedAt:
              description: ''
              type: string
              format: date-time
            error:
              description: Description of the error
              type: string
            result:
              description: The resulting fields retrieved from this scan.
              type: object
        file:
          type: object
          properties:
            id:
              description: File identifier.
              type: string
              format: uuid
            originalName:
              description: Original file name of the document uploaded.
              type: string
            mimeType:
              description: MIME type of the file.
              type: string
            url:
              description: >-
                Presigned URL to download the file expiring in 1 hour from
                creation.
              type: string
        context:
          type: object
          properties:
            first_name:
              description: ''
              type: string
            middle_name:
              description: ''
              type: string
            last_name:
              description: ''
              type: string
            date_of_birth:
              description: Format of YYYY-MM-DD
              type: string
              format: date
            requirement:
              description: ''
              type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````