Quickstart
Create an API key, copy a published pipeline's id, submit a document to it, and read the result back — without leaving your terminal.
You need a workspace with at least one published pipeline, and a role that can manage API keys. A new workspace starts empty — no pipelines, keys or documents are created for you. If you need a document to try, the Overview page offers a sample invoice and a sample mortgage statement to download. Every job you submit consumes credits.
1. Create an API key
In Studio, go to Settings → API Keys and choose Create key. Give the key a name and an expiry, keep the default pipeline access, and grant its scopes. The Run pipelines preset (jobs:write, jobs:read, pipeline:read, documents:read) covers everything in this quickstart. You can only grant scopes your own role holds.
The full key is shown once, when you save it. Copy it into your secret store now. Keys created in Studio start with idpf_live_.
# keep it out of your shell history
export IDP_API_KEY="idpf_live_••••••••••••••••"2. Copy the pipeline id
Open Pipelines, select the pipeline you want to run, and go to its Versions tab. The API endpoint card shows the endpoint URL and a ready-to-copy request with the pipeline's pipeline_id filled in. A pipeline with no published version has no live endpoint.
export PIPELINE_ID="<pipeline id from the API endpoint card>"3. Submit a document
A job is one file run through one pipeline. Post the file as multipart form data in a field named files, with the pipeline in pipeline_id. The call returns 202 Accepted as soon as the job is queued — processing is asynchronous.
curl -X POST https://api.us.idpforge.cloud/v1/jobs \
-H "X-API-Key: $IDP_API_KEY" \
-F "files=@Globex-INV-4471.pdf" \
-F "pipeline_id=$PIPELINE_ID"The response is an array with one entry per uploaded file:
[
{
"job_id": "01a08dcc-a671-7a63-a2e2-dec7c6ecbb38",
"status": "queued",
"execution_mode": "async",
"status_url": "https://api.us.idpforge.cloud/v1/jobs/01a08dcc-a671-7a63-a2e2-dec7c6ecbb38",
"result_url": "https://api.us.idpforge.cloud/v1/jobs/01a08dcc-a671-7a63-a2e2-dec7c6ecbb38?include=result",
"submitted_at": "2026-09-11T00:09:55.315027355Z"
}
]4. Read the result
Poll the job until it reaches a final status, or subscribe to a webhook and stop polling. Add include=result to get the output once the status is completed.
curl -X GET "https://api.us.idpforge.cloud/v1/jobs/$JOB_ID?include=result" \
-H "X-API-Key: $IDP_API_KEY"{
"job_id": "01a08dcc-a671-7a63-a2e2-dec7c6ecbb38",
"status": "completed",
"api_type": "extract",
"execution_mode": "async",
"priority": "standard",
"input": {
"file_name": "Globex-INV-4471.pdf",
"mime_type": "application/pdf",
"page_count": 1
},
"created_at": "2026-09-11T00:09:55.315027355Z",
"completed_at": "2026-09-11T00:11:09.399027355Z",
"total_time_taken_ms": 74084
}The sample is abridged. With include=result, a completed job also carries result: the extracted fields for a pipeline with an Extract stage, or a parse summary otherwise. A job that stops for human review sits at awaiting_review; every status is listed in Submit a job.
Jobs submitted with an API key appear on the Production tab of the Jobs page. Runs started from a pipeline's Test tab or the API Playground are tagged test and appear on the Test tab. Both kinds consume credits.
If the submission is rejected
| Status | error | What it means |
|---|---|---|
400 | MISSING_PART | No files field — the file was sent under another name, such as file. |
400 | PIPELINE_NOT_PUBLISHED | The pipeline has no published version. Publish it, or pin a version with pipeline_version. |
402 | PAYMENT_REQUIRED | The workspace does not have enough credits. No job was created. |
422 | UNSUPPORTED_FILE_TYPE | The file type is not accepted by the platform or by this pipeline. |