Docspeed Customer API docs
OpenAPI API Playground
Documentation /docs/extract

Extract

POST /v1/extract turns a PDF or image into structured JSON using an explicit Schema V2 contract.

The public request schema is:

{
  "input": {"file_id": "file_123"},
  "execution_mode": "sync",
  "grounding": "cell",
  "schema": {
    "doc_class": "invoice",
    "fields": [],
    "tables": []
  }
}

The public success response is an ExtractionResult envelope:

{
  "schema": {"doc_class": "invoice", "fields": [], "tables": []},
  "result": {},
  "grounding_mode": "regions",
  "page_count": 1
}

Async job results return the same endpoint payload from GET /v1/jobs/{job_id}/result.

Schema V2 example

{
  "doc_class": "invoice",
  "fields": [
    {
      "key": "invoice.invoice_number",
      "description": "Invoice identifier",
      "type": "string",
      "array": false
    },
    {
      "key": "invoice.invoice_date",
      "description": "Invoice date",
      "type": "string",
      "array": false
    },
    {
      "key": "supplier.GSTIN",
      "description": "Supplier GST registration number",
      "type": "string",
      "array": false
    },
    {
      "key": "tax.CGST_Amount",
      "description": "Central GST amount",
      "type": "number",
      "array": false
    },
    {
      "key": "tax.SGST_Amount",
      "description": "State GST amount",
      "type": "number",
      "array": false
    },
    {
      "key": "tax.IGST_Amount",
      "description": "Integrated GST amount",
      "type": "number",
      "array": false
    },
    {
      "key": "invoice.total_due",
      "description": "Final invoice amount due",
      "type": "number",
      "array": false
    }
  ],
  "tables": [
    {
      "key": "line_items",
      "description": "Invoice line items",
      "fields": [
        {
          "key": "description",
          "description": "Line item description",
          "type": "string",
          "array": false
        },
        {
          "key": "quantity",
          "description": "Billed quantity",
          "type": "number",
          "array": false
        },
        {
          "key": "unit_price",
          "description": "Unit price",
          "type": "number",
          "array": false
        },
        {
          "key": "amount",
          "description": "Line amount",
          "type": "number",
          "array": false
        },
        {
          "key": "HSN_Code",
          "description": "HSN or SAC classification code",
          "type": "string",
          "array": false
        }
      ]
    }
  ]
}

cURL

curl -sS -X POST "https://api.docspeed.ai/v1/extract" \
  -H "Authorization: Bearer ${DOCSPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d @extract-ap-invoice.json

extract-ap-invoice.json:

{
  "input": {"file_id": "file_gst_invoice"},
  "execution_mode": "sync",
  "grounding": "cell",
  "schema": {
    "doc_class": "invoice",
    "fields": [
      {"key": "invoice.invoice_number", "description": "Invoice identifier", "type": "string", "array": false},
      {"key": "supplier.GSTIN", "description": "Supplier GST registration number", "type": "string", "array": false},
      {"key": "tax.CGST_Amount", "description": "Central GST amount", "type": "number", "array": false},
      {"key": "tax.SGST_Amount", "description": "State GST amount", "type": "number", "array": false},
      {"key": "tax.IGST_Amount", "description": "Integrated GST amount", "type": "number", "array": false}
    ],
    "tables": [
      {
        "key": "line_items",
        "description": "Invoice line items",
        "fields": [
          {"key": "description", "description": "Line item description", "type": "string", "array": false},
          {"key": "HSN_Code", "description": "HSN or SAC classification code", "type": "string", "array": false}
        ]
      }
    ]
  }
}

Python

import requests

payload = {
    "input": {"file_id": "file_gst_invoice"},
    "execution_mode": "sync",
    "grounding": "cell",
    "schema": {
        "doc_class": "invoice",
        "fields": [
            {"key": "invoice.invoice_number", "description": "Invoice identifier", "type": "string", "array": False},
            {"key": "supplier.GSTIN", "description": "Supplier GST registration number", "type": "string", "array": False},
            {"key": "tax.CGST_Amount", "description": "Central GST amount", "type": "number", "array": False},
            {"key": "tax.SGST_Amount", "description": "State GST amount", "type": "number", "array": False},
            {"key": "tax.IGST_Amount", "description": "Integrated GST amount", "type": "number", "array": False},
        ],
        "tables": [
            {
                "key": "line_items",
                "description": "Invoice line items",
                "fields": [
                    {"key": "description", "description": "Line item description", "type": "string", "array": False},
                    {"key": "HSN_Code", "description": "HSN or SAC classification code", "type": "string", "array": False},
                ],
            }
        ],
    },
}

response = requests.post(
    "https://api.docspeed.ai/v1/extract",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=600,
)
response.raise_for_status()
print(response.json())

TypeScript

const response = await fetch("https://api.docspeed.ai/v1/extract", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: { file_id: "file_gst_invoice" },
    execution_mode: "sync",
    grounding: "cell",
    schema: {
      doc_class: "invoice",
      fields: [
        { key: "invoice.invoice_number", description: "Invoice identifier", type: "string", array: false },
        { key: "supplier.GSTIN", description: "Supplier GST registration number", type: "string", array: false },
        { key: "tax.CGST_Amount", description: "Central GST amount", type: "number", array: false },
        { key: "tax.SGST_Amount", description: "State GST amount", type: "number", array: false },
        { key: "tax.IGST_Amount", description: "Integrated GST amount", type: "number", array: false },
      ],
      tables: [
        {
          key: "line_items",
          description: "Invoice line items",
          fields: [
            { key: "description", description: "Line item description", type: "string", array: false },
            { key: "HSN_Code", description: "HSN or SAC classification code", type: "string", array: false },
          ],
        },
      ],
    },
  }),
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

Example response fragment

{
  "schema": {
    "doc_class": "invoice",
    "fields": [
      {
        "key": "supplier.GSTIN",
        "description": "Supplier GST registration number",
        "type": "string",
        "array": false
      }
    ],
    "tables": [
      {
        "key": "line_items",
        "description": "Invoice line items",
        "fields": [
          {
            "key": "HSN_Code",
            "description": "HSN or SAC classification code",
            "type": "string",
            "array": false
          }
        ]
      }
    ]
  },
  "result": {
    "fields": {
      "supplier.GSTIN": {
        "value": "29ABCDE1234F1Z5",
        "region_ids": ["p1_supplier_gstin"]
      }
    },
    "tables": {
      "line_items": [
        {
          "HSN_Code": {
            "value": "8471",
            "region_ids": ["p1_line_items_r1_hsn"]
          }
        }
      ]
    },
    "grounding_regions": [
      {
        "region_id": "p1_supplier_gstin",
        "page_index": 0,
        "shape": {"type": "bbox", "x": 120, "y": 240, "w": 180, "h": 28}
      }
    ],
    "pages": [
      {"page_index": 0, "width": 1200, "height": 1600}
    ]
  },
  "grounding_mode": "regions",
  "page_count": 1
}

Grounding values

  • grounding: "none" disables grounding.
  • grounding: "regions" asks for field evidence regions.
  • grounding: "cell" asks for table-cell-friendly grounding and is recommended for line-item review.

Schema files

For production systems that version schemas separately, upload a JSON schema file and pass schema_file_id instead of inline schema. Do not send both schema and schema_file_id in the same request.