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#
/a/{team_slug}/artwork-approvals/api/v1/artworks/
artworks_list ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/artworks/
artworks_create ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/artworks/{id}/
artworks_retrieve ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/artworks/{id}/
artworks_partial_update ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/artworks/{id}/
artworks_update ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/artworks/{id}/versions/
Every uploaded version of this artwork, newest first.
artworks_versions ·
View in API reference
| Field | Description |
|---|---|
| id | The artwork's id. |
| name | The artwork's name, up to 255 characters. You can write it, and allow_download. |
| allow_download | Whether reviewers can download the PDF from the proof's ⋯ menu: false (the default) or true. Your team can always download it. |
| created_at | When the artwork was created. |
| updated_at | Last activity: uploads, links, emails, decisions, resets and comments move it forward. |
| version_count | How many versions the artwork has. |
| latest_version | The newest version (a version object), or null before the first upload. |
The list is paged (10 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.
Lists for one reviewer#
Add ?recipient_email=buyer%40example.com to artworks/ or approval-requests/ to return only records associated
with that exact email. Matching ignores case, includes viewers and approvers in every workflow stage (including
future stages), and never matches part of another address. Counts and pagination describe the filtered list.
Requests shared with several reviewers still appear once. Other filters, such as status and artwork, combine
with the email filter. An unknown email gives an empty list; a blank or invalid email answers 400.
These remain team APIs: team membership is checked before filtering. The API key has the team's access; a portal
integration must get the email from its authenticated user, never from an editable customer query parameter.
Filtering reduces the records sent and serialized before your portal displays its table. Internal team views
can leave the email filter off. Artwork metadata and latest_version still describe the team's artwork; customer
portals must use only versions on that reviewer's matching requests, including when a newer version is unshared.
Versions#
/a/{team_slug}/artwork-approvals/api/v1/versions/
Upload a PDF as the next version of an artwork.
artwork_versions_upload ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/versions/
artwork_versions_list ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/versions/{id}/
artwork_versions_retrieve ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/versions/{id}/pdf/
Download the version's PDF (team members only; the file is never public).
artwork_versions_pdf ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/versions/{id}/thumbnail/
Small first-page PNG (200 pixels on its long side).
artwork_versions_thumbnail ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/versions/{id}/advanced-preview/
Build status of the separations preview (ready, building, failed, missing or stale).
artwork_versions_advanced_preview ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/versions/{id}/advanced-preview/
Build the separations preview now, or retry a failed build.
artwork_versions_advanced_preview_build ·
View in API reference
An upload is multipart, with these fields:
| Field | Description |
|---|---|
| artwork | Required. The artwork's id; the version gets the artwork's next number. |
| pdf_file | Required. The PDF, at most 200 MB. The name must end in .pdf and the file must be a PDF. |
| notes | Optional. What changed in this version, up to 5,000 characters. |
| client_file_path | Optional. Where the file came from on your side, such as a path or an order reference (up to 1,024 characters). It is kept with the version and never shown to reviewers. |
| files_folder | Optional. The id of a Files folder for the artwork's first file. Default: the Approvals folder. Later versions always go to the artwork's file, wherever it is. |
| notify_reviewers | true (default): a few minutes after the upload, the previous version's invited reviewers are emailed the new version and its staged approval starts over at stage 1. false: nobody is emailed until you share it. |
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:
| Field | Description |
|---|---|
| id | The version's id. |
| artwork | The artwork's id. |
| version_number | 1, 2, 3 and so on, per artwork. |
| pdf_url | The team download of the PDF (the pdf action). It needs your API key or session. |
| original_filename | The uploaded file's name. |
| client_file_path | What you sent as client_file_path, or empty. |
| spot_colors | The names of the spot colours found in the PDF, in the order they were found. |
| notes | The version's notes. |
| uploaded_at | When the version was uploaded. |
| advanced_preview | The separations preview: status ready, building (with progress), failed, missing or stale. |
| file_id | The id of the Files file the version was made from, or null for a version from before Files. |
| file_version | The id of that version in Files, or null. |
| file_version_number | Its version number in Files (v5), which is independent of version_number; or null. |
| file_latest_version_number | The file's current version number in Files, or null when the file is in the trash. Higher than file_version_number: a newer version is waiting in Files. |
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.
Thumbnails#
GET …/versions/43/thumbnail/ returns a small first-page PNG, at most 200 pixels on its long side. It uses the
same stored thumbnail as the Approvals dashboard. Fetch your list first, then request images separately for the
visible rows. Send your team API key or session with each thumbnail request; the image is not public.
A cached image answers 200 with Content-Type: image/png and a private, one-day browser cache. If it needs
rendering, the request starts or joins a background render and immediately answers 202 with no image and
Retry-After: 2. Wait that many seconds before retrying. An unavailable image answers 404; show a file icon
instead. Pending and unavailable responses are not cached. Rendering is independent of the separations preview,
and the list response never waits for thumbnails. Keep API keys on your server when building a customer portal.
Versions from Files#
/a/{team_slug}/artwork-approvals/api/v1/versions/from-file/
Send a PDF version from Files for approval: the next version of the artwork that already proofs that file (or of `artwork`, or of a new artwork), using the same bytes, never a copy.
artwork_versions_from_file ·
View in API reference
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:
| Field | Description |
|---|---|
| file_version | Required. The id of a ready PDF version in your team's Files, at most 200 MB. |
| artwork | Optional. The artwork that gets the version. Default: the artwork that already proofs this file, else a new one. |
| name | Optional. The name of a new artwork, up to 255 characters. Default: the file name without .pdf. |
| notes | Optional. What changed in this version, up to 5,000 characters. |
| share_mode | simple (default) or advanced: the link emailed to the reviewers. |
| emails | Optional. Up to 50 reviewer addresses to email the link to. They become invited approvers. |
| same_reviewers | true also emails the approvers of the artwork's previous version (default false). Nobody is emailed again when no version was added. |
| message | Optional text above the link in the email, up to 5,000 characters. |
| notify_reviewers | true (default): previous reviewers you did not email here are emailed the new version a few minutes later, as after an upload. false: only the addresses in emails and same_reviewers are emailed. |
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).
By default the previous version's reviewers hear of a new version a few minutes later, as after an upload. Send
"notify_reviewers": false to email only the addresses in emails and same_reviewers, which is what the Files
and Approvals dialogs do.
Where a file stands#
/a/{team_slug}/artwork-approvals/api/v1/files/{file_id}/approvals/
Where a file in Files stands in Approvals: every version of it that was sent for approval, newest first, with its status, who decided and when; and the file's current version when it is newer than the one in approval.
artwork_file_approvals ·
View in API reference
GET …/files/{file_id}/approvals/ answers where a file in Files stands in Approvals, by the file's id: which of
its versions were sent for approval, whether each was approved, by whom and when, and whether its current version
is newer than the one in approval. It is what the Files panel shows (see Proofs and Files).
| Field | Description |
|---|---|
| file | The file's id in Files. |
| current_version | The file's current version number in Files, or null. |
| approvals | Every version of the file that was sent for approval, newest first (see below). |
| newer | Set when the file's current version is newer than the one in approval (see below); null when the current version is the one in approval, or the file was never sent. |
Each entry of approvals is one artwork version made from the file:
| Field | Description |
|---|---|
| artwork | The artwork's id. |
| name | The artwork's name. |
| url | The Approvals page, searched for the artwork. |
| version | The id of the artwork version (the proof round). |
| version_number | Its number in the artwork: 1, 2, 3 and so on. |
| file_version | The version number in Files it was made from (v2). |
| print_ready | true when it proofs the print-ready file made from that version in the 1-up editor. |
| status | draft (not sent to anyone yet), pending (out for approval), approved, or rejected (changes requested). |
| superseded | true once a later version of the artwork replaced it: it can no longer be approved. |
| decided_at | When it was approved or rejected (the latest decision that counted), or null. |
| decided_by | The names of up to 5 approvers who gave that decision, latest first. |
| stage | For a staged approval that is under way: number, total and name of the stage deciding now. |
| reviewers | How many approvers it has. |
| created_at | When the version was sent to Approvals. |
newer describes the version waiting in Files:
| Field | Description |
|---|---|
| version_id | The id of the file's current version in Files: give it as file_version to versions/from-file/. |
| number | Its version number in Files. |
| artwork | The id of the artwork that gets it. |
| name | That artwork's name. |
| round | The artwork version number it would get. |
| previous | The artwork's latest version, which it would replace (an approvals entry, as above). |
| reviewers | The addresses same_reviewers would email: the approvers of that latest version. |
| staged | true when that latest version has a staged approval: with same_reviewers it starts over at stage 1. |
curl -s "https://app.example.com/a/acme/artwork-approvals/api/v1/files/42/approvals/" -H "$AUTH"
To send the waiting version to the same reviewers, post newer.version_id as file_version to
versions/from-file/ with "same_reviewers": true.
Links#
/a/{team_slug}/artwork-approvals/api/v1/versions/{id}/share-links/
The version's default simple and advanced links (created when missing).
artwork_versions_share_links ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/versions/{id}/3d/
Whether the round's 3D proof (folded from its Files document's die) can be shown, and whether the artwork's Simple and Advanced links show it.
artwork_versions_3d ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/versions/{id}/3d/
Show or hide the round 3D proof on the artwork's Simple and Advanced links (every version).
artwork_versions_3d_set ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/versions/{id}/request-approval/
Create a simple or advanced share link for this version (same as POST approval-requests).
artwork_versions_request_approval ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/viewer-link/
Get the signed personal viewer link for an existing recipient.
approval_requests_viewer_link ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/approval-requests/
Generate a simple or advanced viewer link and optionally email it to reviewers.
approval_requests_create ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/approval-requests/
approval_requests_list ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/
approval_requests_retrieve ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/send/
Email this link to reviewers (they are added as approvers).
approval_requests_send ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/reset/
Put the request back to pending (clears every reviewer's decision).
approval_requests_reset ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/expiry/
Set when the link stops opening: expires_in_days (1 to 365) or expires_at (null = never).
approval_requests_expiry ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/revoke/
Turn the link off at once: its address then answers 410 Gone.
approval_requests_revoke ·
View in API reference
POST …/versions/{id}/share-links/ returns the version's own links, {"simple": {…}, "advanced": {…}}, and makes
any that are missing.
GET …/versions/{id}/3d/ answers {"available": …, "offered": …}: whether the version's proof can fold up in 3D
from its Files dieline, and whether the artwork's Simple and Advanced links show it. Post {"offered": true} (or
false) to the same address to switch it, like Show the 3D proof in Share; it applies to every version of
the artwork and is off until switched on (see 3D proofs in approvals).
request-approval/ and POST approval-requests/ make a new, separate link each time, with these fields:
| Field | Description |
|---|---|
| version | Required on approval-requests/. The version's id; request-approval/ takes it from its URL. |
| share_mode | simple (default) or advanced: the viewer the link opens. |
| emails | Optional. Up to 50 reviewer addresses. They become invited approvers of the link. |
| subject | Optional email subject, up to 255 characters. Default: "Approval requested: <artwork> v<number>". |
| message | Optional text above the link in the email, up to 5,000 characters. |
| send_email | true (default) emails the link to emails; false only adds them as approvers. |
| stages | Optional. Makes it a staged approval: up to 6 stages in order, each with name, rule and emails (see below). Replaces emails, and the first stage is always emailed. |
| workflow | Optional, instead of stages: the id of a staged-approval preset to start. |
| variables | With workflow: the addresses for the preset's variables, as an object of variable name to a list of emails. |
| expires_in_days | Optional. The link stops opening this many days from now, 1 to 365. |
| expires_at | Optional. The link stops opening at this time (in the future), instead of expires_in_days. |
Warning: Addresses given with send_email: false
The emails of a new link become invited approvers even when no email is sent. An invited address can only
comment and decide from its personal link. Email it with send/, or open it from a trusted portal integration
using viewer-link/; the shared request URL alone does not verify the invited address.
send/ emails an existing link and adds the addresses as approvers:
| Field | Description |
|---|---|
| emails | Required. 1 to 50 reviewer addresses. Each gets a personal link and becomes an approver. |
| message | Optional text above the link in the email, up to 5,000 characters. |
reset/ puts the link back to pending, like Reset to pending on the proof page (see
Decisions, locking and reset):
| Field | Description |
|---|---|
| reason | Optional. Why the link is reset, up to 2,000 characters. Kept in the history. |
expiry/ sets when the link stops opening, like the expiry in Share (see
Share links: Simple and Advanced). A revoked link can't be given a new expiry:
| Field | Description |
|---|---|
| expires_in_days | 1 to 365: the link stops opening this many days from now. |
| expires_at | Instead of expires_in_days: a time in the future, or null for a link that never expires. |
revoke/ turns the link off at once and takes no body. Both answer with the link and are recorded in the history.
A closed link (is_open false) answers 410 Gone to reviewers; asking share-links/ again then makes a new
Simple or Advanced link with a new address.
A link reads as:
| Field | Description |
|---|---|
| id | The link's id. |
| token | The secret part of the link's address. Anyone who has it can open the proof. |
| url | The reviewer link to open or send. |
| viewer_link | Personal invitation with email and url for the exact recipient_email filter on an open request. Null without that filter or when closed. Use directly in the portal; never share between reviewers. |
| share_mode | simple or advanced. |
| views | The proof views the link was made with: ["flat"], or with "3d" for a 3D proof. |
| scene | The id of the link's 3D proof, or null. |
| status | pending, approved or rejected (the link's own status). |
| artwork | The artwork's id. |
| version | The version's id. |
| version_number | The version's number. |
| requested_by | The name of the team member who made the link, or empty. |
| email_subject | The subject its emails use. |
| email_message | The message sent with it when it was made. |
| created_at | When the link was made. |
| expires_at | When the link stops opening, or null for never. |
| revoked_at | When a team member revoked the link, or null. |
| is_open | true while the link opens: not revoked and not expired. A closed link answers 410 Gone. |
| current_stage | For a staged approval: the number of the stage that is deciding now. 1 without stages. |
| stages | For a staged approval: every stage with its state and approvers (see below). Empty without stages. |
| recipients | The link's reviewers (see below). |
| comments | Every comment made on the link (see below). |
Its recipients are:
| Field | Description |
|---|---|
| id | The reviewer's id on this link. |
| Their email address, in full. | |
| name | The name they gave, or empty. |
| role | approver or viewer. |
| stage | For a staged approval: the number of the stage they decide in. 1 without stages. |
| decision | pending, approved or rejected. |
| decision_at | When they last decided, or null. |
| page_decisions | Read-only map of 1-based PDF page numbers to decision (approved or rejected) and at (ISO timestamp). Missing pages are pending. An empty map means decision applies to the entire file. |
For page-by-page reviews, page_decisions maps page numbers such as "2" to
{"decision": "approved", "at": "2026-10-15T12:00:00Z"}. Missing pages are pending. The recipient's top-level
decision is the roll-up: rejected if any page is rejected, approved only if all pages are approved, otherwise
pending. An empty page_decisions map means the top-level decision covers the whole PDF. These fields are
read-only; reviewers record decisions through their proof link. A reset clears both whole-file and page decisions.
Decision history includes scope (file or page), page (1-based, or null for the file) and page_count when
known. Older decisions without scope apply to the entire file.
and its comments:
| Field | Description |
|---|---|
| id | The comment's id. |
| page | The page, from 1; 0 for a general comment made with a decision. |
| x | Distance from the left edge of the page, in points. |
| y | Distance from the top edge of the page, in points. |
| width | The width of the marked area in points; 0 for a spot. |
| height | The height of the marked area in points; 0 for a spot. |
| surface | flat or 3d. |
| anchor | For 3D comments: where the pin sits on the carton, and the camera it was made with. |
| content | The comment's text, up to 5,000 characters. |
| commenter | The email address of who wrote it. |
| thumbnail_url | Team-authenticated PNG preview of the selected area or the context around a point. Null for general comments and unprinted 3D surfaces. Fetch separately; 202 means retry after Retry-After. |
| created_at | When it was written. |
Comment selection previews#
Each point or area comment includes thumbnail_url, a team-authenticated PNG endpoint:
approval-requests/<request_id>/comments/<comment_id>/thumbnail/. General comments (page 0) and 3D pins on
unprinted surfaces return null. Load these URLs separately when displaying the comments, so neither the proof
list nor the comments JSON waits for image generation. No PDF download is needed in your portal.
/a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/comments/{comment_id}/thumbnail/
PNG of a selected area or the context around a point (320 pixels on the long side).
approval_requests_comment_thumbnail ·
View in API reference
An area preview shows the selected rectangle with a little surrounding context and an outline. A point preview
shows a one-inch neighbourhood with a crosshair. Images are at most 320 pixels on the long side, clipped to the
displayed page (including its CropBox and rotation), and use the proof renderer's overprint simulation when
available. Only the small region is rasterized. The API checks the team and owning approval request before reading
the image cache; a comment from another request answers 404.
Cached images return 200 image/png. A cold request queues a background render and answers 202 immediately
with Retry-After: 2; retry lazily with a concurrency limit and backoff. A general, invalid or unrenderable
selection answers 404. The image cache is shared with the proof thumbnail render pool and is keyed by the PDF,
page and selection coordinates: moving or resizing a comment creates a fresh preview. HTTP responses use
private, no-store, since comment positions can change. The list response only provides the URL and starts no render.
Personal viewer links#
GET …/approval-requests/44/viewer-link/?recipient_email=buyer%40example.com returns email and url for that
existing reviewer on that request. url is their private, signed invitation link, including ?reviewer=….
Opening it verifies that email in the viewer for that request only, and shows the document and comments without an
AutomatePrint team account. Another request needs its own link, even for the same reviewer. It never points at the
team dashboard. The response is private and must not be cached, logged or shared
with another reviewer. The request sends no email and changes no approval state.
For a portal table, list approval-requests/?recipient_email=buyer%40example.com. Every open matching request
includes viewer_link: {email, url} for that exact recipient, using the same signed invitation as the endpoint
above. The email-filtered detail response includes it too. Unfiltered responses and expired/revoked requests
return viewer_link: null. The existing url remains the shared viewer URL. The personal URL uses the team's
verified proof domain when one is configured.
Portals can put viewer_link.url directly in the row's Open proof link after verifying its email, viewer
path and trusted origin. This avoids a portal redirect and a separate API call per row. Signing uses the recipients
already loaded for the list and sends no email or other HTTP request. Email-filtered responses are private and
must not be cached by browsers/shared proxies or logged. Server-side caches must remain separated by recipient.
The single-link endpoint remains available for existing integrations and a last-moment access check. A missing
request or reviewer answers 404; an expired or revoked request answers 410. A missing or invalid email answers
400. Both methods require API-key or team session authentication. Always derive the email from the authenticated
portal login. AutomatePrint still verifies the signed invitation and current proof access when it is opened.
For team members who want to open a document without taking a reviewer's identity, use the request's plain viewer path on the AutomatePrint app host. An existing team login shows the viewer's team comment/history controls. This is the document viewer, separate from the team Approvals dashboard.
Staged approvals#
A staged approval asks its approvers in order: the next stage is emailed only when the one before it has approved
(see Staged approvals). Start one with approval-requests/ (or a version's request-approval/) by giving
stages, or the workflow id of a preset with its variables. Leave both out for an ordinary link, where
everyone is asked at once.
{
"version": 42,
"share_mode": "simple",
"message": "Carton 200 is ready for sign-off.",
"stages": [
{"name": "Prepress check", "rule": "all", "emails": ["pat@example.com", "sam@example.com"]},
{"name": "Customer", "rule": "any", "emails": ["jordan@example.com"]}
]
}
Each stage of stages takes:
| Field | Description |
|---|---|
| name | Optional. The stage's name, up to 60 characters. Default: "Stage 1", "Stage 2"… |
| rule | all (default): every approver of the stage must approve. any: one approval is enough. |
| emails | Required. The stage's approvers, team members or anyone else. An address may be in one stage only. |
To start a preset instead, send its id and fill its variables:
{"version": 42, "workflow": 7, "variables": {"customer": ["jordan@example.com"]}}
The link in the answer, and every later read of it, says where the approval stands: status is the whole
approval's (it is approved when the last stage has approved, rejected while a rejection holds a stage),
current_stage is the stage deciding now, and stages lists them all:
| Field | Description |
|---|---|
| number | The stage's place in the order, from 1. |
| name | The stage's name. |
| rule | all or any. |
| state | waiting (not started), active (its approvers are deciding now), approved, or rejected (an approver of the active stage rejected: the approval is held there). |
| approvers | The stage's approvers: email, name, decision (pending, approved or rejected) and decision_at. |
A version has one staged approval at a time: starting another revokes the one still under way (an approved one
is kept). A single stage with "rule": "any" is how "everyone at once, one approval is enough" is sent.
While a version has a staged approval under way, decisions on its other links are refused, so reviewers cannot approve it around the stages.
send/ on a staged link adds its addresses to the stage that is deciding. reset/ starts the approval over at
its first stage. A new version of the artwork restarts the approval on that version with the same stages and
approvers, unless you add it with "notify_reviewers": false or the New version email is switched off.
Presets are managed under workflows/:
/a/{team_slug}/artwork-approvals/api/v1/workflows/
approval_workflows_list ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/workflows/
approval_workflows_create ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/workflows/{id}/
approval_workflows_retrieve ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/workflows/{id}/
approval_workflows_partial_update ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/workflows/{id}/
approval_workflows_update ·
View in API reference
/a/{team_slug}/artwork-approvals/api/v1/workflows/{id}/
approval_workflows_destroy ·
View in API reference
| Field | Description |
|---|---|
| id | The preset's id: give it as workflow when you start an approval. |
| name | Required. The preset's name, up to 80 characters, unique in your team. |
| stages | Required. 1 to 6 stages in order (see below). |
| created_at | When the preset was made. |
| updated_at | When it was last changed. |
and each of its stages:
| Field | Description |
|---|---|
| name | Optional. The stage's name, up to 60 characters. Default: "Stage 1", "Stage 2"… |
| rule | all (default): every approver of the stage must approve. any: one approval is enough. |
| approvers | The stage's fixed approvers. A stage needs approvers, a variable, or both. |
| variable | Optional. A short lower-case name, such as customer: starting the preset takes that stage's remaining approvers from variables. |
| variable_label | Optional. What the Share dialog asks for, such as "Customer contact". |
Changing or deleting a preset does not change approvals already started with it.
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#
History for a portal reviewer#
/a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/reviewer-history/
Read this recipient's History panel using the same public_history and masked reviewer list as their personal proof viewer.
approval_requests_reviewer_history ·
View in API reference
approval-requests/<id>/reviewer-history/?recipient_email=buyer%40example.com returns email, request_id,
status, history and recipients. A team member's API key or session is required. The address must be an existing
recipient of this exact request; matching ignores case. An invalid address returns 400, an unknown recipient
or request outside the team returns 404, and an expired/revoked link returns 410.
This calls the same reviewer-history and masked-recipient helpers as the personal proof viewer, even when the API key belongs to a team administrator. Reviewers see version uploads and their link's creation, email activity, comments, decisions and resets. They do not see team-only email delivery logs, page-view tracking, internal notes, reset reasons, invitation messages or other reviewers' full addresses. Browser-owned comments on other links follow the viewer's identity-cookie rules; they are not inferred from the email address alone. A portal API request without that cookie gets the same scope as opening the personal invitation in a fresh browser.
Trusted portals must take the address from their authenticated login, verify the returned email/request scope and
load this response only when the user opens History. Never fall back to the full team-history endpoint for a
reviewer. Responses are private and not cached. This is read-only: it sends no email and changes no identity or
approval state. Internal staff continue to use artworks/<id>/history/ for the full audit timeline below.
/a/{team_slug}/artwork-approvals/api/v1/artworks/{id}/history/
Newest-first timeline: uploads, share links, decisions and resets.
artworks_history ·
View in API reference
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. Page-specific entries also include proof_url, a
relative portal URL selecting the version and page; comment links additionally select the comment. The kinds are:
| In the timeline | API label | API kind | What it records |
|---|---|---|---|
| v2 uploaded | Version uploaded | uploaded | A version was uploaded or sent from Files: its number, file name and notes, and the version number of its file in Files. |
| Simple link created for v2 (or Advanced link, 3D proof link) | Share link created | link_created | A link was made: Simple, Advanced or 3D, and its reviewers. Every upload makes the version's Simple and Advanced links. |
| Simple link for v2 expires on 1 May 2027 (or never expires) | Share link expiry changed | link_expiry | A team member changed when a link stops opening: the new date, or never. |
| Simple link revoked for v2 | Share link revoked | link_revoked | A team member revoked a link: its address stopped working at once. |
| Simple link emailed for v2 | Link sent to reviewers | sent | A link was emailed: to whom, and the message. |
| Approved v2, or Rejected v2 | Decision | decision | A reviewer approved or rejected a page or the whole PDF: the comment, progress, status, and whether the address was verified by an invitation link. |
| Reset to pending (was approved) | Reset to pending | reset | A team member reset a link to pending: the reason, the status before and the decisions it cleared. |
| Comment on v2 | Comment | comment | A comment: the start of its text, and its page, the 3D proof, or general. |
| Viewed page 2 · v2 | Page viewed | viewed | A PDF page was displayed in Flat or Booklet view: page, version, time and known reviewer or anonymous visitor.Team-only activity; viewing does not mean approval. |
| Email sent: Approval request · v2 (or Email not delivered) | Email sent | An email went out, to a reviewer or to your team: which email, its subject, each recipient, and whether your own mail account or AutomatePrint sent it. A failed delivery shows the mail server's reason. Team-only. | |
| Stage 1 of 2 approved: Prepress check | Stage completed | stage | A stage of a staged approval passed: its number and name, how many stages there are, and the stage that started next. |
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. Multipage decisions also include scope (file or
page), page, page_count, optional comment_id, and a saved progress object with approved, rejected,
remaining, total and complete. completed marks an action that completed the review or cleared its final
rejection. A viewed entry records page, surface (flat or booklet), name, anonymous and verified.
Page-view entries are team-only and never count as decisions. A link_expiry holds share_mode and the new
expires_at (null for never); a link_revoked holds share_mode. A reset holds reason, previous_status,
cleared_decisions and demoted_approvers. A stage holds stage (its number), name, total and next
(the name of the stage that started, or null after the last). A decision on a staged approval adds a stage object
with number, name, total, completed and next. An email holds email (which one), label, audience,
subject and deliveries: each with to, ok, via (team for your own mail account, platform for
AutomatePrint) and error. See History and notifications.
Errors#
400with 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."]}forsend/without addresses. An id of another team in the body (artworkon upload,versiononapproval-requests/) is a field error too ({"artwork": ["Invalid pk …"]}). An expiry in the past is{"expires_at": ["The expiry must be in the future."]}. Other refusals are400with{"detail": "…"}, such assend/orexpiry/on a revoked or expired link.400forfrom-file/with afile_versionthat 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 afiles_folderthat doesn't exist or is in the trash.507with{"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 owncode,detailand status.502with{"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.404for 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#
| Method | Path | What it does |
|---|---|---|
| GET | /a/{team_slug}/artwork-approvals/api/v1/approval-requests/ | approval_requests_list |
| POST | /a/{team_slug}/artwork-approvals/api/v1/approval-requests/ | Generate a simple or advanced viewer link and optionally email it to reviewers. |
| GET | /a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/ | approval_requests_retrieve |
| GET | /a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/comments/{comment_id}/thumbnail/ | PNG of a selected area or the context around a point (320 pixels on the long side). |
| POST | /a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/expiry/ | Set when the link stops opening: expires_in_days (1 to 365) or expires_at (null = never). |
| POST | /a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/reset/ | Put the request back to pending (clears every reviewer's decision). |
| GET | /a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/reviewer-history/ | Read this recipient's History panel using the same public_history and masked reviewer list as their personal proof viewer. |
| POST | /a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/revoke/ | Turn the link off at once: its address then answers 410 Gone. |
| POST | /a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/send/ | Email this link to reviewers (they are added as approvers). |
| GET | /a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/viewer-link/ | Get the signed personal viewer link for an existing recipient. |
| GET | /a/{team_slug}/artwork-approvals/api/v1/artworks/ | artworks_list |
| POST | /a/{team_slug}/artwork-approvals/api/v1/artworks/ | artworks_create |
| GET | /a/{team_slug}/artwork-approvals/api/v1/artworks/{id}/ | artworks_retrieve |
| PUT | /a/{team_slug}/artwork-approvals/api/v1/artworks/{id}/ | artworks_update |
| PATCH | /a/{team_slug}/artwork-approvals/api/v1/artworks/{id}/ | artworks_partial_update |
| GET | /a/{team_slug}/artwork-approvals/api/v1/artworks/{id}/history/ | Newest-first timeline: uploads, share links, decisions and resets. |
| GET | /a/{team_slug}/artwork-approvals/api/v1/artworks/{id}/versions/ | Every uploaded version of this artwork, newest first. |
| GET | /a/{team_slug}/artwork-approvals/api/v1/files/{file_id}/approvals/ | Where a file in Files stands in Approvals: every version of it that was sent for approval, newest first, with its status, who decided and when; and the file's current version when it is newer than the one in approval. |
| GET | /a/{team_slug}/artwork-approvals/api/v1/versions/ | artwork_versions_list |
| POST | /a/{team_slug}/artwork-approvals/api/v1/versions/ | Upload a PDF as the next version of an artwork. |
| GET | /a/{team_slug}/artwork-approvals/api/v1/versions/{id}/ | artwork_versions_retrieve |
| GET | /a/{team_slug}/artwork-approvals/api/v1/versions/{id}/3d/ | Whether the round's 3D proof (folded from its Files document's die) can be shown, and whether the artwork's Simple and Advanced links show it. |
| POST | /a/{team_slug}/artwork-approvals/api/v1/versions/{id}/3d/ | Show or hide the round 3D proof on the artwork's Simple and Advanced links (every version). |
| GET | /a/{team_slug}/artwork-approvals/api/v1/versions/{id}/advanced-preview/ | Build status of the separations preview (ready, building, failed, missing or stale). |
| POST | /a/{team_slug}/artwork-approvals/api/v1/versions/{id}/advanced-preview/ | Build the separations preview now, or retry a failed build. |
| GET | /a/{team_slug}/artwork-approvals/api/v1/versions/{id}/pdf/ | Download the version's PDF (team members only; the file is never public). |
| POST | /a/{team_slug}/artwork-approvals/api/v1/versions/{id}/request-approval/ | Create a simple or advanced share link for this version (same as POST approval-requests). |
| POST | /a/{team_slug}/artwork-approvals/api/v1/versions/{id}/share-links/ | The version's default simple and advanced links (created when missing). |
| GET | /a/{team_slug}/artwork-approvals/api/v1/versions/{id}/thumbnail/ | Small first-page PNG (200 pixels on its long side). |
| POST | /a/{team_slug}/artwork-approvals/api/v1/versions/from-file/ | Send a PDF version from Files for approval: the next version of the artwork that already proofs that file (or of `artwork`, or of a new artwork), using the same bytes, never a copy. |
| GET | /a/{team_slug}/artwork-approvals/api/v1/workflows/ | approval_workflows_list |
| POST | /a/{team_slug}/artwork-approvals/api/v1/workflows/ | approval_workflows_create |
| GET | /a/{team_slug}/artwork-approvals/api/v1/workflows/{id}/ | approval_workflows_retrieve |
| PUT | /a/{team_slug}/artwork-approvals/api/v1/workflows/{id}/ | approval_workflows_update |
| PATCH | /a/{team_slug}/artwork-approvals/api/v1/workflows/{id}/ | approval_workflows_partial_update |
| DELETE | /a/{team_slug}/artwork-approvals/api/v1/workflows/{id}/ | approval_workflows_destroy |