Quickstart | Plextera Public API

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.

Prerequisite - you have an API key. See Authentication.

Flow 1: Extract fields and poll for output

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

Upload a document

$ curl https://api.plextera.com/api/public/v1/files \
>   -H "Authorization: api-key YOUR_API_KEY" \
>   -F "file=@lab-result.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.

Create an extraction

Include docType only when Plextera has configured document-type routing for your workspace.

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

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 }

Poll until terminal status

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

Stop polling when status is COMPLETED, FAILED, or REJECTED. When outputAvailable is true, the response includes the final output.

Flow 2: Extract fields and receive an event

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

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 '{
>     "endpointUrl": "https://example.com/webhooks/plextera",
>     "eventTypes": [
>       "document-insights.extraction.completed",
>       "document-insights.extraction.failed",
>       "document-insights.extraction.rejected"
>     ],
>     "signingSecret": "whsec_your_secret"
>   }'

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.

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, inspect GET /event-subscriptions/{subscriptionId}/deliveries - it shows each delivery attempt, the HTTP response your endpoint returned, and the next scheduled retry. See Inspect deliveries.

Flow 3: Start a workflow

Use this when the workflow is already configured in Plextera Studio and your application only needs to trigger it.

$ curl -X POST https://api.plextera.com/api/public/v1/workflows/daily-lab-loader/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

Pattern	Use when
Polling	You are building a simple integration, a batch worker, or a backend process that can periodically check status.
Events	You need near-real-time processing, lower API traffic, or a clean handoff once processing completes.
Both	You 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