BOOK DEMO
PressCentric - API Developer Guide
 
Developer Documentation

PressCentric Client API Guide & Reference

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.

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.

Jump to Section
12 Sections

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:

  1. Create a new test application.
  2. Start its job feed.
  3. Download the customers.
  4. Submit one catalog job and one custom job.
  5. Retry each submission and confirm that no duplicate was created.
  6. Read each job's status, find both jobs in the feed, and compare them with the Back Office.
  7. Revoke the test application.
Before you start:
  • You need a Bash shell, curl and jq, 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>. Only application/json is 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:

  1. Open Control Panel → System Settings → API Integrations.
  2. Choose New application.
  3. Application name: a name used only for this walkthrough, for example API walkthrough test.
  4. Permissions: select Read customer accounts, Read jobs and Submit new jobs.
  5. Choose Review access. Read the access summary and tick Grant … access to all storefronts and territories of ….
  6. Choose Grant access.
  7. 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.

BASH / CURL
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#

BASH / CURL
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
Expect:
  • HTTP 200 application/json;
  • name equals $APP_NAME;
  • host equals $COMPANY_HOST;
  • scopes lists customers.read, jobs.read and jobs.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.

BASH / CURL
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).

BASH / CURL
: > 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
Expect:
  • 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:

BASH / CURL
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.

BASH / CURL
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 the service.
  • Rates quoted to one address can differ for another, and the chosen service can then be refused with 422.
BASH / CURL
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.

BASH / CURL
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:

BASH / CURL
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:

BASH / CURL
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"
Expect, for each job:
  • HTTP 200 application/json, a currency line, and at least one numbered rate;
  • a non-empty SHIPPING_SERVICE_… value: the chosen rate's service.

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 service from 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.

BASH / CURL
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.

BASH / CURL
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#

BASH / CURL
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"
Expect:
  • the receipt line: "jobType": "CATALOG", release RELEASED, or PENDING_APPROVAL if the test customer needs approval. "replayed" is false, or true if an earlier attempt had already created the job;
  • the retry: HTTP 200 application/json, "replayed": true, and same 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#

BASH / CURL
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"
Expect:
  • the receipt line: "jobType": "CUSTOM", release ON_HOLD, holds ["NEEDS_STOCK","NEEDS_PRICING"];
  • the retry: HTTP 200 application/json, "replayed": true, and same 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#

BASH / CURL
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: release is RELEASED or PENDING_APPROVAL.
  • Custom job: release is ON_HOLD, jobActivation is HELD, and holds is ["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:

BASH / CURL
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.

  1. Open Job Dockets and set the activation filter to Activation: All. Held jobs are then listed too.
  2. Find the row whose ID equals the job's ticketNumber, and open it.
  3. 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
  1. Open Orders, open the order whose ID equals the job's orderId, and check that Purchase Order shows the payload's purchaseOrder (WT-…-CAT or WT-…-CUS).
Expect:
  • 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#

  1. In Control Panel → System Settings → API Integrations, find the row named $APP_NAME.
  2. Choose Revoke in that row, and confirm with Revoke in the "Revoke … ?" dialog.
  3. Its status becomes Revoked. The company's other applications are not affected.

Then confirm that the credential is refused:

BASH / CURL
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 /credential works 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 externalReference space 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#

HTTP / URL
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-Type is not application/json as "no answer, retry later", including a 200. 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 and externalReference (section 8).

4. Check your credential: GET /credential#

BASH / CURL
curl -s -H "Authorization: Bearer $CREDENTIAL" \
  "https://print.example.com/backoffice/next/api/client-api/v1/credential"
JSON
{
  "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 next only after processing the page.
    • While hasMore is true, ask again at once. Otherwise poll later with the same after.
    • Process idempotently by jobId.
  • One job: GET /jobs/{jobId}. Its state now, including held, waiting for approval and cancelled. 404 JOB_NOT_FOUND when the company has no such placed job.
  • The key to store is jobId. It is the same id the submission receipt and its Location header carry. ticketNumber is 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:

JSON
{
  "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):

JSON
{
  "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.

  • versions comes back in the same order. Read the job back and check each versions[].name against 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 0 means 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 quantity you 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)#

BASH / CURL
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"
JSON
{
  "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.

JSON
{
  "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}.

JSON
{
  "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} (needs jobs.read).
  • Release values:
    • RELEASED: in production.
    • PENDING_APPROVAL: waiting for the customer's approval.
    • ON_HOLD: a custom job waiting for staff; holds lists NEEDS_STOCK and/or NEEDS_PRICING.
    • NOT_RELEASED: any other state.
  • Totals: atCommit.total is 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.

PressCentric API Documentation • Pro Edition Integration Module
Synthetic Walkthrough & Reference • Client API v1