Job Status & Polling

Every import on the Praedico Integration Platform is asynchronous. You submit a payload and get back a job, not a final result. The platform validates the request shape, queues your data, and applies it on a background worker. You then poll the job until it reaches a terminal state. This page is the reference for that lifecycle. The First Import Walkthrough shows it end-to-end with a real request.

Why asynchronous

Imports can be sizeable, and a single call may touch thousands of records. Processing them inline would mean long-held connections and request timeouts. Instead, the platform accepts your data quickly, returns a job you can track, and lets you check the outcome on your own schedule.

The lifecycle

1. Submit a payload to a resource endpoint. The platform checks the request shape only: well-formed JSON, required fields present, correct types.

2. Receive 202 Accepted with a job document. Your data is now queued, not yet applied. Keep the job id (or its statusUrl).

3. A background worker processes the job. Data-level rules run here, such as resolving the identifiers your records reference.

4. Poll GET /v2/status/{id} until the job reaches a terminal state.

The job document

A job looks like this:

{
  "id": 1234,
  "importJobType": "Asset",
  "importJobStatus": "Pending",
  "statusUrl": "/v2/status/1234",
  "output": null
}

• id — the job identifier; use it to poll.
• statusUrl — a ready-made path to poll, so you don’t have to build the URL.
• importJobType — the kind of import this job represents.
• importJobStatus — the current state (see below).
• output — null until the job finishes, then carries the result and any per-record errors.

Status values

importJobStatus	Meaning	What to do
Pending	Accepted and queued, not started	Keep polling
Processing	The worker is applying your data	Keep polling
Succeeded	All records applied	Done
PartiallySucceeded	Some records applied, some rejected	Read output.message; fix and re-submit the failed records
Failed	The job did not apply	Read output.message; fix and re-submit

Succeeded, PartiallySucceeded, and Failed are terminal — stop polling once you see one.

Polling guidance

Poll at a sensible interval, such as every few seconds, rather than in a tight loop. Back off for large jobs, and stop as soon as the status is terminal. Tight polling is itself a source of load and counts against your request throttling budget.

Reading the result

While a job is Pending or Processing, output is usually null. Once it reaches a terminal state, output.message carries the detail. For PartiallySucceeded and Failed jobs, this includes which records failed and why. Always read it on anything other than a clean Succeeded, and log it so failures are diagnosable later.

Re-submitting safely

Because imports are upserts, re-sending records is safe: applied records are updated in place, not duplicated. After a PartiallySucceeded or Failed job, fix the records named in output.message and submit them again. You don’t need to resend records that already succeeded.

Note

Request-shape problems are rejected synchronously, before you ever get a job. Problems that depend on other data surface in the job status. The distinction matters when you’re chasing an error — see Common Errors.