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
- 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.
- Send it as a Bearer token:
Authorization: Bearer tf_…. The base URL ishttps://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.pdfA 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." } }| Status | code | When |
|---|---|---|
| 400 | invalid_request | A field is missing or wrong; the message names it. |
| 401 | unauthorized | No key, or a revoked one. |
| 402 | plan_required | The studio's trial ended without a plan. Reading still works. |
| 403 | forbidden | Not something a key may do (changing an owner, for example). |
| 404 | not_found | It doesn't exist, or it's in another studio. |
| 409 | conflict | It can't be done now (an archived project, an older version). |
| 413 / 415 | too_large / unsupported_file | The file is too big, or not a format TrulyFinal reviews. |
| 429 | rate_limited | More 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.madeTrulyFinal-Delivery: this delivery's id; the body'sidis the event's, the same on every retryTrulyFinal-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
| Type | When |
|---|---|
project.created · project.completed · project.archived · project.deleted | A project starts, is marked complete, archived or deleted. |
version.uploaded · version.ready · version.processing_failed | A file or new version arrives, is ready to review, or couldn't be prepared. |
round.started · stage.advanced · reviewer.invited | A version goes out for review, moves to the next stage, reviewers are added. |
decision.made · decision.withdrawn · round.overridden | A reviewer approves or asks for changes (data.value), takes it back, or the team records it for them. |
approval.sealed · approval.revoked | A file is approved and its approval record sealed, or the approval is withdrawn. |
round.overdue | A review passes its due date. |
comment.created · comment.replied · comment.resolved | Comments, with the text in data.comment. |
delivery.sent · delivery.downloaded | Final 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
| Parameter | In | Type | |
|---|---|---|---|
limit optional | query | integer | Items per page, up to 100. |
cursor optional | query | string | nextCursor from the previous page. |
Returns 200: ClientPage
Add a client
POST /api/v1/clients
| Body field | Type | |
|---|---|---|
name | string |
Returns 201: Client
List projects
GET /api/v1/projects
Newest first. updatedSince returns only projects changed after a time, for syncing.
| Parameter | In | Type | |
|---|---|---|---|
limit optional | query | integer | Items per page, up to 100. |
cursor optional | query | string | nextCursor from the previous page. |
status optional | query | "active" | "completed" | "archived" | |
clientId optional | query | string | |
updatedSince optional | query | date-time |
Returns 200: ProjectPage
Create a project
POST /api/v1/projects
| Body field | Type | |
|---|---|---|
name | string | |
clientId optional | string | |
reference optional | string | PO or job number. |
dueAt optional | date-time | |
templateId optional | string | Set the review stages up from a saved template (GET /v1/templates). |
Returns 201: Project
Get a project
GET /api/v1/projects/{id}
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
Returns 200: Project
Update a project
PATCH /api/v1/projects/{id}
Rename, change the client, reference or due date, complete, archive or reopen (status).
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
| Body field | Type | |
|---|---|---|
name optional | string | |
clientId optional | string | |
reference optional | string | null | |
dueAt optional | date-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.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
Returns 200: object
Review steps
List a project's review stages
GET /api/v1/projects/{id}/steps
Team stages first, the client stage last.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
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.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
| Body field | Type | |
|---|---|---|
internalSteps | object[] | |
clientName optional | string | |
clientRule optional | "all" | "any" | "threshold" | |
clientThreshold optional | integer | |
clientDueDays optional | integer | 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.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
| Body field | Type | |
|---|---|---|
reviewers optional | object[] | |
fileIds optional | string[] | |
message optional | string | |
dueAt optional | date-time |
Returns 200: object
Remove a reviewer
DELETE /api/v1/projects/{id}/reviewers/{reviewerId}
| Parameter | In | Type | |
|---|---|---|---|
id | path | string | |
reviewerId | path | string |
Returns 200: object
Files
List a project's files
GET /api/v1/projects/{id}/files
| Parameter | In | Type | |
|---|---|---|---|
id | path | string | |
limit optional | query | integer | Items per page, up to 100. |
cursor optional | query | string | nextCursor 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-TypeandContent-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.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string | |
filename optional | query | string | |
fileId optional | query | string | Upload a new version of this file instead of a new file. |
externalId optional | query | string | |
note optional | query | string | What 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.
| Parameter | In | Type | |
|---|---|---|---|
limit optional | query | integer | Items per page, up to 100. |
cursor optional | query | string | nextCursor from the previous page. |
externalId | query | string |
Returns 200: FileSearchPage
Get a file and its versions
GET /api/v1/files/{id}
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
Returns 200: FileDetail
Rename a file or set its external id
PATCH /api/v1/files/{id}
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
| Body field | Type | |
|---|---|---|
name optional | string | |
externalId optional | string | null |
Returns 200: FileDetail
Delete a file
DELETE /api/v1/files/{id}
It goes to Recently deleted for 30 days.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
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.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
| Body field | Type | |
|---|---|---|
filename | string | |
fileId optional | string | Upload a new version of this file instead of a new file. |
externalId optional | string | |
note optional | string | What changed, shown with the version. |
size | integer | |
mime optional | string |
Returns 201: object
Upload one part
PUT /api/v1/uploads/{versionId}/parts/{part}
The part's bytes as the body.
| Parameter | In | Type | |
|---|---|---|---|
versionId | path | string | |
part | path | integer | |
uploadId | query | string |
Returns 200: object
Finish a large upload
POST /api/v1/uploads/{versionId}/complete
| Parameter | In | Type | |
|---|---|---|---|
versionId | path | string |
| Body field | Type | |
|---|---|---|
uploadId | string | |
parts | object[] |
Returns 200: Uploaded
Download a version's original file
GET /api/v1/versions/{id}/download
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
Returns 200 · The file as uploaded.
Reviews
A version's reviews, stage by stage
GET /api/v1/versions/{id}/reviews
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
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.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
| Body field | Type | |
|---|---|---|
stepId optional | string | |
dueAt optional | date-time | |
message optional | string |
Returns 200: object
Change a review's due date
PATCH /api/v1/reviews/{id}
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
| Body field | Type | |
|---|---|---|
dueAt | date-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.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
| Body field | Type | |
|---|---|---|
status | "approved" | "changes_requested" | "in_review" | |
basis optional | "email" | "phone" | "in_person" | "other" | How the client approved; needed with approved. |
reason | string | |
reviewerId optional | string | The reviewer it was decided for; else the review as a whole. |
Returns 200: object
Templates
List workflow templates
GET /api/v1/templates
Returns 200: object
Save a workflow template
POST /api/v1/templates
| Body field | Type | |
|---|---|---|
name | string | |
description optional | string | |
stages | StagesInput |
Returns 201: Template
Delete a workflow template
DELETE /api/v1/templates/{id}
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
Returns 200: object
Members
List members
GET /api/v1/members
| Parameter | In | Type | |
|---|---|---|---|
limit optional | query | integer | Items per page, up to 100. |
cursor optional | query | string | nextCursor 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.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
| Body field | Type | |
|---|---|---|
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.
| Parameter | In | Type | |
|---|---|---|---|
id | path | string | |
transferTo optional | query | string |
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 field | Type | |
|---|---|---|
url | string | |
events optional | array | null |
Returns 201: Webhook
Unsubscribe
DELETE /api/v1/webhooks/{id}
| Parameter | In | Type | |
|---|---|---|---|
id | path | string |
Returns 200: object
Objects
Member
id | string | |
name | string | |
email | string | |
role | "owner" | "admin" | "member" | |
joinedAt | date-time |
Client
id | string | |
name | string | |
createdAt | date-time |
Project
id | string | |
name | string | |
reference | string | null | |
status | "active" | "completed" | "archived" | |
client | object | null | |
dueAt | date-time | |
createdAt | date-time | |
updatedAt | date-time | |
url | string |
Step
id | string | |
name | string | |
audience | "internal" | "client" | |
final | boolean | |
approvalRule | "all" | "any" | "threshold" | |
threshold | number | null | |
dueDays | number | null | |
reviewers | Reviewer[] |
Reviewer
id | string | |
name | string | null | |
email | string | null | |
role | "approver" | "reviewer" | "viewer" | approver: their decision counts; reviewer: comments only; viewer: looks only |
File
id | string | |
projectId | string | |
name | string | |
kind | "pdf" | "image" | "video" | |
status | string | draft, in_review, changes_requested, approved… |
externalId | string | null | Your own id for this file (another system's record). |
latestVersion | Version | |
createdAt | date-time | |
updatedAt | date-time | |
url | string |
Version
id | string | |
number | number | |
filename | string | |
mimeType | string | |
byteSize | number | |
status | "uploading" | "processing" | "ready" | "failed" | |
error | string | null | |
pageCount | number | null | |
createdAt | date-time |
FileDetail
Uploaded
file | FileDetail | |
version | Version |
Review
id | string | |
stage | object | |
status | "not_started" | "in_review" | "changes_requested" | "approved" | "superseded" | "canceled" | |
dueAt | date-time | |
startedAt | date-time | |
closedAt | date-time | |
reviewers | object[] |
Comment
id | string | |
versionId | string | |
parentId | string | null | |
number | number | null | |
body | string | |
internal | boolean | Seen by the team only. |
status | "open" | "resolved" | "dismissed" | "reopened" | null | |
page | number | null | 1-based page of a document. |
timeMs | number | null | |
author | object | |
createdAt | date-time | |
editedAt | date-time |
Template
id | string | |
name | string | |
description | string | null | |
stages | StagesInput | |
projects | number | Live projects set up from it. |
createdAt | date-time |
Webhook
id | string | |
url | string | |
events | array | null | null: every event. |
secret | string | null | Verifies the TrulyFinal-Signature header. null for chat apps, which get a plain message. |
createdAt | date-time |
Comments
List a version's comments
GET
/api/v1/versions/{id}/commentsNewest first; replies carry
parentId.idlimitoptionalcursoroptionalnextCursorfrom the previous page.Returns 200:
CommentPageComment on a version
POST
/api/v1/versions/{id}/commentsInternal by default (the team only);
internal: falseshares it with the client. A pin needspageandx/y(0–1 from the top left).idbodyinternaloptionalparentIdoptionalpageoptionalxoptionalyoptionaltimeMsoptionalReturns 201:
CommentEdit, 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.
idbodyoptionalstatusoptionalReturns 200:
CommentDelete a comment
DELETE
/api/v1/comments/{id}A key can delete only its own comments (and AI findings).
idReturns 200:
object