Skip to content
Docs
Sign in

Approvals API

Create artworks, upload versions, make and email proof links, follow their status and read the full history of decisions.

For integrators

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#

GET /a/{team_slug}/artwork-approvals/api/v1/artworks/

artworks_list · View in API reference

POST /a/{team_slug}/artwork-approvals/api/v1/artworks/

artworks_create · View in API reference

GET /a/{team_slug}/artwork-approvals/api/v1/artworks/{id}/

artworks_retrieve · View in API reference

PATCH /a/{team_slug}/artwork-approvals/api/v1/artworks/{id}/

artworks_partial_update · View in API reference

PUT /a/{team_slug}/artwork-approvals/api/v1/artworks/{id}/

artworks_update · View in API reference

GET /a/{team_slug}/artwork-approvals/api/v1/artworks/{id}/versions/

Every uploaded version of this artwork, newest first.

artworks_versions · View in API reference

FieldDescription
idThe artwork's id.
nameThe artwork's name, up to 255 characters. You can write it, and allow_download.
allow_downloadWhether reviewers can download the PDF from the proof's ⋯ menu: false (the default) or true. Your team can always download it.
created_atWhen the artwork was created.
updated_atLast activity: uploads, links, emails, decisions, resets and comments move it forward.
version_countHow many versions the artwork has.
latest_versionThe 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#

POST /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

GET /a/{team_slug}/artwork-approvals/api/v1/versions/

artwork_versions_list · View in API reference

GET /a/{team_slug}/artwork-approvals/api/v1/versions/{id}/

artwork_versions_retrieve · View in API reference

GET /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

GET /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

GET /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

POST /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:

FieldDescription
artworkRequired. The artwork's id; the version gets the artwork's next number.
pdf_fileRequired. The PDF, at most 200 MB. The name must end in .pdf and the file must be a PDF.
notesOptional. What changed in this version, up to 5,000 characters.
client_file_pathOptional. 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_folderOptional. 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_reviewerstrue (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:

FieldDescription
idThe version's id.
artworkThe artwork's id.
version_number1, 2, 3 and so on, per artwork.
pdf_urlThe team download of the PDF (the pdf action). It needs your API key or session.
original_filenameThe uploaded file's name.
client_file_pathWhat you sent as client_file_path, or empty.
spot_colorsThe names of the spot colours found in the PDF, in the order they were found.
notesThe version's notes.
uploaded_atWhen the version was uploaded.
advanced_previewThe separations preview: status ready, building (with progress), failed, missing or stale.
file_idThe id of the Files file the version was made from, or null for a version from before Files.
file_versionThe id of that version in Files, or null.
file_version_numberIts version number in Files (v5), which is independent of version_number; or null.
file_latest_version_numberThe 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#

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.

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:

FieldDescription
file_versionRequired. The id of a ready PDF version in your team's Files, at most 200 MB.
artworkOptional. The artwork that gets the version. Default: the artwork that already proofs this file, else a new one.
nameOptional. The name of a new artwork, up to 255 characters. Default: the file name without .pdf.
notesOptional. What changed in this version, up to 5,000 characters.
share_modesimple (default) or advanced: the link emailed to the reviewers.
emailsOptional. Up to 50 reviewer addresses to email the link to. They become invited approvers.
same_reviewerstrue also emails the approvers of the artwork's previous version (default false). Nobody is emailed again when no version was added.
messageOptional text above the link in the email, up to 5,000 characters.
notify_reviewerstrue (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#

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.

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).

FieldDescription
fileThe file's id in Files.
current_versionThe file's current version number in Files, or null.
approvalsEvery version of the file that was sent for approval, newest first (see below).
newerSet 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:

FieldDescription
artworkThe artwork's id.
nameThe artwork's name.
urlThe Approvals page, searched for the artwork.
versionThe id of the artwork version (the proof round).
version_numberIts number in the artwork: 1, 2, 3 and so on.
file_versionThe version number in Files it was made from (v2).
print_readytrue when it proofs the print-ready file made from that version in the 1-up editor.
statusdraft (not sent to anyone yet), pending (out for approval), approved, or rejected (changes requested).
supersededtrue once a later version of the artwork replaced it: it can no longer be approved.
decided_atWhen it was approved or rejected (the latest decision that counted), or null.
decided_byThe names of up to 5 approvers who gave that decision, latest first.
stageFor a staged approval that is under way: number, total and name of the stage deciding now.
reviewersHow many approvers it has.
created_atWhen the version was sent to Approvals.

newer describes the version waiting in Files:

FieldDescription
version_idThe id of the file's current version in Files: give it as file_version to versions/from-file/.
numberIts version number in Files.
artworkThe id of the artwork that gets it.
nameThat artwork's name.
roundThe artwork version number it would get.
previousThe artwork's latest version, which it would replace (an approvals entry, as above).
reviewersThe addresses same_reviewers would email: the approvers of that latest version.
stagedtrue 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.

POST /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

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.

artwork_versions_3d · View in API reference

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).

artwork_versions_3d_set · View in API reference

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).

artwork_versions_request_approval · View in API reference

GET /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

POST /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

GET /a/{team_slug}/artwork-approvals/api/v1/approval-requests/

approval_requests_list · View in API reference

GET /a/{team_slug}/artwork-approvals/api/v1/approval-requests/{id}/

approval_requests_retrieve · View in API reference

POST /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

POST /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

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).

approval_requests_expiry · View in API reference

POST /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:

FieldDescription
versionRequired on approval-requests/. The version's id; request-approval/ takes it from its URL.
share_modesimple (default) or advanced: the viewer the link opens.
emailsOptional. Up to 50 reviewer addresses. They become invited approvers of the link.
subjectOptional email subject, up to 255 characters. Default: "Approval requested: <artwork> v<number>".
messageOptional text above the link in the email, up to 5,000 characters.
send_emailtrue (default) emails the link to emails; false only adds them as approvers.
stagesOptional. 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.
workflowOptional, instead of stages: the id of a staged-approval preset to start.
variablesWith workflow: the addresses for the preset's variables, as an object of variable name to a list of emails.
expires_in_daysOptional. The link stops opening this many days from now, 1 to 365.
expires_atOptional. 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:

FieldDescription
emailsRequired. 1 to 50 reviewer addresses. Each gets a personal link and becomes an approver.
messageOptional 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):

FieldDescription
reasonOptional. 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:

FieldDescription
expires_in_days1 to 365: the link stops opening this many days from now.
expires_atInstead 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:

FieldDescription
idThe link's id.
tokenThe secret part of the link's address. Anyone who has it can open the proof.
urlThe reviewer link to open or send.
viewer_linkPersonal 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_modesimple or advanced.
viewsThe proof views the link was made with: ["flat"], or with "3d" for a 3D proof.
sceneThe id of the link's 3D proof, or null.
statuspending, approved or rejected (the link's own status).
artworkThe artwork's id.
versionThe version's id.
version_numberThe version's number.
requested_byThe name of the team member who made the link, or empty.
email_subjectThe subject its emails use.
email_messageThe message sent with it when it was made.
created_atWhen the link was made.
expires_atWhen the link stops opening, or null for never.
revoked_atWhen a team member revoked the link, or null.
is_opentrue while the link opens: not revoked and not expired. A closed link answers 410 Gone.
current_stageFor a staged approval: the number of the stage that is deciding now. 1 without stages.
stagesFor a staged approval: every stage with its state and approvers (see below). Empty without stages.
recipientsThe link's reviewers (see below).
commentsEvery comment made on the link (see below).

Its recipients are:

FieldDescription
idThe reviewer's id on this link.
emailTheir email address, in full.
nameThe name they gave, or empty.
roleapprover or viewer.
stageFor a staged approval: the number of the stage they decide in. 1 without stages.
decisionpending, approved or rejected.
decision_atWhen they last decided, or null.
page_decisionsRead-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:

FieldDescription
idThe comment's id.
pageThe page, from 1; 0 for a general comment made with a decision.
xDistance from the left edge of the page, in points.
yDistance from the top edge of the page, in points.
widthThe width of the marked area in points; 0 for a spot.
heightThe height of the marked area in points; 0 for a spot.
surfaceflat or 3d.
anchorFor 3D comments: where the pin sits on the carton, and the camera it was made with.
contentThe comment's text, up to 5,000 characters.
commenterThe email address of who wrote it.
thumbnail_urlTeam-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_atWhen 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.

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).

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.

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:

FieldDescription
nameOptional. The stage's name, up to 60 characters. Default: "Stage 1", "Stage 2"…
ruleall (default): every approver of the stage must approve. any: one approval is enough.
emailsRequired. 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:

FieldDescription
numberThe stage's place in the order, from 1.
nameThe stage's name.
ruleall or any.
statewaiting (not started), active (its approvers are deciding now), approved, or rejected (an approver of the active stage rejected: the approval is held there).
approversThe 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/:

GET /a/{team_slug}/artwork-approvals/api/v1/workflows/

approval_workflows_list · View in API reference

POST /a/{team_slug}/artwork-approvals/api/v1/workflows/

approval_workflows_create · View in API reference

GET /a/{team_slug}/artwork-approvals/api/v1/workflows/{id}/

approval_workflows_retrieve · View in API reference

PATCH /a/{team_slug}/artwork-approvals/api/v1/workflows/{id}/

approval_workflows_partial_update · View in API reference

PUT /a/{team_slug}/artwork-approvals/api/v1/workflows/{id}/

approval_workflows_update · View in API reference

DELETE /a/{team_slug}/artwork-approvals/api/v1/workflows/{id}/

approval_workflows_destroy · View in API reference

FieldDescription
idThe preset's id: give it as workflow when you start an approval.
nameRequired. The preset's name, up to 80 characters, unique in your team.
stagesRequired. 1 to 6 stages in order (see below).
created_atWhen the preset was made.
updated_atWhen it was last changed.

and each of its stages:

FieldDescription
nameOptional. The stage's name, up to 60 characters. Default: "Stage 1", "Stage 2"…
ruleall (default): every approver of the stage must approve. any: one approval is enough.
approversThe stage's fixed approvers. A stage needs approvers, a variable, or both.
variableOptional. A short lower-case name, such as customer: starting the preset takes that stage's remaining approvers from variables.
variable_labelOptional. 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#

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.

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.

GET /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 timelineAPI labelAPI kindWhat it records
v2 uploadedVersion uploadeduploadedA 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 createdlink_createdA 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 changedlink_expiryA team member changed when a link stops opening: the new date, or never.
Simple link revoked for v2Share link revokedlink_revokedA team member revoked a link: its address stopped working at once.
Simple link emailed for v2Link sent to reviewerssentA link was emailed: to whom, and the message.
Approved v2, or Rejected v2DecisiondecisionA 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 pendingresetA team member reset a link to pending: the reason, the status before and the decisions it cleared.
Comment on v2CommentcommentA comment: the start of its text, and its page, the 3D proof, or general.
Viewed page 2 · v2Page viewedviewedA 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 sentemailAn 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 checkStage completedstageA 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#

  • 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 …"]}). An expiry in the past is {"expires_at": ["The expiry must be in the future."]}. Other refusals are 400 with {"detail": "…"}, such as send/ or expiry/ on a revoked or expired link.
  • 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#

API operations tagged artwork-approvals
MethodPathWhat 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

All “artwork-approvals” operations in the API reference

Last updated Nov. 18, 2026