Document Extraction

Document Insights extracts structured field values from a document. The flow is asynchronous: you submit a document, receive an extraction ID, then read the result once processing finishes.

A typical integration looks like this:

1. Submit a document.
2. Poll or subscribe for the terminal state.
3. Read the output.
4. Optionally submit feedback.

All requests require an API key in the Authorization header. See Authentication for how to obtain and send one.

Submit a document

Choose one of two submission styles, depending on whether you want to manage the file separately.

Option A: Extract from a file or URL

Use this when the document already lives in Plextera File Service or is reachable at an HTTPS URL. This is also the right choice when you want a reusable fileId you can extract from more than once.

$
# 1. Upload the file
$
curl -X POST https://api.plextera.com/api/public/v1/files \
>
  -H "Authorization: api-key YOUR_API_KEY" \
>
  -F "file=@lab-result.pdf"

1
{
2
  "id": "file_01JY7M4ZVX5R1P3M3Q0TA1S7ZM",
3
  "fileName": "lab-result.pdf",
4
  "mimeType": "application/pdf",
5
  "sizeBytes": 63877
6
}

$
# 2. Start the extraction
$
curl -X POST https://api.plextera.com/api/public/v1/document-insights/extractions \
>
  -H "Authorization: api-key YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "document": {
>
      "fileId": "file_01JY7M4ZVX5R1P3M3Q0TA1S7ZM"
>
    }
>
  }'

Option B: Upload and extract in one request

Use this when you do not need a reusable fileId and want a single round trip. Send the file as multipart/form-data to POST /document-insights/extractions/upload.

$
curl -X POST https://api.plextera.com/api/public/v1/document-insights/extractions/upload \
>
  -H "Authorization: api-key YOUR_API_KEY" \
>
  -F "file=@lab-result.pdf" \
>
  -F 'tags={"customerDocumentId":"lab-42"};type=application/json'

The file part is required. The optional tags part is a JSON object with string values.

What you get back

Every submission method returns the same extraction object, accepted asynchronously with status QUEUED.

1
{
2
  "id": "69654f0bc073ef404baec649",
3
  "status": "QUEUED",
4
  "outputAvailable": false,
5
  "createdAt": "2026-04-07T10:05:04Z",
6
  "updatedAt": "2026-04-07T10:05:04Z",
7
  "tags": {
8
    "customerDocumentId": "lab-42"
9
  },
10
  "document": {
11
    "fileId": "file_01JY7M4ZVX5R1P3M3Q0TA1S7ZM",
12
    "fileName": "lab-result.pdf",
13
    "mimeType": "application/pdf"
14
  }
15
}

All timestamps in extraction responses are UTC ISO 8601 strings, for example 2026-04-07T10:22:00Z.

Tags and docType

Both submission methods accept optional tags: string key-value pairs that Plextera returns on every response and event for the extraction. Use them to correlate results with records in your own system, such as a case ID or source system.

1
{
2
  "document": {
3
    "fileId": "file_01JY7M4ZVX5R1P3M3Q0TA1S7ZM"
4
  },
5
  "tags": {
6
    "customerDocumentId": "lab-42",
7
    "sourceSystem": "patient-portal"
8
  }
9
}

docType is a reserved tag that drives document-type routing. Only send it when Plextera has configured routing for your workspace; otherwise omit it.

1
{
2
  "tags": {
3
    "customerDocumentId": "lab-42",
4
    "docType": "lab-result"
5
  }
6
}

You can attach up to 50 tags. Keys are limited to 64 characters and values to 512 characters; keys and values must be non-empty after trimming.

Get the result

An extraction moves through one of these lifecycles:

COMPLETED, FAILED, and REJECTED are terminal. You can receive the result by polling or by subscribing to events.

Poll for output

Call GET /document-insights/extractions/{extractionId} until the status is terminal. A reasonable cadence: poll every 2–5 seconds for the first minute, then back off to every 15–30 seconds. Most documents finish within a couple of minutes; large or multi-page documents can take longer.

$
curl https://api.plextera.com/api/public/v1/document-insights/extractions/69654f0bc073ef404baec649 \
>
  -H "Authorization: api-key YOUR_API_KEY"

When status is COMPLETED, outputAvailable is true and the response carries the output object. When status is FAILED or REJECTED, it carries an error object instead.

Read the output

A completed extraction returns output.fieldCount and an output.fields array. Each field carries its extracted value plus extraction details such as confidence, page, and placement.

1
{
2
  "id": "69654f0bc073ef404baec649",
3
  "status": "COMPLETED",
4
  "outputAvailable": true,
5
  "createdAt": "2026-04-07T10:05:04Z",
6
  "updatedAt": "2026-04-07T10:22:00Z",
7
  "completedAt": "2026-04-07T10:22:00Z",
8
  "document": {
9
    "fileId": "file_01JY7M4ZVX5R1P3M3Q0TA1S7ZM",
10
    "fileName": "lab-result.pdf",
11
    "mimeType": "application/pdf",
12
    "sizeBytes": 63877,
13
    "pageCount": 1,
14
    "contentUrl": "https://files.plextera.com/acme/2026/04/07/lab-result_9f1c8b2e.pdf?Expires=1775900000&KeyName=cdn-key&Signature=Zm9vYmFyc2lnbmF0dXJl"
15
  },
16
  "output": {
17
    "fieldCount": 3,
18
    "fields": [
19
      {
20
        "id": "field_01",
21
        "name": "labName",
22
        "type": "text",
23
        "value": "Quest Diagnostics",
24
        "metadata": {
25
          "extracted": true,
26
          "confidence": 1.0,
27
          "page": 1,
28
          "placement": { "x": 43, "y": 12, "width": 22, "height": 4 }
29
        }
30
      }
31
    ]
32
  }
33
}

Each field’s id is what you pass as fieldId when submitting feedback. For the full field schema, see the API reference.

Download the source document

The document object carries file metadata plus contentUrl - a short-lived pre-signed link to download the original document straight from storage. This link is minted on each Get extraction request and expires, so fetch it promptly and don’t persist it; request the extraction again to get a fresh one. contentUrl is returned only by Get extraction (this endpoint), not by List extractions, and is omitted when the link cannot be resolved. The Files guide shows the same download pattern for files fetched by fileId.

Delete an extraction

Delete an extraction you no longer need with DELETE /document-insights/extractions/{extractionId}.

$
curl -X DELETE https://api.plextera.com/api/public/v1/document-insights/extractions/69654f0bc073ef404baec649 \
>
  -H "Authorization: api-key YOUR_API_KEY"

A successful delete returns 204 No Content. Only terminal extractions can be deleted - deleting one that is still QUEUED or PROCESSING returns 409 CONFLICT; wait for a terminal status first. Deletion is permanent: the extraction disappears from GET and list responses and from Plextera review tooling.

Handle failures

FAILED and REJECTED both return an error object with a machine-readable code and a human-readable message. The distinction matters when deciding whether to retry.

1
{
2
  "id": "69654f0bc073ef404baec649",
3
  "status": "REJECTED",
4
  "outputAvailable": false,
5
  "completedAt": "2026-04-07T10:05:20Z",
6
  "error": {
7
    "code": "DOCUMENT_REJECTED",
8
    "message": "The document was rejected."
9
  }
10
}

Receive events instead of polling

If your application exposes a webhook endpoint, subscribe to extraction events and let Plextera push the terminal result to you. The completed event payload contains the same extraction model returned by GET /document-insights/extractions/{extractionId}, including output.

Recommended event types:

• document-insights.extraction.completed includes output.
• document-insights.extraction.failed includes error.
• document-insights.extraction.rejected includes error.

See Event Subscriptions for endpoint setup, signature verification, and retry behavior.

List extractions

Use GET /document-insights/extractions to review history or build a status view. It returns a paged summary of each extraction without the full output, and the document summary here does not include the contentUrl download link. Fetch a single extraction by ID when you need the field values or a download link.

$
curl "https://api.plextera.com/api/public/v1/document-insights/extractions?status=COMPLETED&from=2026-04-01T00:00:00Z&to=2026-04-30T23:59:59Z&sortBy=createdAt&sort=desc" \
>
  -H "Authorization: api-key YOUR_API_KEY"

Filter by status, narrow by a from / to created-time window, and order with sortBy and sort. Results are paged with zero-based page and size, and every response includes a pageInfo object. See the API reference for the complete parameter list and defaults.

Filter by tags

Filter on the tags you submitted with each extraction using the tags[key]=value parameter. Use tags[key]= (empty value) to match extractions that have the tag, or tags[key]=value for an exact match. Multiple keys are combined with AND.

$
curl "https://api.plextera.com/api/public/v1/document-insights/extractions?tags[docType]=lab-result&tags[customerDocumentId]=lab-42" \
>
  -H "Authorization: api-key YOUR_API_KEY"

This returns extractions tagged docType=lab-result and customerDocumentId=lab-42. Tag filters combine with the other filters above.

Submit feedback

When an extracted value is wrong or needs review, submit feedback against the extraction. Feedback is surfaced to the team that configures your workspace and is used to improve extraction quality.

$
curl -X POST https://api.plextera.com/api/public/v1/document-insights/extractions/69654f0bc073ef404baec649/feedback \
>
  -H "Authorization: api-key YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "type": "ERROR",
>
    "fieldId": "field_01",
>
    "message": "Collection date should be 2026-04-05."
>
  }'

Related reference

• Document Insights API
• Event Reference