> ## 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 an Intake

> Creates an intake from an uploaded file and processes it asynchronously. Intakes are split into segments.



## OpenAPI

````yaml POST /v2/intakes/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:
  /v2/intakes/scan/async:
    post:
      summary: Create an intake and scan it in the background
      description: >-
        Creates an intake from an uploaded file and processes it asynchronously.
        Intakes are split into segments.
      parameters: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/NewIntake'
      responses:
        '201':
          description: Intake created and queued. `scan_status` is `PENDING`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Intake'
              examples:
                pending:
                  summary: Initial response
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    external_id: candidate-123
                    client_reference: req-456
                    scan_status: PENDING
                    context:
                      first_name: Jane
                      last_name: Doe
                    split: null
                    validation: null
                    fraud: null
                    payloads: []
                    segments: []
                    error: null
                    file:
                      url: https://…
                      name: bls.pdf
                      mime_type: application/pdf
                    created_at: '2026-09-18T20:00:00.000Z'
                    updated_at: '2026-09-18T20:00:00.000Z'
        '400':
          description: >-
            Invalid request (e.g. missing `external_id`, unknown
            `validate.requirement`, source validation not enabled).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '413':
          description: File exceeds 20 MB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
components:
  schemas:
    NewIntake:
      type: object
      required:
        - external_id
        - file
      properties:
        file:
          type: string
          format: binary
          description: File to upload
        file_id:
          type: string
          description: ID of a previously uploaded file.
        external_id:
          type: string
          maxLength: 500
          description: UUID of document owner in your system.
        client_reference:
          type: string
          maxLength: 200
          description: Your file correlation ID. Stored and echoed.
        context:
          type: object
          description: >-
            Candidate, placement and/or requirement data relevant to validation.
            Can accept any key-value pairs.
          additionalProperties: true
          properties:
            first_name:
              type: string
            middle_name:
              type: string
            last_name:
              type: string
            date_of_birth:
              type: string
              format: date
        validate:
          type: object
          description: Used for performing validation on the document.
          properties:
            requirement:
              type: string
              description: Requirement key to validate against (e.g. `bls`, `covid`).
            placement_id:
              type: string
              description: Resolve per-requirement rules from this placement.
            requirement_id:
              type: string
              description: Fulfill exactly this requirement slot.
            broadcast:
              type: boolean
              description: >-
                Evaluate against every matching requirement on the candidate's
                placements.
            source:
              type: boolean
              description: Run source validation, if enabled on your account.
    Intake:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Intake ID.
        external_id:
          type: string
        client_reference:
          type: string
          nullable: true
        scan_status:
          type: string
          enum:
            - PENDING
            - SUCCESS
            - FAILED
        context:
          type: object
          nullable: true
          additionalProperties: true
        split:
          type: object
          nullable: true
          description: >-
            Page ranges after split. Null while still `PENDING` (before split
            has run).
          properties:
            page_count:
              type: integer
              nullable: true
            segments:
              type: array
              items:
                type: object
                properties:
                  index:
                    type: integer
                  page_start:
                    type: integer
                  page_end:
                    type: integer
        validation:
          type: object
          nullable: true
          description: Present when a requirement was sent on create.
          properties:
            requirement:
              type: string
            result:
              type: string
              nullable: true
              enum:
                - VALID
                - INVALID
                - NOT_SUPPORTED
            document_id:
              type: string
              format: uuid
              nullable: true
            validations:
              type: object
              nullable: true
              description: That segment's rule tree.
        fraud:
          type: object
          nullable: true
          description: >-
            Rollup over segments. Any fraudulent segment makes the intake
            fraudulent.
        segments:
          type: array
          items:
            $ref: '#/components/schemas/Segment'
        error:
          $ref: '#/components/schemas/IntakeError'
          description: Intake-level failure. Null unless `scan_status` is `FAILED`.
        file:
          $ref: '#/components/schemas/IntakeFile'
          description: The upload as received. Segment PDFs are on each segment's `file`.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          nullable: true
        deleted_at:
          type: string
          format: date-time
          description: Only present on a deleted intake.
    V2Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: >-
                Stable snake_case code, e.g. `invalid_request`, `unauthorized`,
                `not_found`, `unknown_requirement`, `file_required`,
                `file_too_large`, `source_validation_disabled`,
                `unsupported_file`.
            message:
              type: string
            details:
              nullable: true
    Segment:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Document ID.
        intake_id:
          type: string
          format: uuid
        index:
          type: integer
          description: 0-based page order.
        page_start:
          type: integer
          nullable: true
        page_end:
          type: integer
          nullable: true
        document_type:
          type: string
          nullable: true
        document_category:
          type: string
          nullable: true
        schema_id:
          type: string
          nullable: true
        fields:
          type: object
          nullable: true
          description: Extracted fields for this document type.
        derived_fields:
          type: object
          nullable: true
        external_fields:
          type: object
          nullable: true
        validation_result:
          type: string
          nullable: true
          enum:
            - VALID
            - INVALID
            - NOT_SUPPORTED
          description: >-
            Null for segments that are not candidates for the requested
            requirement.
        validations:
          type: object
          nullable: true
        attestations:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              type:
                type: string
              created_at:
                type: string
                format: date-time
              file:
                type: object
                nullable: true
                properties:
                  url:
                    type: string
        expires_at:
          type: string
          format: date
          nullable: true
        redacted_at:
          type: string
          format: date-time
          nullable: true
        scan_status:
          type: string
          enum:
            - PENDING
            - SUCCESS
            - FAILED
        fraud:
          type: object
          nullable: true
          properties:
            result:
              type: string
              enum:
                - clean
                - fraudulent
            score:
              type: number
              nullable: true
        error:
          $ref: '#/components/schemas/IntakeError'
        file:
          $ref: '#/components/schemas/IntakeFile'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          nullable: true
    IntakeError:
      type: object
      nullable: true
      properties:
        code:
          type: string
        message:
          type: string
    IntakeFile:
      type: object
      nullable: true
      properties:
        url:
          type: string
          description: Presigned download URL.
        name:
          type: string
          nullable: true
        mime_type:
          type: string
          nullable: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````