Approvals API

The approvals API does what the Approvals page and the proof page do: artworks, versions, proof links, emails to reviewers, resets and the history. Every endpoint is under your team, at /a/<team_slug>/artwork-approvals/api/v1/.

Every call takes the same authentication as the rest of the API: an API key of a team member, or a signed-in session that also sends its CSRF token when it changes data (see authentication).

Every member of the team can read and write. Reviewers don't use this API: they comment and decide on the proof page. How approvals work is in How approvals work.

From upload to approval#

ARTWORKS=https://app.example.com/a/acme/artwork-approvals/api/v1/artworks/
VERSIONS=https://app.example.com/a/acme/artwork-approvals/api/v1/versions/
LINKS=https://app.example.com/a/acme/artwork-approvals/api/v1/approval-requests/
AUTH="Authorization: Api-Key $API_KEY"

# 1. Create an artwork (the answer has its id, here 42)
curl -s -X POST "$ARTWORKS" -H "$AUTH" -H "Content-Type: application/json" -d '{"name": "Carton 200"}'

# 2. Upload its first version (the answer is the version, here id 43)
curl -s -X POST "$VERSIONS" -H "$AUTH" -F artwork=42 -F pdf_file=@carton-200.pdf -F notes="First proof"

# 3. Read the version's Simple and Advanced links (the simple one here has id 44), then email it
curl -s -X POST "${VERSIONS}43/share-links/" -H "$AUTH"
curl -s -X POST "${LINKS}44/send/" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"emails": ["buyer@example.com"], "message": "Please check the barcode."}'

# 4. Follow the status of the version's links, and read the history
curl -s "${LINKS}?version=43" -H "$AUTH"
curl -s "${ARTWORKS}42/history/" -H "$AUTH"

Artworks#

The list is paged (100 per page, newest activity first); versions/ of an artwork returns all of them as a plain array, newest first. Artworks can't be deleted through the API.

Versions#

An upload is multipart, with these fields:

It answers 201 with the version. The upload makes the version's Simple and Advanced links, and starts preflight and the print preview. The PDF is kept in Files too (see Proofs and Files). A version reads as:

GET …/advanced-preview/ only reports the preview's status and never starts a build. POST to the same address builds it now, or again after a failure, and answers with the new status. versions/ can be filtered with ?artwork=42.

Versions from Files#

POST …/versions/from-file/ sends a PDF that is already in Files for approval, by the id of its file version (the Files API lists them). Nothing is uploaded: the version shows the same bytes. It takes JSON with these fields:

curl -s -X POST "${VERSIONS}from-file/" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"file_version": 42, "same_reviewers": true, "message": "The barcode is fixed."}'

Without artwork, the version goes to the artwork that already proofs the file, or to a new artwork named name (or after the file). It answers 201 with the new version. When that artwork's latest version already shows this file version, nothing is added and it answers 200 with that version, so a retried request never adds a second one (the reviewers in emails are still invited to it). Compare a version's file_version_number with file_latest_version_number to find artworks with a newer version waiting in Files (see Proofs and Files).

Links#

POST …/versions/{id}/share-links/ returns the version's own links, {"simple": {…}, "advanced": {…}}, and makes any that are missing. request-approval/ and POST approval-requests/ make a new, separate link each time, with these fields:

send/ emails an existing link and adds the addresses as approvers:

reset/ puts the link back to pending, like Reset to pending on the proof page (see Decisions, locking and reset):

A link reads as:

Its recipients are:

and its comments:

The list is paged and can be filtered with ?version=, ?artwork= and ?status=pending|approved|rejected. A link's status is its own; the status the dashboard shows for a version combines its links (see How approvals work).

History#

The history is a plain array, newest first, of every entry of the artwork: id, kind, label, actor, at, version_id, version_number, request_id and details. The kinds are:

The details of a decision hold the whole decision record: decision, comment, name, share_mode, resulting_status, verified, file_sha256, views (offered), viewed (opened), acknowledged and acknowledgement (the text confirmed), ip and user_agent. A reset holds reason, previous_status, cleared_decisions and demoted_approvers. See History and notifications.

Errors#

• 400 with field errors for invalid input: for example {"pdf_file": ["Only PDF files are supported."]} for a file that isn't a PDF, {"emails": {"0": ["Enter a valid email address."]}} for a bad address, {"emails": ["Ensure this field has no more than 50 elements."]} for more than 50, and {"emails": ["This list may not be empty."]} for send/ without addresses. An id of another team in the body (artwork on upload, version on approval-requests/) is a field error too ({"artwork": ["Invalid pk …"]}). Other refusals are 400 with {"detail": "…"}.
• 400 for from-file/ with a file_version that isn't a ready version of a file in your team's Files (a file in the trash doesn't count: {"file_version": ["…"]}), or that isn't a PDF of at most 200 MB ({"detail": "…"}), and for a files_folder that doesn't exist or is in the trash.
• 507 with {"code": "quota_exceeded", "detail": "…", "needed": …, "free": …, "limit": …} when your team's Files storage is full and an upload can't be kept (see Storage). Other refusals from Files answer with their own code, detail and status.
• 502 with {"detail": "The email could not be sent. Try again later."} when an email can't be sent. Nothing is saved then: no link is made and nobody is added.
• 404 for an id of another team in the URL, and for the PDF of a version whose file is missing.

The general rules for keys, errors and paging are on API overview.

Every operation#