> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs.plextera.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.plextera.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.plextera.com/_mcp/server.

# Quickstart

Most integrations start with one of three flows:

#### [Extract fields from a document](/guides/core-guides/document-extraction)

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

#### [Start a workflow](/guides/core-guides/workflow-runs)

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

#### [Receive events](/guides/core-guides/event-subscriptions)

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

## Before you start

Every flow requires an API key. See [Authentication](/guides/introduction/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](/guides/core-guides/document-extraction#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.

### Upload a document

```bash
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](/guides/core-guides/files) 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.

### 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.

```bash
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](/guides/core-guides/document-extraction#labels-and-doctype).

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

```json
{
  "id": "69654f0bc073ef404baec649",
  "status": "QUEUED",
  "outputAvailable": false
}
```

### Poll until terminal status

```bash
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](/guides/core-guides/document-extraction#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.

### Create an event subscription

```bash
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.

### 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, 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](/guides/core-guides/event-subscriptions#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.

```bash
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

| 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](/guides/core-guides/document-extraction) - detailed extraction flow, output model, feedback, and polling guidance
* [Workflow Runs](/guides/core-guides/workflow-runs) - start workflows with JSON or multipart form-data
* [Event Subscriptions](/guides/core-guides/event-subscriptions) - webhook setup, signatures, retries, and event payloads
* [Errors](/guides/introduction/errors) - error envelope, code table, and retry guidance
* [API Reference](/api/api-reference) - full endpoint reference with interactive examples