Introduction

Quickstart

Choose your first integration path and make your first calls

Most integrations start with one of three flows:

Extract fields from a document

Upload a file, submit it to Document Insights, and read structured extraction output.

Start a workflow

Trigger a workflow configured in Plextera Studio and monitor the run.

Receive events

Subscribe to webhooks so Plextera pushes terminal state changes to your application.

Before you start

Every flow requires an API key. See Authentication.

For the Document Insights flows, you also need:

  • A Document Insights configuration in your workspace that supports the document you will submit.
  • The expected output fields for that configuration.
  • The exact docType configured in Plextera, if your workspace uses document-type routing. Retrieve it from the relevant Document Insights configuration; if you do not know where to find it, ask your workspace administrator or Plextera.

Document Insights does not choose an arbitrary output schema from each request. Your workspace configuration defines which documents match and which fields are returned. If your workspace has default routing, omit docType. See Configuration, routing, and output for details.

Flow 1: Extract fields and poll for output

Use this when your application can wait for the result by checking the API.

1

Upload a document

$curl -X POST https://api.plextera.com/api/public/v1/files \
>  -H "Authorization: api-key YOUR_API_KEY" \
>  -F "file=@invoice.pdf"

Save the returned id; this is the fileId used by later calls. See the Files guide for metadata, downloads via contentUrl, and upload constraints.

Some workspaces reject duplicate document content. When repeating this quickstart, continue polling the extraction you already created or use a different document instead of submitting the same file again.

2

Create an extraction

The example below assumes your workspace uses document-type routing. Replace YOUR_CONFIGURED_DOCUMENT_TYPE with the exact value configured in Plextera. If you do not know where to find it, ask your workspace administrator or Plextera. If your workspace uses default routing, omit only the docType entry. You can still send other labels for correlation; because this example has no other labels, you can omit the empty labels object.

$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" },
>    "labels": {
>      "docType": "YOUR_CONFIGURED_DOCUMENT_TYPE"
>    }
>  }'

docType is a routing value, not a value you invent. Other labels are optional identifiers you define for correlation; see Labels and docType.

The response is accepted asynchronously. Store the returned id; the API reference calls this extractionId.

1{
2  "id": "69654f0bc073ef404baec649",
3  "status": "QUEUED",
4  "outputAvailable": false
5}
3

Poll until terminal status

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

The initial QUEUED response is expected. Continue polling until status is COMPLETED, FAILED, or REJECTED:

  • COMPLETED - outputAvailable is true and the response includes the configured fields in output.fields.
  • REJECTED - inspect error.message; correct document-level problems such as duplicate content or an unsupported language before retrying.
  • FAILED - inspect error.code. Correct routing when it is DOCUMENT_NOT_ROUTED, or retry with backoff when processing may have failed temporarily.

See Handle failures for duplicate documents, routing failures, retry guidance, and the information to provide to support.

Flow 2: Extract fields and receive an event

Use this when your application has a webhook endpoint and should not poll.

1

Create an event subscription

$curl -X POST https://api.plextera.com/api/public/v1/event-subscriptions \
>  -H "Authorization: api-key YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "name": "Document extraction events",
>    "endpointUrl": "https://example.com/webhooks/plextera",
>    "eventTypes": [
>      "document-insights.extraction.completed",
>      "document-insights.extraction.failed",
>      "document-insights.extraction.rejected"
>    ]
>  }'

The 201 Created response contains a server-generated signingSecret. Save it securely because ordinary subscription responses do not contain it and the Public API has no reveal endpoint.

2

Create an extraction

Submit the document the same way as Flow 1. When processing reaches a terminal state, Plextera sends an event to your endpointUrl.

3

Verify and process the webhook

Verify the X-Plextera-Signature header before trusting the payload. For document-insights.extraction.completed, the event payload includes the completed extraction and its output.

If events do not arrive, start with GET /events to confirm that Plextera created the event. Then use GET /events/{eventId}/deliveries to inspect its deliveries and GET /events/{eventId}/deliveries/{deliveryId} for the payload and individual HTTP attempts. See Inspect events.

Flow 3: Start a workflow

Use this when the workflow is already configured in Plextera Studio and your application only needs to trigger it. Replace invoice-processing with the published workflow identifier provided for your integration.

$curl -X POST https://api.plextera.com/api/public/v1/workflows/invoice-processing/runs \
>  -H "Authorization: api-key YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "document": { "fileId": "file_01JY7M4ZVX5R1P3M3Q0TA1S7ZM" },
>    "customerId": "customer-42"
>  }'

Then either poll GET /workflow-runs/{runId} or subscribe to workflow.run.completed and workflow.run.failed.

When to use polling vs events

PatternUse when
PollingYou are building a simple integration, a batch worker, or a backend process that can periodically check status.
EventsYou need near-real-time processing, lower API traffic, or a clean handoff once processing completes.
BothYou want webhooks for normal operation and polling as a recovery path if a delivery is missed or delayed.

Next steps

  • Document Extraction - detailed extraction flow, output model, feedback, and polling guidance
  • Workflow Runs - start workflows with JSON or multipart form-data
  • Event Subscriptions - webhook setup, signatures, retries, and event payloads
  • Errors - error envelope, code table, and retry guidance
  • API Reference - full endpoint reference with interactive examples