How projects, tasks, contacts, assignees, entities, and drive folders fit together.
Truss organizes a firm's work around a small number of objects. This page explains what each one is and how they relate, so the endpoints in the API Reference make sense as a whole.
Projects
A project is one piece of client work: Frodo Baggins's 2025 Form 1040, a quarterly engagement for the Prancing Pony, a BOI filing for Bag End Holdings. It has a name, a due date, an owner (a firm user), an optional status, tags, and a free-form metadata object you can use to store your own identifiers.
Projects come in two shapes in API responses. List endpoints return a summary with scalar fields plus the owner and status. GET /projects/{id} and POST /projects return the extended project, which adds assignees, tasks, tags, and the linked entity.
A project is ready when every task on it has been completed by the client or approved by the firm. Truss tags it ready and sends the project.ready webhook. If the firm has configured an automatic status for completed projects, the status changes too.
Project statuses
Statuses are the columns of the firm's project board: "Waiting on client", "In review", "Filed with the Council". Each firm defines its own ordered list. GET /firms/project_status_dropdown returns them with their ids, and POST /projects/{id}/update_status moves a project between them. Pass status_id: 0 to clear the status.
Status ids are specific to a firm. Don't hard-code them; look them up once and cache the result.
Tasks
A task is an item on a project's checklist, usually something the client has to provide or do. Tasks belong to exactly one project and are addressed as /projects/{project_id}/tasks/{id}.
Every task has a status:
status | Meaning |
|---|---|
to_do | Open. The client hasn't completed it. |
pending_review | The client completed it, typically by uploading a file. The firm hasn't reviewed it yet. |
approved | The firm accepted it. |
Tasks also carry an optional document_category, the kind of document the task is about ("W-2", "1099-INT", "Schedule C"). Categories are global reference data; fetch them from GET /document_categories and pass an id as document_category_id. When you omit it, Truss infers a category from the task name.
A task is a plain checklist item unless you set task_type when creating it. The native types are invoice (a payment request, requires a connected Stripe account), contact_info_verification (asks the client to confirm details on file), and ez_sign (an engagement letter generated from one of the firm's templates). Each type has its own required fields, listed in the Reference under Tasks.
To create many tasks at once, use POST /projects/{project_id}/tasks/bulk_create with either an explicit list of up to 100 tasks or the id of a checklist template. The request is all-or-nothing.
Files on a task
A task can hold two kinds of files, and the API tells them apart with uploaded_by:
- Client uploads are what an assignee submits through their portal in response to the task.
- Firm uploads are files your staff, or your integration, attach to the task. See Uploading files.
Both appear in attached_files on the extended task, each with a temporary download_url valid for one hour and an attachment_id you can pass to GET /files/{file_id}/text_extraction to retrieve OCR text.
Comments and notes
Comments on a task are a conversation the client can see. commenter_type says whether a firm user or a client wrote each one. Posting a comment through the API emails the project's watchers, and emails the task's assignees if you ask it to.
Project notes are internal. Clients never see them. A note belongs to a project and can optionally point at one of its tasks, and every edit is kept in the note's history.
Contacts
A contact is a person: Frodo Baggins, his gardener Samwise Gamgee, the bookkeeper at the Prancing Pony. Contacts belong to the firm, not to any project, so one contact can be assigned to many projects over many years. A contact has one or more emails and phone numbers, with one of each marked primary, plus tags and an optional client_id_number that mirrors the id in your practice management or tax software.
Assignees
An assignee is a contact attached to a specific project. Assigning a contact gives them a portal where they see that project's tasks and can upload files, and it is how Truss decides who gets reminders and task emails.
There are two ways to assign. POST /assignees takes a project_id and an email address, and creates the contact first if no contact in the firm has that email. POST /assignees/create_by_contact_id attaches an existing contact by id. Each assignee has a magic_link, a URL that opens the client's upload page for the project without a password.
New tasks are assigned to the project's default clients. When the project has no default client, they go to every active client on it.
Entities
An entity is a household or a business, the thing a return is filed for: the Baggins household at Bag End, or Prancing Pony Inn LLC. Entities group the contacts who belong to it and the projects done for it across years, and carry the identifiers that persist when people change: client_id_number, ein, and other_ids.
Link a contact to an entity with POST /entities/{id}/link_contact and a project with POST /entities/{id}/link_project. Within an entity, a contact can have an email override, so prefer effective_email on a contact returned inside an entity or project over the contact's global primary email.
Users
Users are the firm's staff. They own projects and appear as user on projects and notes. Your API key belongs to a user, and the API behaves as that user: it returns what they can see and records what they do.
Drive folders
The drive is file storage that is not tied to a project: permanent client records, Bilbo's prior-year returns, firm documents. Folders nest under a single root folder per firm, and each file is either visible to clients in their portal or internal. The root folder itself cannot hold files.
Templates
Templates are reusable definitions the firm has set up in Truss. GET /templates?template_type=checklist_template lists checklist templates and the task names each one creates; pass a template's id to bulk_create to add all of its tasks to a project. GET /templates?template_type=engagement_letter_template lists engagement letter templates for ez_sign tasks.
How it fits together
Firm
├── Users (staff; your API key is one of these)
├── Contacts (people)
├── Entities (households and businesses)
│ ├── contacts (linked)
│ └── projects (linked)
├── Projects
│ ├── owner → User
│ ├── status → Project status
│ ├── assignees → Contacts (clients on this project)
│ ├── tasks
│ │ ├── files (client and firm uploads)
│ │ └── comments (visible to the client)
│ └── notes (internal)
└── Drive folders
└── files