Getting Started with Truss API

The Truss API is a REST API served over HTTPS. It returns JSON, uses conventional HTTP response codes, and authenticates every request with an API key tied to a user in your firm.

All requests go to the same base URL:

https://app2.gettruss.io/api/v1

Get an API key

Sign in to Truss. Open the menu in the top-right corner and choose Integrations.
Under API Key, click Generate API Key.
Copy the key. Truss shows it once. After you leave the page, only the date it was generated remains visible.

API keys are available to full-access users. Generating a new key invalidates the previous one. See Authentication for details.

Make your first request

Send the key in the Authorization header as a bearer token.

curl https://app2.gettruss.io/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY"

Every successful response wraps its result in a data key:

{
  "data": [
    {
      "id": 48213,
      "name": "2025 Form 1040 - Frodo Baggins",
      "tax_year": 2025,
      "due_date": "2026-04-15",
      "idempotency_key": null,
      "metadata": {},
      "project_status": { "id": 310, "name": "Waiting on client", "position": 2 },
      "user": { "id": 902, "email": "[email protected]", "first_name": "Gandalf", "last_name": "Greyhame" }
    }
  ]
}

Create a project

A project is the unit of work in Truss: a tax return, an engagement, a filing. Most integrations start by creating one.

curl -X POST https://app2.gettruss.io/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "2025 Form 1040 - Frodo Baggins",
    "user_email": "[email protected]"
  }'

project_name is required, and so is one of user_email or user_id, which names the firm user who owns the project. The due date defaults to 30 days from now. The response is the full project, including its id. Pass contact_id to assign a client at the same time.

Add a client and a task

Clients are contacts in Truss. Assigning a contact to a project gives them a portal where they can see tasks and upload files. Here Frodo is the client and Gandalf, a user at the firm, owns the project.

curl -X POST https://app2.gettruss.io/api/v1/assignees \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "project_id": 48213, "assignee_email": "[email protected]" }'

If no contact with that email exists, Truss creates one. Then add something for the client to do:

curl -X POST https://app2.gettruss.io/api/v1/projects/48213/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Upload your W-2 from the Prancing Pony", "due_date": "2026-03-01" }'

New tasks are assigned to the project's default clients, so the client sees it immediately. When the client uploads a file, Truss changes the task to pending_review, and when every task on the project has been completed, the project is marked ready. You can watch all of this happen through Webhooks instead of polling.

Next steps

Core concepts explains how projects, tasks, contacts, and entities fit together.
Uploading files covers attaching documents to tasks and drive folders.
The API Reference tab lists every endpoint with request and response schemas, and lets you call the API from the browser with your key.