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

# Create a document from an uploaded file

> Ingest a file uploaded via `POST /documents/upload-urls` as a DRAFT document. Name `documentType` (RECEIPT, REIMBURSEMENT, BILL, or INVOICE) when you know it and it is kept over the classifier's guess; omit it and the document lands unsorted for the classifier to name. When all you know is the direction, `uploadContext` (`money_out` / `money_in`) leans the classifier that way without settling anything — the document's own evidence still decides. AI extraction fills the type, amount, dates, counterparty, and line items in the background, guided by any details provided; bills and invoices then also get their draft accrual journal entry. Re-read the document until `aiExtractionPending` is false. Idempotent on `uploadKey` — retries return the same document.



## OpenAPI

````yaml /openapi.json post /api/documents/ingest
openapi: 3.1.0
info:
  title: Equated API
  version: 1.0.0
  description: >-
    Agent-facing accounting API. Authenticate with a bearer token issued from
    Settings → API Tokens, or via the in-app session cookie when called from the
    web client.
servers:
  - url: https://app.equated.co
    description: API server
security: []
paths:
  /api/documents/ingest:
    post:
      tags:
        - Documents
      summary: Create a document from an uploaded file
      description: >-
        Ingest a file uploaded via `POST /documents/upload-urls` as a DRAFT
        document. Name `documentType` (RECEIPT, REIMBURSEMENT, BILL, or INVOICE)
        when you know it and it is kept over the classifier's guess; omit it and
        the document lands unsorted for the classifier to name. When all you
        know is the direction, `uploadContext` (`money_out` / `money_in`) leans
        the classifier that way without settling anything — the document's own
        evidence still decides. AI extraction fills the type, amount, dates,
        counterparty, and line items in the background, guided by any details
        provided; bills and invoices then also get their draft accrual journal
        entry. Re-read the document until `aiExtractionPending` is false.
        Idempotent on `uploadKey` — retries return the same document.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                uploadKey:
                  type: string
                  minLength: 1
                  description: uploadKey from the presign step, after the PUT succeeded.
                documentType:
                  type: string
                  enum:
                    - RECEIPT
                    - BILL
                    - INVOICE
                    - REIMBURSEMENT
                  description: >-
                    Which kind of document this is, when the caller knows.
                    Preserved over the AI classifier's own guess; omit it and
                    the classifier decides.
                uploadContext:
                  type: string
                  enum:
                    - money_in
                    - money_out
                  description: >-
                    Which side of the books the file came from when the caller
                    knows only that: money_out (the business pays) or money_in
                    (the business is owed). A weak prior for the classifier,
                    which the document's own evidence and a named documentType
                    both outrank.
                counterpartyName:
                  type: string
                  minLength: 1
                  maxLength: 200
                  description: Vendor (receipt/bill) or customer (invoice) the user named.
                amount:
                  type: string
                  pattern: ^\d+(\.\d+)?$
                  description: Grand total the user stated, in currency.
                currency:
                  type: string
                  enum:
                    - CAD
                    - USD
                    - EUR
                    - GBP
                    - AUD
                  description: ISO currency the user stated. Omit to let extraction decide.
                documentDate:
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}$
                  description: Receipt/issue date printed on the document.
                note:
                  type: string
                  minLength: 1
                  maxLength: 2000
                  description: Any other context the user gave about this document.
              required:
                - uploadKey
      responses:
        '201':
          description: Ingested document
          content:
            application/json:
              schema:
                type: object
                properties:
                  document:
                    $ref: '#/components/schemas/Document'
                required:
                  - document
      security:
        - bearerAuth: []
components:
  schemas:
    Document:
      type: object
      properties:
        id:
          type: integer
          minimum: 0
          exclusiveMinimum: true
        documentType:
          type: string
        lifecycle:
          type: string
        amount:
          type: string
          nullable: true
        currency:
          type: string
          nullable: true
        displayTitle:
          type: string
          nullable: true
        documentNumber:
          type: string
          nullable: true
        dueDate:
          type: string
          nullable: true
        createdAt:
          type: string
        orgMerchantId:
          type: integer
          nullable: true
          minimum: 0
          exclusiveMinimum: true
        orgMerchant:
          type: object
          nullable: true
          properties:
            id:
              type: integer
              minimum: 0
              exclusiveMinimum: true
            name:
              type: string
            website:
              type: string
              nullable: true
            imageUrl:
              type: string
              nullable: true
            logo:
              type: string
              nullable: true
          required:
            - id
            - name
            - website
            - imageUrl
            - logo
          additionalProperties:
            nullable: true
        amountBase:
          type: string
          nullable: true
        baseCurrency:
          type: string
          nullable: true
        derivedSettlementStatus:
          $ref: '#/components/schemas/SettlementStatus'
        derivedOutstandingAmount:
          type: string
          nullable: true
          description: Unapplied balance in the document currency.
        payerAccountId:
          type: integer
          nullable: true
          minimum: 0
          exclusiveMinimum: true
          description: >-
            Reimbursement liability/equity payer account; retained on unconfirm
            and null until selected.
        resolution:
          type: string
          nullable: true
          enum:
            - unresolved
            - matched
            - null
          description: >-
            Receipts only: unresolved (not linked to a transaction) or matched
            (linked to one); null for other document types.
      required:
        - id
        - documentType
        - lifecycle
        - amount
        - currency
        - displayTitle
      additionalProperties:
        nullable: true
    SettlementStatus:
      type: string
      enum:
        - open
        - partially_closed
        - closed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API token issued from the Equated app under Settings → API Tokens.

````