Use the PressCentric API to download customer accounts, read new jobs, check a job’s current status and submit catalog or one-off custom jobs to a print company.
For every value you send, it says where you get it. The source is one of three:
| Source | Meaning |
|---|---|
| Client API | You can read the value yourself with your credential. |
| Admin setup | An administrator of the print company reads the value in the PressCentric Back Office once and gives it to you. |
| Not yet available | Neither the client API nor a Back Office screen shows it. The known gaps section lists these. |
Every example in this guide is synthetic: the hosts, ids, names and references are invented. A real credential never appears in this guide; examples use $CREDENTIAL.
Walkthrough: a fresh test application and two test jobs (run in this order)#
This walkthrough takes you through these steps:
- Create a new test application.
- Start its job feed.
- Download the customers.
- Submit one catalog job and one custom job.
- Retry each submission and confirm that no duplicate was created.
- Read each job's status, find both jobs in the feed, and compare them with the Back Office.
- Revoke the test application.
- You need a Bash shell,
curlandjq, and a Back Office administrator login for the company. - The company must have the PressCentric API enabled: Pro edition and the PressCentric API module (section 1).
- Use only a synthetic test customer, in an environment where test orders are allowed. Both jobs become real orders of that customer.
- Each step says what to expect. If a response differs, stop at that step.
- Every call prints
HTTP <status> <content type>. Onlyapplication/jsonis an API answer (section 3).
Values the walkthrough needs#
| Value | Step | Source |
|---|---|---|
| Company host, credential | 0 | Admin setup: the application you create in step 0 |
customer.id |
3 | Client API: GET /customers |
product.id |
4 | Admin setup: Products list, ID column |
| Each job's details: quantity, purchase order, custom description, size, stock wording, colours | 5 | You choose them |
shipping.service, one per job |
5 | Client API: POST /jobs/shipping-rates, quoted for that job |
externalReference, one per job |
6 | You choose it |
Step 0 create a fresh test application#
In the Back Office, signed in as an administrator:
- Open Control Panel → System Settings → API Integrations.
- Choose New application.
- Application name: a name used only for this walkthrough, for example
API walkthrough test. - Permissions: select Read customer accounts, Read jobs and Submit new jobs.
- Choose Review access. Read the access summary and tick Grant … access to all storefronts and territories of ….
- Choose Grant access.
- The drawer shows the credential once. Copy it into your secret store, then choose Done.
Then set up the shell. The credential is read from the terminal, so it does not land in your shell history.
COMPANY_HOST="print.example.com" # the company's own PressCentric host, never a storefront domain
APP_NAME="API walkthrough test"
read -rs CREDENTIAL # paste the credential, then press Enter; nothing is echoed
API="https://$COMPANY_HOST/backoffice/next/api/client-api/v1"
AUTH="Authorization: Bearer $CREDENTIAL"
ok() { case "$1" in "200 application/json"*) return 0 ;; *) echo "STOP: HTTP $1"; return 1 ;; esac; }
Step 1 check the credential#
r=$(curl -sS -H "$AUTH" -H "Accept: application/json" -o credential.json \
-w '%{http_code} %{content_type}' "$API/credential"); echo "HTTP $r"
jq . credential.json
HTTP 200 application/json;nameequals$APP_NAME;hostequals$COMPANY_HOST;scopeslistscustomers.read,jobs.readandjobs.submit.
If you get an empty 401, check the credential and the host. If you get a 404, the host is not the company's own host, or the company does not have the PressCentric API enabled (section 1).
Step 2 start the job feed (before any submission)#
The feed delivers to an application only the tickets committed after its first GET /jobs (section 5). Make this call before submitting anything.
r=$(curl -sS -H "$AUTH" -H "Accept: application/json" -o feed-start.json \
-w '%{http_code} %{content_type}' "$API/jobs?limit=200"); echo "HTTP $r"; ok "$r"
jq . feed-start.json
FEED_START=$(jq -r '.next' feed-start.json); echo "FEED_START=$FEED_START"
Expect {"jobs": [], "next": <position>, "hasMore": false}. A fresh application always starts empty. Keep FEED_START.
Step 3 download the customers and pick the test customer#
This reads one complete scan, page by page (section 6).
: > customers.jsonl; CURSOR=""
while :; do
if [ -z "$CURSOR" ]; then
r=$(curl -sS -H "$AUTH" -H "Accept: application/json" -o customers-page.json \
-w '%{http_code} %{content_type}' "$API/customers?limit=500")
else
r=$(curl -sS -H "$AUTH" -H "Accept: application/json" -o customers-page.json --get \
--data-urlencode "after=$CURSOR" --data-urlencode "limit=500" \
-w '%{http_code} %{content_type}' "$API/customers")
fi
ok "$r" || { cat customers-page.json; break; }
jq -c '.items[]' customers-page.json >> customers.jsonl
[ "$(jq -r '.complete' customers-page.json)" = "true" ] && { jq -c '{complete, totalRows}' customers-page.json; break; }
CURSOR=$(jq -r '.nextCursor' customers-page.json)
done
wc -l < customers.jsonl
- the loop ends with
{"complete":true,"totalRows":N}; - the line count printed after it is also
N.
On 400 INVALID_CURSOR or 409 RESTART_SCAN, run the step again from the start.
Pick the synthetic test customer by its email:
TEST_EMAIL="walkthrough.customer@example.test" # the synthetic test customer's email
jq -c --arg e "$TEST_EMAIL" 'select(.customer.email == $e) | {id, enabled: .customer.enabled, company: .customer.company}' customers.jsonl
CUSTOMER_ID=$(jq -r --arg e "$TEST_EMAIL" 'select(.customer.email == $e and .customer.enabled) | .id' customers.jsonl)
echo "CUSTOMER_ID=$CUSTOMER_ID"
Expect exactly one line, with "enabled": true, and a numeric CUSTOMER_ID.
Step 4 get the product id#
In the Back Office, open Control Panel → Products & Pricing → Products. Show the ID column and pick an active catalog product that the test customer may order.
PRODUCT_ID=214 # replace with the product's ID
The walkthrough sends no size, options, proofingId or turnaroundId. The product's defaults and the company's default turnaround apply.
Step 5 build each job's details and get a shipping rate for it#
shipping.service must be a rate that the company's shipping setup offers for that job: its customer, product or custom specification, quantity and ship-to address. So you build each job's details first, ask for that job's rates with the test application's own credential, and choose one. Each job gets its own request.
The details are the job's final payload without externalReference and shipping.service. The rates are then quoted for exactly the job you will submit.
A quote is valid only for the address it was priced to.
- Without
shipping.address, the rates are priced to the customer's account address. Leave the address out of the details only if the submission also leaves it out, as the walkthrough does. - If a job ships to an explicit address, keep
"shipping": {"address": {…}}in its details, identical to the one you submit. Step 6 keeps it and adds only theservice. - Rates quoted to one address can differ for another, and the chosen
servicecan then be refused with422.
RUN=$(date -u +%Y%m%dT%H%M%SZ)
cat > catalog-details.json <<EOF
{"customer":{"id":$CUSTOMER_ID},"product":{"id":$PRODUCT_ID},"quantity":250,"purchaseOrder":"WT-$RUN-CAT","notifyCustomer":false}
EOF
cat > custom-details.json <<EOF
{"customer":{"id":$CUSTOMER_ID},"custom":{"description":"Walkthrough test card","finishedSize":{"width":5,"height":7,"unit":"in"},"stock":{"description":"Walkthrough test stock, no match"},"printing":{"front":4,"back":0}},"quantity":100,"purchaseOrder":"WT-$RUN-CUS","notifyCustomer":false}
EOF
jq -c . catalog-details.json custom-details.json
The custom job's stock wording deliberately matches no stock. The job is then held for stock selection and for pricing.
Define the rates helper. It sends a details file to POST /jobs/shipping-rates and lists the rates offered, numbered from 0. Asking for rates creates nothing (no order, job or submission), so it is always safe to ask again.
rates() { # usage: rates <details file> <name>
rm -f "$2-rates.json"
r=$(curl -sS --max-time 60 -X POST -H "$AUTH" -H "Accept: application/json" \
-H "Content-Type: application/json" --data-binary @"$1" -o "$2-rates.json" \
-w '%{http_code} %{content_type}' "$API/jobs/shipping-rates") || r="no-answer"
echo "$2 rates: HTTP $r"
case "$r" in
"200 application/json"*) ;;
"401 "*) echo "STOP: empty 401 - check the credential and the host"; return 1 ;;
"403 "*) echo "STOP: 403 - check the application's permissions (it needs Submit new jobs)"; return 1 ;;
"400 "*|"422 "*) echo "STOP: refused - fix the details"; cat "$2-rates.json"; echo; return 1 ;;
"4"*) echo "STOP: HTTP $r - shipping rates are not available on this host"; return 1 ;;
*) echo "no usable answer: run this again (asking for rates creates nothing)"; return 1 ;;
esac
jq -r '"currency: \(.currency)", (.rates | to_entries[]
| "[\(.key)] service=\(.value.service) \(.value.name) \(.value.carrier) \(.value.code) \(.value.amount)")' "$2-rates.json"
[ "$(jq '.rates | length' "$2-rates.json")" -gt 0 ] || { echo "STOP: no shipping rate is offered for $2"; return 1; }
}
Ask for the catalog job's rates and choose one:
unset SHIPPING_SERVICE_CATALOG
rates catalog-details.json catalog
CATALOG_RATE=0 # the [number] of the rate you choose from the list above
SHIPPING_SERVICE_CATALOG=$(jq -r --argjson i "$CATALOG_RATE" '.rates[$i].service // empty' catalog-rates.json 2>/dev/null)
echo "SHIPPING_SERVICE_CATALOG=$SHIPPING_SERVICE_CATALOG"
Then the custom job's, from its own details:
unset SHIPPING_SERVICE_CUSTOM
rates custom-details.json custom
CUSTOM_RATE=0 # the [number] of the rate you choose from the list above
SHIPPING_SERVICE_CUSTOM=$(jq -r --argjson i "$CUSTOM_RATE" '.rates[$i].service // empty' custom-rates.json 2>/dev/null)
echo "SHIPPING_SERVICE_CUSTOM=$SHIPPING_SERVICE_CUSTOM"
HTTP 200 application/json, acurrencyline, and at least one numbered rate;- a non-empty
SHIPPING_SERVICE_…value: the chosen rate'sservice.
The two jobs can be offered different rates. Never use one job's service for the other.
Choose the number from the list the helper has just printed. The variable reads the service from that same answer (catalog-rates.json, custom-rates.json). If you ask for rates again, choose again from the new list.
If no rate is offered (STOP: no shipping rate is offered), no shipping service the company has set up can quote this job to this address. Do not submit the job: any shipping.service would be refused with 422 SHIPPING_SERVICE_UNAVAILABLE.
- In the walkthrough, the address is the test customer's account address. Use a synthetic customer whose address the company ships to, or ask the company's administrator to check its shipping setup for that destination.
- In your own integration, check the job's details and its
shipping.address. - Never take a
servicefrom another job, another customer, an internal Back Office request or a value someone sends you privately.
Each service is valid for the job it was quoted for, at the time. It is quoted again at submission. If step 8 or 9 stops with 422 SHIPPING_SERVICE_UNAVAILABLE, nothing was created and the reference is not spent: for that job only, ask for its rates again, delete its payload file, and write it again with step 6.
Step 6 write each final payload once#
Each final payload is that job's details, plus its externalReference and its chosen shipping.service. It is written once. Steps 8 and 9 send this same file for the submission and for every retry, so the request is byte-identical. The final helper refuses to overwrite an existing payload.
final() { # usage: final <details file> <externalReference> <shipping service> <payload file>
[ -n "$3" ] || { echo "STOP: no shipping service chosen for $4 (step 5)"; return 1; }
[ -e "$4" ] && { echo "STOP: $4 already exists; keep it unchanged for the retries"; return 1; }
jq -c --arg ref "$2" --arg svc "$3" '. + {externalReference: $ref} | .shipping = ((.shipping // {}) + {service: $svc})' "$1" > "$4"
}
final catalog-details.json "WT-$RUN-CAT" "$SHIPPING_SERVICE_CATALOG" catalog-job.json
final custom-details.json "WT-$RUN-CUS" "$SHIPPING_SERVICE_CUSTOM" custom-job.json
jq -c '{externalReference, service: .shipping.service, purchaseOrder}' catalog-job.json custom-job.json
Expect two lines, each with its own externalReference (WT-…-CAT, WT-…-CUS) and the service chosen for that job in step 5.
Step 7 define the submit and retry helpers#
submit sends a payload file until it gets a receipt. It handles each kind of answer as follows:
| Answer | What submit does |
|---|---|
201, or the 200 replay (both JSON) |
Checks the receipt (below). If it passes, saves it as <name>-receipt.json and stops; otherwise stops with STOP. |
Empty 401 |
Stops: check the credential and host. |
403 |
Stops: check the application's permissions. |
404 |
Stops: use the company's own host, and check that the company has the PressCentric API enabled. |
400, 409, 422 or any other 4xx |
Stops and shows the answer. |
A timeout, a 5xx, or a non-JSON answer such as a 200 maintenance page |
The outcome is unknown. It waits and resends the same file with the same application. |
A receipt is usable only if it is JSON, its externalReference equals the one in the payload file, and its jobId and orderId are positive whole numbers. Anything else, even an empty JSON object, stops the walkthrough.
Each resend is safe: it returns 201 (the job did not exist yet) or the 200 replay of the original job. It never creates a second job.
Do not resend with another application: each application has its own externalReference space, so a different application would create a duplicate.
confirm_replay sends the same file once more, after submit has saved a receipt. It passes only if the answer is 200 JSON with "replayed": true and the same externalReference, jobId and orderId as the saved receipt.
receipt_ok() { # usage: receipt_ok <answer file> <payload file>
jq -e --arg ref "$(jq -r '.externalReference' "$2")" \
'def id: type == "number" and . > 0 and . == floor;
type == "object" and .externalReference == $ref and (.jobId | id) and (.orderId | id)' "$1" > /dev/null 2>&1
}
submit() { # usage: submit <payload file> <name>
rm -f "$2-receipt.json"; n=1
while [ "$n" -le 5 ]; do
r=$(curl -sS --max-time 60 -X POST -H "$AUTH" -H "Accept: application/json" \
-H "Content-Type: application/json" --data-binary @"$1" -D "$2-$n.headers" -o "$2-$n.json" \
-w '%{http_code} %{content_type}' "$API/jobs") || r="no-answer"
echo "$2 attempt $n: HTTP $r"
case "$r" in
"201 application/json"*|"200 application/json"*)
if receipt_ok "$2-$n.json" "$1"; then
cp "$2-$n.json" "$2-receipt.json"
jq -c '{replayed, jobId, orderId, externalReference, jobType, release: .atCommit.release, holds: .atCommit.holds}' "$2-receipt.json"
return 0
fi
echo "STOP: no usable receipt (needs this externalReference, a jobId and an orderId)"; cat "$2-$n.json"; echo; return 1 ;;
"401 "*) echo "STOP: empty 401 - check the credential and the host"; return 1 ;;
"403 "*) echo "STOP: 403 - check the application's permissions (it needs Submit new jobs)"; return 1 ;;
"404 "*) echo "STOP: 404 - use the company's own host, and check that the company has the PressCentric API enabled"; return 1 ;;
"400 "*|"409 "*|"422 "*) echo "STOP: refused"; cat "$2-$n.json"; echo; return 1 ;;
"4"*) echo "STOP: HTTP $r"; cat "$2-$n.json"; echo; return 1 ;;
esac
echo "outcome unknown: resending the same file in 15 s"; sleep 15; n=$((n + 1))
done
echo "STOP: no receipt after 5 attempts; run the step again later with the same file"; return 1
}
confirm_replay() { # usage: confirm_replay <payload file> <name> (after submit saved <name>-receipt.json)
[ -f "$2-receipt.json" ] || { echo "STOP: no saved receipt for $2"; return 1; }
r=$(curl -sS --max-time 60 -X POST -H "$AUTH" -H "Accept: application/json" \
-H "Content-Type: application/json" --data-binary @"$1" -o "$2-retry.json" \
-w '%{http_code} %{content_type}' "$API/jobs") || r="no-answer"
echo "$2 retry: HTTP $r"
case "$r" in
"200 application/json"*) ;;
"201 "*) echo "STOP: 201 - the retry created a new job; report it with both answers"; cat "$2-retry.json"; echo; return 1 ;;
"200 "*|"5"*|"no-answer") echo "outcome unknown: run the step again; it resends the same file"; return 1 ;;
*) echo "STOP: HTTP $r"; cat "$2-retry.json"; echo; return 1 ;;
esac
if receipt_ok "$2-retry.json" "$1" && jq -e --slurpfile o "$2-receipt.json" \
'.replayed == true and .jobId == $o[0].jobId and .orderId == $o[0].orderId' "$2-retry.json" > /dev/null 2>&1; then
jq -c '{replayed, jobId, orderId, externalReference}' "$2-retry.json"; echo "same job and order"; return 0
fi
echo "STOP: not a replay of the original job and order"; cat "$2-retry.json"; echo; return 1
}
Step 8 submit the catalog job, then retry it#
unset CATALOG_JOB_ID CATALOG_ORDER_ID
submit catalog-job.json catalog && confirm_replay catalog-job.json catalog \
&& CATALOG_JOB_ID=$(jq -r '.jobId' catalog-receipt.json) && CATALOG_ORDER_ID=$(jq -r '.orderId' catalog-receipt.json) \
&& echo "CATALOG_JOB_ID=$CATALOG_JOB_ID CATALOG_ORDER_ID=$CATALOG_ORDER_ID"
- the receipt line:
"jobType": "CATALOG",releaseRELEASED, orPENDING_APPROVALif the test customer needs approval."replayed"isfalse, ortrueif an earlier attempt had already created the job; - the retry:
HTTP 200 application/json,"replayed": true, andsame job and order; - last:
CATALOG_JOB_ID=… CATALOG_ORDER_ID=…. The ids are set only when both checks pass.
If a line starts with STOP, stop the walkthrough there. If it says outcome
unknown, run this step again; it sends the same file, so it cannot create a second job. Never change the file.
Step 9 submit the custom job, then retry it#
unset CUSTOM_JOB_ID CUSTOM_ORDER_ID
submit custom-job.json custom && confirm_replay custom-job.json custom \
&& CUSTOM_JOB_ID=$(jq -r '.jobId' custom-receipt.json) && CUSTOM_ORDER_ID=$(jq -r '.orderId' custom-receipt.json) \
&& echo "CUSTOM_JOB_ID=$CUSTOM_JOB_ID CUSTOM_ORDER_ID=$CUSTOM_ORDER_ID"
- the receipt line:
"jobType": "CUSTOM",releaseON_HOLD,holds["NEEDS_STOCK","NEEDS_PRICING"]; - the retry:
HTTP 200 application/json,"replayed": true, andsame job and order; - last:
CUSTOM_JOB_ID=… CUSTOM_ORDER_ID=….
STOP and outcome unknown mean the same as in step 8.
Step 10 read each job's current status#
if [ -z "$CATALOG_JOB_ID" ] || [ -z "$CUSTOM_JOB_ID" ]; then
echo "STOP: steps 8 and 9 did not both finish"
else
for id in "$CATALOG_JOB_ID" "$CUSTOM_JOB_ID"; do
r=$(curl -sS -H "$AUTH" -H "Accept: application/json" -o "job-$id.json" \
-w '%{http_code} %{content_type}' "$API/jobs/$id"); echo "job $id: HTTP $r"
ok "$r" && jq -c '{jobId, ticketNumber, orderId, source, externalReference, orderState, jobState, jobActivation, release, holds}' "job-$id.json"
done
fi
Expect HTTP 200 for both, "source": "CLIENT_API", and each job's own externalReference and orderId.
- Catalog job:
releaseisRELEASEDorPENDING_APPROVAL. - Custom job:
releaseisON_HOLD,jobActivationisHELD, andholdsis["NEEDS_STOCK", "NEEDS_PRICING"].
This is the job's current state, so it can differ from the receipt.
Step 11 find both jobs in the feed#
The feed can show a ticket up to about 5 seconds after it commits. Read from FEED_START:
if [ -z "$CATALOG_JOB_ID" ] || [ -z "$CUSTOM_JOB_ID" ] || [ -z "$FEED_START" ]; then
echo "STOP: steps 2, 8 and 9 did not all finish"
else
sleep 6; AFTER=$FEED_START; : > feed-after.jsonl
while :; do
r=$(curl -sS -H "$AUTH" -H "Accept: application/json" -o feed-page.json \
-w '%{http_code} %{content_type}' "$API/jobs?after=$AFTER&limit=200"); ok "$r" || break
jq -c '.jobs[]' feed-page.json >> feed-after.jsonl
AFTER=$(jq -r '.next' feed-page.json)
[ "$(jq -r '.hasMore' feed-page.json)" = "true" ] || break
done
jq -c --argjson a "$CATALOG_JOB_ID" --argjson b "$CUSTOM_JOB_ID" \
'select(.jobId == $a or .jobId == $b) | {seq, jobId, orderId, source, externalReference, release, holds}' feed-after.jsonl
fi
Expect exactly two lines, one per job id, each with "source": "CLIENT_API" and its own externalReference. Other tickets of the company may appear too.
If one is missing, wait a few seconds and run this step again. Reading from the same FEED_START returns the same tickets.
Step 12 compare each job's current status with the Back Office#
For each job, use its ticketNumber, orderId, jobState and jobActivation from step 10.
- Open Job Dockets and set the activation filter to Activation: All. Held jobs are then listed too.
- Find the row whose ID equals the job's
ticketNumber, and open it. - Its Status shows the state and the activation. Compare them with the API values:
jobState |
Back Office state |
|---|---|
APPROVAL |
Approval Required |
REVIEW |
Awaiting Review |
PREPRESS |
Preflight |
PROOFING |
Proofing |
IMPOSITION |
Imposition |
PRODUCTION |
In Production |
COMPLETE |
Completed |
jobActivation |
Back Office activation |
|---|---|
ACTIVE |
Active |
HELD |
Held |
INACTIVE |
Inactive |
- Open Orders, open the order whose ID equals the job's
orderId, and check that Purchase Order shows the payload'spurchaseOrder(WT-…-CATorWT-…-CUS).
- the catalog job's state and activation match the API;
- the custom job shows Held.
No Back Office screen lists a custom job's open holds (NEEDS_STOCK, NEEDS_PRICING). For those, the API is the reference.
Step 13 revoke the test application#
- In Control Panel → System Settings → API Integrations, find the row named
$APP_NAME. - Choose Revoke in that row, and confirm with Revoke in the "Revoke … ?" dialog.
- Its status becomes Revoked. The company's other applications are not affected.
Then confirm that the credential is refused:
r=$(curl -sS -H "$AUTH" -H "Accept: application/json" -o revoked.txt \
-w '%{http_code} %{content_type}' "$API/credential"); echo "HTTP $r"; wc -c < revoked.txt
unset CREDENTIAL AUTH
Expect HTTP 401 and a body of 0 bytes.
1. Before you start: setup checklist#
| Step | Who | How |
|---|---|---|
| The company is on the Pro edition and its PressCentric API module is enabled | PressCentric, for the print company | Both are required; the general Integration module alone does not enable the API, and the module is off by default. Until both are in place, every client API call answers 404 and administrators cannot list, create, rotate or revoke applications. If either is later removed, existing credentials stop working (404) without being revoked. |
| An application and its credential exist | A Back Office administrator of the print company | System Settings → API Integrations (/integration/api), New application. See section 2. |
| You know the company's API host | The administrator | The company's own PressCentric host, never a storefront domain. GET
/credential returns it as host. |
| You have the ids your jobs need | The administrator, plus your own reads | See section 9. |
2. Credentials and permissions#
An administrator creates one application per system that connects. Creating it shows the credential once. Store it in your secret store immediately; PressCentric keeps only a hash and cannot show it again.
- Format:
pcik_<12-character prefix>_<43-character secret>.- The prefix is public and identifies the application.
- The secret is what authenticates.
- Header:
Authorization: Bearer <credential>on every call. - Scope of access: a v1 credential is company-wide. It covers every customer and job of the company, across all storefronts and territories. The administrator confirms this when creating it.
- Rotate: the administrator can issue a new secret. The old secret stops working at once and the prefix stays the same, so deploy the new secret right after rotating.
- Revoke: the administrator can revoke an application. Every call with its credential then answers
401.
Choosing permissions#
Each permission is independent; none implies another. Grant only what the system needs.
| Permission (scope) | Allows |
|---|---|
customers.read |
GET
/customers |
jobs.read |
GET
/jobs (new-ticket feed) and GET /jobs/{jobId} (one job's current state) |
jobs.submit |
POST
/jobs and POST /jobs/shipping-rates |
GET /credentialworks with any valid credential, whatever its scopes.- A submit-only credential still receives the full receipt for its own submissions. To read a job's state later, it needs
jobs.read. - Permissions cannot be edited after creation. To change them, the administrator creates a new application and revokes the old one.
- A new application has its own new-ticket feed start position, set at its first
GET /jobs; see section 5. Tickets committed before that read are not delivered to it. Read them by id if you need them. - Its
externalReferencespace is also its own. Sending the same payload through two applications can create two jobs; see section 8.
3. Base URL and responses common to every call#
https://<company host>/backoffice/next/api/client-api/v1
| Status | Body | Meaning | What to do |
|---|---|---|---|
401 |
empty | No credential, a malformed, wrong or revoked one, or another company's credential, or the wrong host for it. The request was refused before it ran; nothing was done. | Check the credential and the host. Resending unchanged gets the same 401. |
403 |
a generic body; never an API error code | The application lacks the permission this endpoint needs. The request was refused before it ran; nothing was done. | Check the application's permissions under API Integrations. They cannot be edited; an application with the permission is needed. |
404 |
no API error code (any body is a generic server response, not an {"error",
"message"} object) |
The host is not the company's own host (for example a storefront domain), or the company does not have the PressCentric API enabled (Pro edition and the PressCentric API module) | Check the host; ask the administrator. |
About the generic 403. With Accept: application/json the body looks like {"timestamp":"…","status":403,"error":"Forbidden","path":"…"}; with Accept:
text/html it is an HTML page. It has no message, and "Forbidden" is not an API error code. To tell a missing scope from the customers endpoint's 403 CURSOR_FORBIDDEN, read error: anything other than CURSOR_FORBIDDEN means a missing scope.
Check the HTTP status and content type before reading a successful response as JSON. An HTML maintenance page can arrive with HTTP 200.
- Treat any response whose
Content-Typeis notapplication/jsonas "no answer, retry later", including a200. It is never data. - A JSON body without an API error code (for example a generic
{"timestamp", "status", "error", "path"}page) is not an API error either. - For
POST /jobs, a maintenance page or a timeout means the outcome is unknown. Resend the same saved payload with the same application andexternalReference(section 8).
4. Check your credential: GET /credential#
curl -s -H "Authorization: Bearer $CREDENTIAL" \
"https://print.example.com/backoffice/next/api/client-api/v1/credential"
{
"applicationId": 3,
"name": "Example ERP",
"host": "print.example.com",
"scopes": ["customers.read", "jobs.read", "jobs.submit"],
"companyWideAccess": true
}
The credential itself is never echoed back.
5. Read new jobs and job status#
Required permission: jobs.read.
- New tickets:
GET /jobs?after=<position>&limit=<1-200>.- Tickets come oldest first:
{"jobs": [...], "next": <position>, "hasMore": <bool>}. - Save
nextonly after processing the page. - While
hasMoreis true, ask again at once. Otherwise poll later with the sameafter. - Process idempotently by
jobId.
- Tickets come oldest first:
- One job:
GET /jobs/{jobId}. Its state now, including held, waiting for approval and cancelled.404 JOB_NOT_FOUNDwhen the company has no such placed job. - The key to store is
jobId. It is the same id the submission receipt and itsLocationheader carry.ticketNumberis a label that can change.
Job status fields:
| Field | Values |
|---|---|
release |
RELEASED, PENDING_APPROVAL, ON_HOLD or NOT_RELEASED |
holds |
NEEDS_STOCK, NEEDS_PRICING |
orderState |
ACTIVE, APPROVAL, PAYMENT_PENDING or CANCELLED |
jobState |
the production stage, APPROVAL … COMPLETE |
jobActivation |
ACTIVE, HELD or INACTIVE |
cancelled |
true or false |
Versions#
A catalog job can have versions: the options of the product's Multiple Quantities field, each with its own quantity. GET /jobs and GET /jobs/{jobId} list them in versions ([] for a job without any). Ordinary options, for example a Finish choice, are not versions.
Submitting versions. Send the product's Multiple Quantities field in options, with its value as one quantity per option of that field, separated by commas. This example is the one PressCentric's test JobFeedHttpIntegrationTest.multipleVersions_areTheJobsMultipleQuantitiesOptions_andJobsWithoutThemHaveNone submits and reads back. The product has a Multiple Quantities field "Design" (id 7 here) whose options are listed as Spring, then Summer, and a choice field "Finish" (id 9 here) with the choice Matte:
{
"externalReference": "ACME-RACK-1",
"customer": {"id": 5120},
"product": {"id": 214},
"quantity": 1500,
"size": {"width": 20, "height": 25},
"options": [
{"customFieldId": 7, "value": "1000,500"},
{"customFieldId": 9, "value": "Matte"}
],
"shipping": {"service": "11-GROUND"},
"notifyCustomer": false
}
The job then reads back with the quantity that was sent and two versions; Matte is not one of them (other fields of the job omitted):
{
"quantity": 1500,
"versions": [
{"fieldId": 7, "field": "Design", "name": "Spring", "quantity": 1000},
{"fieldId": 7, "field": "Design", "name": "Summer", "quantity": 500}
]
}
How the quantities are matched to options:
-
The first quantity goes to the field's first option, the second to its second option, and so on. The order is the order in which the options are listed on the field in the Back Office (Control Panel → Products & Pricing → Custom Fields, the field's options). Option names are not sent.
-
versionscomes back in the same order. Read the job back and check eachversions[].nameagainst what you meant. -
Write each quantity as a whole number in digits only, without thousands separators: the comma separates versions.
-
With fewer quantities than the field has options, the remaining options get no version. A quantity of
0means that option was not ordered, and it is not listed. -
Changing the field later (renaming, reordering or retyping its options) does not change an existing job's versions. It does change which option each position means for later submissions.
-
Send at most one whole-number quantity per listed choice, in the order shown in Back Office.
The job quantity and the version quantities are stored independently.
- The API stores the
quantityyou send and each version's quantity as sent. It computes neither from the other and does not check one against the other. They can differ.
Read the overall quantity and the version quantities as separate values.
There are no packages in v1.
6. Download customers#
Required permission: customers.read.
GET
/customers?limit=<1-500> starts a scan. GET /customers?after=<nextCursor> continues it until complete is true. Remove local customers only after a complete scan.
customer.id is the value you send as customer.id in POST
/jobs. A customer with enabled: false cannot receive jobs (422
CUSTOMER_NOT_ORDERABLE).
Errors (body {"error", "message"}, application/json):
| Status | error |
message |
What to do |
|---|---|---|---|
| 400 | INVALID_LIMIT |
limit must be an integer from 1 to 500 |
Fix limit. |
| 400 | INVALID_CURSOR |
the cursor is not valid; discard the scan and start a new one |
Discard progress, remove nothing, start a new scan. |
| 403 | CURSOR_FORBIDDEN |
the cursor was issued to another application |
Keep progress and stop; continue with the credential that started the scan. |
| 409 | RESTART_SCAN |
the scan can no longer continue; start a new scan |
Discard progress, remove nothing, start a new scan. |
| 503 | CUSTOMER_SYNC_UNAVAILABLE |
customer sync is not configured on this server |
Retry later. |
7. Submit a job: POST
/jobs#
Scope: jobs.submit. Send Content-Type: application/json and one JSON object.
What a submission does: each submission creates one job on one new order for an existing customer of the company.
- The order is billed the way that customer's account is billed. No card or online payment is ever taken, and the customer's cart is never touched.
- The customer's approval rule applies: a customer who needs approval gets
release: PENDING_APPROVAL. - PressCentric staff are always notified. The customer gets a confirmation only when you send
notifyCustomer: true.
Parsing is strict:
- Every key not listed below is refused (
400 UNKNOWN_FIELD), at every level. - Duplicate keys are refused.
- Strings are trimmed, and an empty string counts as absent.
A request is either a catalog job (product) or a custom job (custom), never both.
Catalog job example (synthetic)#
curl -s -X POST \
-H "Authorization: Bearer $CREDENTIAL" \
-H "Content-Type: application/json" \
--data @job.json \
"https://print.example.com/backoffice/next/api/client-api/v1/jobs"
{
"externalReference": "ERP-SO-100245-1",
"customer": {"id": 5120},
"product": {"id": 214},
"quantity": 1000,
"size": {"width": 4, "height": 9},
"options": [
{"customFieldId": 31, "value": "Matte"},
{"customFieldId": 44, "value": "Spring promotion"}
],
"proofingId": 2,
"turnaroundId": 3,
"shipping": {
"service": "<a rate id; see section 9>",
"address": {"name": "Receiving", "line1": "100 Sample St", "city": "Vancouver",
"state": "BC", "postalCode": "V5K0A1", "country": "CA"}
},
"purchaseOrder": "PO-55012",
"notes": "Deliver to dock 2",
"notifyCustomer": false
}
Custom job example (synthetic)#
A custom job has no catalog product: you describe it. Staff then select stock (unless one is matched; see custom.stock) and set the price. Until both are done the job is held (release:
ON_HOLD), and the customer confirmation and accounting notifications wait.
{
"externalReference": "ERP-SO-100246-1",
"customer": {"id": 5120},
"custom": {
"description": "Fundraiser invitations",
"finishedSize": {"width": 99, "height": 210, "unit": "mm"},
"flatSize": {"width": 297, "height": 210, "unit": "mm"},
"stock": {"description": "100 lb uncoated cover"},
"printing": {"front": 4, "back": 4, "description": "Full colour both sides"},
"instructions": "Tri-fold, banded in 50s"
},
"quantity": 500,
"shipping": {"service": "<a rate id; see section 9>"}
}
Fields: both job types#
| Field | Required | Meaning, units and allowed values | Where you get it |
|---|---|---|---|
externalReference |
yes | Your unique id for this submission: 1-128 characters of A-Z a-z 0-9 . _ :
-. It makes retries safe (section 8). |
You create it. |
customer.id |
yes | Positive integer: the customer the order is for. The customer must exist (422
CUSTOMER_NOT_FOUND) and be enabled (422
CUSTOMER_NOT_ORDERABLE). |
Client API: GET /customers, customer.id. |
quantity |
yes | Number greater than 0 and at most 10,000,000: the job quantity in pieces. Stored as sent, independently of any version quantities (versions). | Your order. |
turnaroundId |
no | Positive integer: one of the company's turnarounds. Used only when the company uses turnarounds; otherwise ignored. Omitted: the turnaround with the least effect on price. An id the company does not have currently fails with 500 SUBMISSION_FAILED (see gaps). |
Not yet available (see gaps). Omit it to get the default. |
shipping.service |
yes | The id of a shipping rate offered for this order's destination, at most 64 characters. Re-quoted at submission; not offered → 422 SHIPPING_SERVICE_UNAVAILABLE. Its shipping cost is added to the order. |
Client API: POST /jobs/shipping-rates, rates[].service, quoted for this same job and ship-to address (step 5). |
shipping.address |
no | Ship-to address. line1, city and country are required inside it. Omitted: the customer's account address. |
Your order. |
shipping.address.name |
no | Recipient name, at most 64 characters. | Your order. |
shipping.address.line1, line2 |
line1 yes |
At most 255 characters each. | Your order. |
shipping.address.city |
yes | At most 64 characters. | Your order. |
shipping.address.state |
no | Region or state code, at most 4 characters, upper-cased (for example BC, NY). |
Your order. |
shipping.address.postalCode |
no | At most 8 characters. | Your order. |
shipping.address.country |
yes | Two-letter country code, upper-cased (for example CA, US). |
Your order. |
purchaseOrder |
no | The customer's PO number, at most 32 characters. | Your order. |
notes |
no | Order instructions, at most 2,048 characters. | Your order. |
notifyCustomer |
no | true sends the customer the order confirmation. Default false. |
Your choice. |
Fields: catalog job only#
size, options and proofingId are refused on a custom job (400
INVALID_REQUEST).
| Field | Required | Meaning, units and allowed values | Where you get it |
|---|---|---|---|
product.id |
yes | Positive integer: the company's catalog product. Unknown: 422
PRODUCT_NOT_FOUND. |
Admin setup: Back Office Products list, ID column. |
size |
no | {"width", "height"} in inches, each greater than 0. Omitted: the product's default size (for printable products). |
Admin setup: the product's default and allowed sizes, from the product in the Back Office. |
options |
no | Up to 100 {"customFieldId", "value"}, each field at most once. Omitted: the product's default options (the first choice of each choice field). Sent: exactly the options you list, so include every option you want. |
See the next two rows. |
options[].customFieldId |
yes | Positive integer: an option field of this product. Otherwise: 422
OPTION_NOT_ON_PRODUCT. |
Admin setup: Back Office Custom Fields list, ID column; the product shows which fields it uses. |
options[].value |
yes | String, at most 255 characters. For a choice field (type SELECT), exactly the name of one of its choices, otherwise 422 OPTION_VALUE_INVALID. For a text or number field, the text or number as a string. For a Multiple Quantities field, whole-number quantities separated by commas, one per option in the field's listed order (versions). Multi-select and number-pricing fields: no supported format. |
Admin setup: the field's choices and their order, in the Back Office Custom Fields list. |
proofingId |
no | Positive integer: one of this product's proofing options. Otherwise: 422
PROOFING_NOT_ON_PRODUCT. Omitted: the job has no proofing option. |
Not yet available (see gaps). |
Fields: custom job only#
| Field | Required | Meaning, units and allowed values | Where you get it |
|---|---|---|---|
custom.description |
yes | The job title, at most 64 characters. | Your order. |
custom.finishedSize |
yes | {"width", "height", "unit"}: the size after finishing. unit is in or mm; each dimension is greater than 0. Shown to staff exactly as submitted. |
Your order. |
custom.flatSize |
no | Same shape: the size before folding. When given, the job is laid out at the flat size, otherwise at the finished size. mm is converted to inches (÷ 25.4). |
Your order. |
custom.stock |
yes | Exactly one of id and description. |
See the next two rows. |
custom.stock.id |
one of | Positive integer: a stock (media) of the company. Unknown: 422
STOCK_NOT_FOUND. If the job's size cannot be laid out on it: 422 STOCK_TOO_SMALL. |
Admin setup: Back Office Media list, Id and Size columns (sheet size in inches). |
custom.stock.description |
one of | Free text, at most 255 characters. Matched against the company's active stock names (brand
description, or description alone), ignoring case, accents and spacing. Exactly one match that fits the job selects it; otherwise the job is held NEEDS_STOCK and staff choose. Your wording is always kept. |
Your order. |
custom.printing.front, back |
yes | Whole number of colours per side, 0 to 8. | Your order. |
custom.printing.description |
no | At most 64 characters, for example "Full colour both sides". | Your order. |
custom.instructions |
no | Production instructions, at most 2,048 characters. | Your order. |
A custom job never takes a price from the API. Staff set it.
The answer: the receipt#
201 Created for a new submission, 200 OK for a replay. The Location header is …/client-api/v1/jobs/{jobId}.
{
"externalReference": "ERP-SO-100245-1",
"replayed": false,
"jobId": 88317,
"jobUuid": "3f6c1e2a-8b7d-4c1e-9a55-0d2b7e4f9a10",
"orderId": 10422,
"orderUuid": "a1b2c3d4-0000-4000-8000-000000000001",
"docketReference": "10422-1",
"ticketNumber": "10422-1",
"jobType": "CATALOG",
"submittedAt": "2026-11-17T15:01:58.120Z",
"atCommit": {
"orderState": "ACTIVE",
"jobState": "REVIEW",
"jobActivation": "ACTIVE",
"release": "RELEASED",
"holds": [],
"billingMethod": "OTHER",
"total": {"amount": "412.50", "currency": "CAD"}
}
}
- The receipt is fixed. It records the state at the moment the job was committed, and a replay returns exactly that again. For the current state, call
GET /jobs/{jobId}(needsjobs.read). - Release values:
RELEASED: in production.PENDING_APPROVAL: waiting for the customer's approval.ON_HOLD: a custom job waiting for staff;holdslistsNEEDS_STOCKand/orNEEDS_PRICING.NOT_RELEASED: any other state.
- Totals:
atCommit.totalis the order's billed total at commit. For a custom job it has no price for the job yet, because staff set the price later.
8. Retrying a submission safely#
PressCentric keeps one submission per (company, application, externalReference). Use one reference per job you intend to create. Save the payload to a file before the first attempt.
A safe retry uses three things unchanged: the same application (its credential), the same externalReference, and the same saved payload.
- Same application: another application of the same company has its own reference space, so the same payload sent through a different application can create a duplicate job.
- Same payload: a changed payload under the same reference is refused with
409.
The walkthrough's submit and confirm_replay helpers (step 7) follow these rules. They resend the same file after a timeout, a 5xx or a non-JSON answer, and stop unless the receipt carries your externalReference, a jobId and an orderId.
| You get | Meaning | Do |
|---|---|---|
201 |
Created. | Store jobId. |
200, "replayed": true |
This reference was already submitted with the same request. Nothing new was created; you get the original receipt. | Store jobId. |
409 EXTERNAL_REFERENCE_CONFLICT (with jobId) |
This reference was already used for a different request. Nothing was written. | Do not change the body and resend under the same reference. The original job is jobId. |
503 SUBMISSION_RETRY |
A concurrent attempt with this reference rolled back. | Retry the identical request. |
500 SUBMISSION_FAILED |
Nothing was committed and the reference is not spent. | Retry the identical request later. If it keeps failing, contact the print company with your externalReference. |
400 / 422 |
Refused; nothing was written and the reference is not spent. | Fix the request. |
401, empty body |
The credential or host was refused before the submission ran. Nothing was written. | Check the credential and the host. Once they are fixed, resend the same saved payload with the same application. |
403, generic body, no API error code |
The application lacks the Submit new jobs permission (jobs.submit). Nothing was written. |
Check the application's permissions. Resending does not help until the application has that permission. |
200 with a non-JSON body, for example an HTML maintenance page (Content-Type:
text/html) |
Outcome unknown. A proxy replaced the answer; the job may or may not have been created. | Wait, then resend the same saved payload with the same application and reference. You get 201 (it had not been created) or the JSON 200 replay with the original jobId (it had). |
| No answer (timeout or connection lost) | Outcome unknown. | Same as the maintenance page: resend the same saved payload with the same application and reference. |
A 200 counts as a replay only when its Content-Type is application/json and the body has "replayed": true, your externalReference, and the original jobId and orderId.
"Identical" means the same fields. The request's fingerprint covers every field. For fields whose default comes from data (size, options, proofingId, turnaroundId, shipping.address), omitting the field and sending today's default value are different requests. So:
- keep the exact body you sent the first time, and resend that;
- never rebuild a retry from changed data.
Other notes:
- Field order, whitespace and trailing zeros in numbers do not matter.
- Options are compared sorted by field id.
- A different application of the same company has its own reference space. Do not submit the same order from two applications.
9. Where each value comes from#
| Value | Client API | Admin setup (Back Office) | Not available to clients today |
|---|---|---|---|
| Your application, host, scopes | GET
/credential |
API Integrations page | |
customer.id |
GET
/customers |
Accounts list, ID column | |
jobId, job status |
receipt, GET /jobs, GET
/jobs/{jobId} |
||
product.id |
Products list, ID column | ||
options[].customFieldId |
Custom Fields list, ID column; the product's fields | ||
Choice names for options[].value, and the option order of a Multiple Quantities field |
The field's choices, in the Custom Fields list | ||
| Product default size, printable or not | The product | ||
custom.stock.id and its sheet size |
Media list, Id and Size columns | ||
turnaroundId |
(the Turnarounds list shows no id) | ✔ | |
proofingId |
(the Proofing list shows no id) | ✔ | |
shipping.service |
POST
/jobs/shipping-rates, rates[].service |
(no screen shows rate ids) |
The Back Office uses internal requests to show these screens. Those requests are not part of the client API: they need a staff login, and they can change without notice. Do not call them from an integration.
10. Errors reference#
POST
/jobs#
The body is {"error", "message", "field"?, "jobId"?}.
| Status | error |
When |
|---|---|---|
| 400 | UNKNOWN_FIELD |
A key that is not in this guide (field names it). |
| 400 | INVALID_REQUEST |
Malformed JSON, duplicate keys, a missing or invalid field, or both or neither of product and custom (field names it). |
| 409 | EXTERNAL_REFERENCE_CONFLICT |
Reference reused for a different request (jobId is the original job). |
| 422 | CUSTOMER_NOT_FOUND, CUSTOMER_NOT_ORDERABLE |
Unknown or disabled customer. |
| 422 | PRODUCT_NOT_FOUND |
Unknown product. |
| 422 | OPTION_NOT_ON_PRODUCT, OPTION_VALUE_INVALID |
Option field not on the product, or not one of its choices. |
| 422 | PROOFING_NOT_ON_PRODUCT |
Proofing option not on the product. |
| 422 | STOCK_NOT_FOUND, STOCK_TOO_SMALL |
Custom job stock id unknown or too small. |
| 422 | SHIPPING_SERVICE_UNAVAILABLE |
shipping.service is not offered for this order. |
| 500 | SUBMISSION_FAILED |
Anything else; nothing was committed. |
| 503 | SUBMISSION_RETRY |
Retry the identical request. |
Example: 400 {"error":"INVALID_REQUEST","message":"custom.stock: give exactly one of id (a
company stock) and
description","field":"custom.stock"}.
GET /jobs, GET
/jobs/{jobId}#
| Status | error |
When |
|---|---|---|
| 400 | INVALID_PARAMETER |
after or limit is invalid (field names it). |
| 404 | JOB_NOT_FOUND |
No such placed job. |
GET /customers errors are in section 6. 401, 403 and 404 from the credential check are in section 3.
Lookup limitations#
Ask the print company for catalog product IDs, field IDs, choice order and stock IDs. You can also specify stock by description on a custom job. Omit optional proofing and turnaround IDs if you have no verified value. The API has no public lookup for these IDs. Use the shipping quote endpoint to obtain a shipping service for each job.
