IDPForgeDocs
Open app
Docs/API reference/Submit a job
Reference

Submit a job

Create a job by posting one or more files to a published pipeline. Processing is asynchronous; the response returns as soon as the submission is durable.

Request ​

POST/v1/jobsRequires jobs:write

Send multipart/form-data when uploading bytes, or application/json when referencing a file already in a connected storage bucket.

ParameterTypeDescription
pipeline_id (required)stringId of a published pipeline. Unpublished pipelines are rejected.
file (required)filePDF, TIFF, PNG, JPEG or DOCX. Repeat the field for a batch.
versionstringPin to a specific pipeline version. Defaults to latest published.
source_tagstringStamped onto the job for filtering in Jobs and Insights.
metadataobjectUp to 20 key/value pairs, echoed on every resulting document.
run_kindenumprod (default) or test. Test runs never deliver to destinations.
bash
curl https://api.idpforge.ai/v1/jobs \
  -H "X-API-Key: $IDP_API_KEY" \
  -H "Idempotency-Key: 8f2a-4c81-e6b7" \
  -F "pipeline_id=std-invoice" \
  -F "source_tag=ap-inbox" \
  -F "file=@Globex-INV-4471.pdf"
python
job = client.jobs.create(
    pipeline_id="std-invoice",
    source_tag="ap-inbox",
    metadata={"cost_center": "4420"},
    file=open("Globex-INV-4471.pdf", "rb"),
    idempotency_key="8f2a-4c81-e6b7",
)
ts
const job = await idp.jobs.create({
  pipelineId: "std-invoice",
  sourceTag: "ap-inbox",
  metadata: { costCenter: "4420" },
  file: fs.createReadStream("Globex-INV-4471.pdf"),
}, { idempotencyKey: "8f2a-4c81-e6b7" });
json
// 202 Accepted
{
  "id": "job_8H2K3FQ",
  "status": "processing",
  "stage_now": "init",
  "pipeline": {
    "id": "std-invoice",
    "version": "v7"
  },
  "documents": 1,
  "source_tag": "ap-inbox",
  "created_at": "2026-07-29T06:12:44Z"
}

Credits ​

Submitting a job reserves credits before it is queued. If the workspace balance is too low, the submission is rejected with 402 Payment Required and no job is created. On success the reservation settles to the actual cost and the remainder is released; a failed job releases its whole reservation. See Credits.

Job status ​

GET/v1/jobs/{job_id}Requires jobs:read

A job moves through a small state machine. Documents inside it have their own, richer lifecycle — a job can be completed while its documents sit in_review.

StatusMeaning
processingAt least one stage is still running. stage_now is populated.
completedEvery stage finished. Check documents for review state.
failedA stage errored. failed_stage and error are populated.
cancelledCancelled before completion via POST /v1/jobs/{id}/cancel.
json
{
  "id": "job_8H2K3FQ",
  "status": "completed",
  "machine_seconds": 74,
  "trace": [
    { "stage": "init",          "ms": 1204, "ok": true },
    { "stage": "splitclassify", "ms": 8810, "ok": true },
    { "stage": "extract",       "ms": 51402, "ok": true },
    { "stage": "validate",      "ms": 612,  "ok": false }
  ],
  "documents": [
    { "id": "DOC-100245", "status": "in_review" }
  ]
}
Was this page helpful?
← Previous · API reference
API overview
Last updated 19 Aug 2026