Document Extraction

Use Document Insights to submit a document, extract structured fields, and retrieve the result. Extractions are asynchronous: Plextera accepts the document first, then returns output when processing is complete.

Before you start

You need:

• An API key. See Authentication.
• A document source: an existing fileId, an HTTPS document URL, or a file sent in the extraction request.
• Optional tags for correlation data you want Plextera to return with the extraction.

Tags and docType

Tags are optional string key-value pairs. Use them for values from your system, such as a case id, customer document id, or source system.

1
{
2
  "tags": {
3
    "customerDocumentId": "lab-42",
4
    "sourceSystem": "patient-portal"
5
  }
6
}

docType is a reserved tag. Send it only when Plextera has configured document-type routing for your workspace.

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

Integration flow

The complete extraction flow has three conceptual steps:

1. Upload a file.
2. Create an extraction.
3. Get the data.

Depending on how you submit the document, the first two steps can be separate or combined.

$
curl 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
  "name": "lab-result.pdf",
4
  "mimeType": "application/pdf",
5
  "sizeBytes": 63877
6
}

$
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"
>
    },
>
    "tags": {
>
      "customerDocumentId": "lab-42",
>
      "docType": "lab-result"
>
    }
>
  }'

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
    "docType": "lab-result"
10
  },
11
  "document": {
12
    "fileId": "file_01JY7M4ZVX5R1P3M3Q0TA1S7ZM",
13
    "fileName": "lab-result.pdf",
14
    "mimeType": "application/pdf"
15
  }
16
}

Submission shortcuts

Step 1 and Step 2 can be combined when you do not need a separate file upload call.

$
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": {
>
      "url": "https://example.com/documents/lab-result.pdf",
>
      "fileName": "lab-result.pdf"
>
    },
>
    "tags": {
>
      "customerDocumentId": "lab-42"
>
    }
>
  }'

Get extraction data

There are two recommended ways to receive extraction output.

Option 1: Poll for output

Call GET /document-insights/extractions/{extractionId} until the extraction reaches COMPLETED, FAILED, or REJECTED.

$
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 output.fields contains the extracted field values.

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

Option 2: Receive events

Create an event subscription if you want Plextera to send the result to your endpoint instead of polling.

Recommended event types:

• document-insights.extraction.completed
• document-insights.extraction.failed
• document-insights.extraction.rejected

For completed extractions, the event payload includes the same completed extraction model as GET /document-insights/extractions/{extractionId}, including output.

See Event Subscriptions for setup, headers, signatures, and retry behavior.

List extraction history

Use GET /document-insights/extractions to review recent extractions or build a status view.

$
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"

Use the list endpoint for history and status checks. Use GET /document-insights/extractions/{extractionId} when you need the full output for one extraction.

Submit feedback

Use feedback when an extracted value is incorrect or the extraction needs review.

$
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 '{
>
    "fieldId": "field_03",
>
    "type": "ERROR",
>
    "message": "Collection date should be 2026-04-05."
>
  }'

message is required and can contain up to 1024 characters. fieldId is optional; include it when feedback applies to one extracted field.

Related reference

• Document Insights API
• Event Reference