Developers

TrulyFinal API

Create projects, upload files, send them for review and hear back the moment a client decides. Every plan includes the API and webhooks.

Getting started

  1. In TrulyFinal, open Settings → Integrations and create a key. Name it after what will use it ("Zapier", "Website form"): what the key does shows under that name in your studio's activity.
  2. Send it as a Bearer token: Authorization: Bearer tf_…. The base URL is https://app.trulyfinal.com/api.
curl https://app.trulyfinal.com/api/v1/projects \
  -H "Authorization: Bearer tf_…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring campaign", "reference": "PO-1042" }'

curl "https://app.trulyfinal.com/api/v1/projects/prj_…/files?filename=brochure.pdf" \
  -H "Authorization: Bearer tf_…" \
  -H "Content-Type: application/pdf" \
  --data-binary @brochure.pdf

A key belongs to the studio, not to a person, so it keeps working when people come and go. It can do what an admin can, except billing and deleting the studio. Revoke it in the same place and it stops at once.

Errors, paging and limits

Every error has the same shape, with a stable code and a sentence you can show:

{ "error": { "code": "not_found", "message": "Project not found." } }
StatuscodeWhen
400invalid_requestA field is missing or wrong; the message names it.
401unauthorizedNo key, or a revoked one.
402plan_requiredThe studio's trial ended without a plan. Reading still works.
403forbiddenNot something a key may do (changing an owner, for example).
404not_foundIt doesn't exist, or it's in another studio.
409conflictIt can't be done now (an archived project, an older version).
413 / 415too_large / unsupported_fileThe file is too big, or not a format TrulyFinal reviews.
429rate_limitedMore than 120 requests a minute with one key. Wait for Retry-After.

Lists are newest first and come in pages: { "data": [...], "nextCursor": "…" }. Pass ?cursor= with the last nextCursor for the next page, and ?limit= (up to 100) to change the page size. nextCursor is null on the last page.

Webhooks

Add a webhook in Settings → Integrations, or from code with POST /v1/webhooks. Each event is POSTed as JSON with these headers:

  • TrulyFinal-Event: the event type, e.g. decision.made
  • TrulyFinal-Delivery: this delivery's id; the body's id is the event's, the same on every retry
  • TrulyFinal-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body">, keyed with the webhook's signing secret
{
  "id": "evt_01jd0…",
  "type": "decision.made",
  "createdAt": "2026-11-15T09:30:00.000Z",
  "studio": {
    "id": "org_…",
    "name": "North Studio"
  },
  "actor": {
    "type": "reviewer",
    "name": "Carla Client",
    "email": "carla@client.com"
  },
  "project": {
    "id": "prj_…",
    "name": "Spring campaign",
    "reference": "PO-1042",
    "url": "https://app.trulyfinal.com/projects/prj_…"
  },
  "file": {
    "id": "ast_…",
    "name": "Brochure",
    "externalId": "crm-42",
    "url": "https://app.trulyfinal.com/files/ast_…?v=2"
  },
  "version": {
    "id": "ver_…",
    "number": 2,
    "filename": "brochure-v2.pdf"
  },
  "review": {
    "id": "rnd_…",
    "stage": "Client review",
    "status": "approved",
    "dueAt": null
  },
  "data": {
    "value": "approved",
    "decision": {
      "id": "dec_…",
      "value": "approved",
      "note": null
    }
  }
}

Verifying the signature

import crypto from "node:crypto";

// header: TrulyFinal-Signature: t=1763200000,v1=5f2b…
function verify(secret, header, rawBody) {
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}

Answer with any 2xx within 10 seconds. Anything else is retried after 1 minute, 5 minutes, 30 minutes, then 2, 6, 12 and 24 hours: eight attempts over about two days. The settings page lists the last deliveries with what your server answered, and can send one again. "Send test event" sends a ping.

Paste a Slack, Discord or Google Chat incoming-webhook address (or a Basecamp chatbot's address) instead and the channel gets a short message for each event, with no code at all.

Events

TypeWhen
project.created · project.completed · project.archived · project.deletedA project starts, is marked complete, archived or deleted.
version.uploaded · version.ready · version.processing_failedA file or new version arrives, is ready to review, or couldn't be prepared.
round.started · stage.advanced · reviewer.invitedA version goes out for review, moves to the next stage, reviewers are added.
decision.made · decision.withdrawn · round.overriddenA reviewer approves or asks for changes (data.value), takes it back, or the team records it for them.
approval.sealed · approval.revokedA file is approved and its approval record sealed, or the approval is withdrawn.
round.overdueA review passes its due date.
comment.created · comment.replied · comment.resolvedComments, with the text in data.comment.
delivery.sent · delivery.downloadedFinal files are delivered, and the client downloads them.

Studio

The key and its studio

GET /api/v1/me

Check a key works and see which studio it belongs to.

Returns 200: object

Projects

List clients

GET /api/v1/clients

ParameterInType
limit optionalqueryintegerItems per page, up to 100.
cursor optionalquerystringnextCursor from the previous page.

Returns 200: ClientPage

Add a client

POST /api/v1/clients

Body fieldType
namestring

Returns 201: Client

List projects

GET /api/v1/projects

Newest first. updatedSince returns only projects changed after a time, for syncing.

ParameterInType
limit optionalqueryintegerItems per page, up to 100.
cursor optionalquerystringnextCursor from the previous page.
status optionalquery"active" | "completed" | "archived"
clientId optionalquerystring
updatedSince optionalquerydate-time

Returns 200: ProjectPage

Create a project

POST /api/v1/projects

Body fieldType
namestring
clientId optionalstring
reference optionalstringPO or job number.
dueAt optionaldate-time
templateId optionalstringSet the review stages up from a saved template (GET /v1/templates).

Returns 201: Project

Get a project

GET /api/v1/projects/{id}

ParameterInType
idpathstring

Returns 200: Project

Update a project

PATCH /api/v1/projects/{id}

Rename, change the client, reference or due date, complete, archive or reopen (status).

ParameterInType
idpathstring
Body fieldType
name optionalstring
clientId optionalstring
reference optionalstring | null
dueAt optionaldate-time
status optional"active" | "completed" | "archived"

Returns 200: Project

Delete a project

DELETE /api/v1/projects/{id}

It goes to Recently deleted and can be restored in the app for 30 days.

ParameterInType
idpathstring

Returns 200: object

Review steps

List a project's review stages

GET /api/v1/projects/{id}/steps

Team stages first, the client stage last.

ParameterInType
idpathstring

Returns 200: object

Set a project's review stages

PUT /api/v1/projects/{id}/steps

Up to three team stages before the client's. Only before any review has started.

ParameterInType
idpathstring
Body fieldType
internalStepsobject[]
clientName optionalstring
clientRule optional"all" | "any" | "threshold"
clientThreshold optionalinteger
clientDueDays optionalinteger | null

Returns 200: object

Invite reviewers and send files for review

POST /api/v1/projects/{id}/reviewers

Adds people to the client stage and emails each their own link (unless notify is false). With fileIds, those files go out for review at the same time.

ParameterInType
idpathstring
Body fieldType
reviewers optionalobject[]
fileIds optionalstring[]
message optionalstring
dueAt optionaldate-time

Returns 200: object

Remove a reviewer

DELETE /api/v1/projects/{id}/reviewers/{reviewerId}

ParameterInType
idpathstring
reviewerIdpathstring

Returns 200: object

Files

List a project's files

GET /api/v1/projects/{id}/files

ParameterInType
idpathstring
limit optionalqueryintegerItems per page, up to 100.
cursor optionalquerystringnextCursor from the previous page.

Returns 200: FilePage

Upload a file (or a new version)

POST /api/v1/projects/{id}/files

Two ways, both answered once the file is stored and being prepared (version.status = processing; the version.ready webhook says when it's ready):

  • The bytes as the body (up to 100 MB): send the file with its Content-Type and Content-Length, and the details as query parameters: ?filename=brochure.pdf&externalId=….
  • From a URL: send JSON { "url": "https://…", "filename": "…" }; TrulyFinal downloads it (useful from Zapier, Make and Power Automate).

Larger files: POST /v1/projects/{id}/uploads.

ParameterInType
idpathstring
filename optionalquerystring
fileId optionalquerystringUpload a new version of this file instead of a new file.
externalId optionalquerystring
note optionalquerystringWhat changed, shown with the version.

Returns 201: Uploaded

Find files by your own id

GET /api/v1/files

Every file whose externalId matches, across all projects.

ParameterInType
limit optionalqueryintegerItems per page, up to 100.
cursor optionalquerystringnextCursor from the previous page.
externalIdquerystring

Returns 200: FileSearchPage

Get a file and its versions

GET /api/v1/files/{id}

ParameterInType
idpathstring

Returns 200: FileDetail

Rename a file or set its external id

PATCH /api/v1/files/{id}

ParameterInType
idpathstring
Body fieldType
name optionalstring
externalId optionalstring | null

Returns 200: FileDetail

Delete a file

DELETE /api/v1/files/{id}

It goes to Recently deleted for 30 days.

ParameterInType
idpathstring

Returns 200: object

Start a large upload in parts

POST /api/v1/projects/{id}/uploads

For files over 100 MB. Then PUT each part (partSize bytes, the last one shorter) to /v1/uploads/{versionId}/parts/{n}?uploadId=…, and finish with POST /v1/uploads/{versionId}/complete.

ParameterInType
idpathstring
Body fieldType
filenamestring
fileId optionalstringUpload a new version of this file instead of a new file.
externalId optionalstring
note optionalstringWhat changed, shown with the version.
sizeinteger
mime optionalstring

Returns 201: object

Upload one part

PUT /api/v1/uploads/{versionId}/parts/{part}

The part's bytes as the body.

ParameterInType
versionIdpathstring
partpathinteger
uploadIdquerystring

Returns 200: object

Finish a large upload

POST /api/v1/uploads/{versionId}/complete

ParameterInType
versionIdpathstring
Body fieldType
uploadIdstring
partsobject[]

Returns 200: Uploaded

Download a version's original file

GET /api/v1/versions/{id}/download

ParameterInType
idpathstring

Returns 200 · The file as uploaded.

Reviews

A version's reviews, stage by stage

GET /api/v1/versions/{id}/reviews

ParameterInType
idpathstring

Returns 200: object

Send a version for review

POST /api/v1/versions/{id}/reviews

Without stepId it goes to the first stage and its reviewers. With stepId it starts at that stage, skipping the ones before. Only the latest, ready version.

ParameterInType
idpathstring
Body fieldType
stepId optionalstring
dueAt optionaldate-time
message optionalstring

Returns 200: object

Change a review's due date

PATCH /api/v1/reviews/{id}

ParameterInType
idpathstring
Body fieldType
dueAtdate-time

Returns 200: object

Record a decision on the client's behalf

POST /api/v1/reviews/{id}/decision

When a client approved or asked for changes outside TrulyFinal (by email, by phone). The approval record says who recorded it, how the client decided (basis) and why (reason). in_review reopens the review.

ParameterInType
idpathstring
Body fieldType
status"approved" | "changes_requested" | "in_review"
basis optional"email" | "phone" | "in_person" | "other"How the client approved; needed with approved.
reasonstring
reviewerId optionalstringThe reviewer it was decided for; else the review as a whole.

Returns 200: object

Comments

List a version's comments

GET /api/v1/versions/{id}/comments

Newest first; replies carry parentId.

ParameterInType
idpathstring
limit optionalqueryintegerItems per page, up to 100.
cursor optionalquerystringnextCursor from the previous page.

Returns 200: CommentPage

Comment on a version

POST /api/v1/versions/{id}/comments

Internal by default (the team only); internal: false shares it with the client. A pin needs page and x/y (0–1 from the top left).

ParameterInType
idpathstring
Body fieldType
bodystring
internal optionalboolean
parentId optionalstring
page optionalinteger
x optionalnumber
y optionalnumber
timeMs optionalinteger

Returns 201: Comment

Edit, resolve or reopen a comment

PATCH /api/v1/comments/{id}

A key can edit only its own comments; any top-level comment can be resolved.

ParameterInType
idpathstring
Body fieldType
body optionalstring
status optional"open" | "resolved"

Returns 200: Comment

Delete a comment

DELETE /api/v1/comments/{id}

A key can delete only its own comments (and AI findings).

ParameterInType
idpathstring

Returns 200: object

Templates

List workflow templates

GET /api/v1/templates

Returns 200: object

Save a workflow template

POST /api/v1/templates

Body fieldType
namestring
description optionalstring
stagesStagesInput

Returns 201: Template

Delete a workflow template

DELETE /api/v1/templates/{id}

ParameterInType
idpathstring

Returns 200: object

Members

List members

GET /api/v1/members

ParameterInType
limit optionalqueryintegerItems per page, up to 100.
cursor optionalquerystringnextCursor from the previous page.

Returns 200: MemberPage

Change a member's role

PATCH /api/v1/members/{id}

Owners can only be made or unmade by an owner, so a key can switch people between admin and member.

ParameterInType
idpathstring
Body fieldType
role"admin" | "member"

Returns 200: object

Remove a member

DELETE /api/v1/members/{id}

Their projects go to transferTo (a member's id), or to the studio's first owner.

ParameterInType
idpathstring
transferTo optionalquerystring

Returns 200: object

Webhooks

The events a webhook can receive

GET /api/v1/events

Returns 200: object

List webhooks

GET /api/v1/webhooks

Returns 200: object

Subscribe a URL to events

POST /api/v1/webhooks

Every event is POSTed as JSON, signed with TrulyFinal-Signature: t=<unix time>,v1=<hex HMAC-SHA256 of "t.body" with the secret>. Failed deliveries are retried over about two days. A webhook a key adds is removed when the key is revoked.

Body fieldType
urlstring
events optionalarray | null

Returns 201: Webhook

Unsubscribe

DELETE /api/v1/webhooks/{id}

ParameterInType
idpathstring

Returns 200: object

Objects

Member

idstring
namestring
emailstring
role"owner" | "admin" | "member"
joinedAtdate-time

Client

idstring
namestring
createdAtdate-time

Project

idstring
namestring
referencestring | null
status"active" | "completed" | "archived"
clientobject | null
dueAtdate-time
createdAtdate-time
updatedAtdate-time
urlstring

Step

idstring
namestring
audience"internal" | "client"
finalboolean
approvalRule"all" | "any" | "threshold"
thresholdnumber | null
dueDaysnumber | null
reviewersReviewer[]

Reviewer

idstring
namestring | null
emailstring | null
role"approver" | "reviewer" | "viewer"approver: their decision counts; reviewer: comments only; viewer: looks only

File

idstring
projectIdstring
namestring
kind"pdf" | "image" | "video"
statusstringdraft, in_review, changes_requested, approved…
externalIdstring | nullYour own id for this file (another system's record).
latestVersionVersion
createdAtdate-time
updatedAtdate-time
urlstring

Version

idstring
numbernumber
filenamestring
mimeTypestring
byteSizenumber
status"uploading" | "processing" | "ready" | "failed"
errorstring | null
pageCountnumber | null
createdAtdate-time

FileDetail

Uploaded

fileFileDetail
versionVersion

Review

idstring
stageobject
status"not_started" | "in_review" | "changes_requested" | "approved" | "superseded" | "canceled"
dueAtdate-time
startedAtdate-time
closedAtdate-time
reviewersobject[]

Comment

idstring
versionIdstring
parentIdstring | null
numbernumber | null
bodystring
internalbooleanSeen by the team only.
status"open" | "resolved" | "dismissed" | "reopened" | null
pagenumber | null1-based page of a document.
timeMsnumber | null
authorobject
createdAtdate-time
editedAtdate-time

Template

idstring
namestring
descriptionstring | null
stagesStagesInput
projectsnumberLive projects set up from it.
createdAtdate-time

Webhook

idstring
urlstring
eventsarray | nullnull: every event.
secretstring | nullVerifies the TrulyFinal-Signature header. null for chat apps, which get a plain message.
createdAtdate-time
Chat