Documentation / API overview

Extract

Select the data you need from one or more documents.

Specify what to extract

Extract focuses on selected information rather than returning the entire document. Supply the documents and identify the fields or content your application needs.

Example use cases

• Vendor names and totals from invoices.
• Specific figures from financial reports.
• Selected information from a collection of documents.

Request and response

Proposed API contract

Use a JSON Schema to describe the data to extract. This example requests a vendor name and invoice total from two files. Results retain the source file reference so your application can associate each record with its document.

curl https://api.moda.app/v1/documents/extract \
  -H "Authorization: Bearer $MODA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "file_refs": [
    "file_invoice_001",
    "file_invoice_002"
  ],
  "schema": {
    "type": "object",
    "properties": {
      "vendor": {
        "type": [
          "string",
          "null"
        ]
      },
      "total": {
        "type": [
          "number",
          "null"
        ]
      }
    },
    "required": [
      "vendor",
      "total"
    ]
  }
}'

The request starts a job. Poll the returned poll_url until the status is completed or failed. See the shared job lifecycle.

{
  "id": "job_extract_example",
  "status": "completed",
  "result": {
    "documents": [
      {
        "file_ref": "file_invoice_001",
        "data": {
          "vendor": "Acme",
          "total": 1240
        }
      },
      {
        "file_ref": "file_invoice_002",
        "data": {
          "vendor": "Northstar",
          "total": 860
        }
      }
    ],
    "warnings": []
  }
}

Fields

file_refs

One or more uploaded document references.

schema

A JSON Schema describing the selected fields and their types.

result.documents

One extraction result per source document.

documents[].data

The selected data, using the requested field names.

Nullable fields

Allow null when a requested value may not be present.

Example workflow

1. Provide a set of invoices.
2. Select vendor name and invoice total as the information to extract.
3. Use the returned data in your application’s invoice workflow.

Extract or Parse?

Choose Extract when your task is defined by the information you need. Choose Parse when you want the full document representation for your own processing, or Index when you need to search or question an archive rather than pull known fields from known files.