# Truss API Documentation

> Documentation for Truss API

## API Reference: API V1
- Projects
  - [Get project](https://truss-api.readme.io/reference/get_projects-id.md)
  - [Update project](https://truss-api.readme.io/reference/put_projects-id.md): Update a project
  - [Get project by idempotency key](https://truss-api.readme.io/reference/get_projects-get-by-idempotency-key.md): Returns a project by idempotency key
  - [List projects by metadata](https://truss-api.readme.io/reference/get_projects-list-by-metadata-key.md): Returns projects that match the provided metadata key-value pair. The metadata key and value must match exactly. Returns a 404 if no project is found.
  - [List all projects](https://truss-api.readme.io/reference/get_projects.md): List all projects
  - [Create project](https://truss-api.readme.io/reference/post_projects.md)
  - [Update project status](https://truss-api.readme.io/reference/post_projects-id-update-status.md): Updates the status of a project
  - [Search projects](https://truss-api.readme.io/reference/get_projects-search.md): Search and filter projects using various criteria
- Project Statuses
  - [Get all project statuses](https://truss-api.readme.io/reference/get_firms-project-status-dropdown.md)
- Contacts
  - [Get contact](https://truss-api.readme.io/reference/get_contacts-contact-id.md): Returns a contact by contact_id
  - [Search contacts](https://truss-api.readme.io/reference/get_contacts-search.md): Search and filter contacts using various criteria
  - [List all contacts](https://truss-api.readme.io/reference/get_contacts.md): Lists all contacts for the firm
  - [Creates a contact](https://truss-api.readme.io/reference/post_contacts.md)
  - [Get contacts for dropdown](https://truss-api.readme.io/reference/get_contacts-dropdown.md): Get simplified contact list for dropdown menus
- Entities
  - [List all entities](https://truss-api.readme.io/reference/get_entities.md): Returns a paginated list of all entities in the current user's firm. Results are paginated using `page` and `per_page` parameters. Use `extended_view=true` to include full contact, project, and tag…
  - [Get entity](https://truss-api.readme.io/reference/get_entities-id.md): Returns an entity by ID, including extended info.
  - [Create an entity](https://truss-api.readme.io/reference/post_entities.md): Create a new entity for the current firm.
  - [Search entities](https://truss-api.readme.io/reference/get_entities-search.md): Search and filter entities using various criteria
  - [Link entity to contact](https://truss-api.readme.io/reference/post_entities-id-link-contact.md): Link a specified contact to an entity by their IDs.
  - [Link entity to project](https://truss-api.readme.io/reference/post_entities-id-link-project.md): Link a specified project to an entity by their IDs.
- Tasks
  - [List tasks in project](https://truss-api.readme.io/reference/get_projects-project-id-tasks.md): List all tasks in the given project_id.
  - [Create task](https://truss-api.readme.io/reference/post_projects-project-id-tasks.md): Creates a task inside a project. Omit task_type for a plain task; see Task types for the native types and the fields each one requires.
  - [Get task](https://truss-api.readme.io/reference/get_projects-project-id-tasks-id.md): Returns full details on a task by task_id, including task-level and assignee task file attachments.
  - [Bulk create tasks](https://truss-api.readme.io/reference/post_projects-project-id-tasks-bulk-create.md): Bulk-creates up to 100 tasks inside a project. Pass exactly one of bulk_tasks or checklist_template_id. The request is all-or-nothing - if any task is invalid, no tasks are created and the response…
  - [Update task](https://truss-api.readme.io/reference/put_projects-project-id-tasks-id.md): Updates a task's name, description, status, and due date
  - [Delete task](https://truss-api.readme.io/reference/delete_projects-project-id-tasks-id.md): Deletes a task
  - [Get signed URL for direct-to-cloud upload to a task](https://truss-api.readme.io/reference/post_projects-project-id-tasks-direct-upload.md): Get a signed URL for direct-to-cloud upload using ActiveStorage - step 1 of uploading files to a task. Upload the file bytes to the returned URL, then attach the blob to a task by passing its…
  - [Add files to task](https://truss-api.readme.io/reference/post_projects-project-id-tasks-id-add-files-to-task.md): Upload files to a task. Files attach at the task level (task.files, i.e. firm-uploaded files, listed in attached_files with uploaded_by=firm). Provide either a publicly accessible URL for Truss to…
  - [List document categories](https://truss-api.readme.io/reference/get_document-categories.md): The document types a task can be filed under - "W-2", "1099-INT", "Schedule C" and so on. The list is global rather than per firm, so it is reference data: read it once and use an id as…
  - [List task comments](https://truss-api.readme.io/reference/get_projects-project-id-tasks-task-id-comments.md): Returns every comment on the task, oldest first. Comments from firm users and from clients (assignees) are both included; commenter_type tells them apart.
  - [Create task comment](https://truss-api.readme.io/reference/post_projects-project-id-tasks-task-id-comments.md): Adds a comment to the task, authored by the authenticated API user. Watchers on the project are emailed, the same as when a firm user comments in the app; the task's assignees are emailed only when…
- Assign to Project
  - [Add email to project](https://truss-api.readme.io/reference/post_assignees.md): Assignee to project by email address.
  - [Assign to project by contact ID](https://truss-api.readme.io/reference/post_assignees-create-by-contact-id.md)
- Users
  - [Show all firm users](https://truss-api.readme.io/reference/get_users.md)
  - [Create firm user](https://truss-api.readme.io/reference/post_users.md)
  - [Show details for a firm user](https://truss-api.readme.io/reference/get_users-id.md)
- Webhook Events
  - [project.created](https://truss-api.readme.io/reference/post_project-created.md): Triggered when a new project is created
  - [project.modified](https://truss-api.readme.io/reference/post_project-modified.md): Triggered when a project is modified
  - [project.ready](https://truss-api.readme.io/reference/post_project-ready.md): Triggered when a project is marked as ready
  - [contact.created](https://truss-api.readme.io/reference/post_contact-created.md): Triggered when a new contact is created
  - [contact.modified](https://truss-api.readme.io/reference/post_contact-modified.md): Triggered when a contact is modified
  - [file.created](https://truss-api.readme.io/reference/post_file-created.md): Triggered when a file is uploaded to a task. Note this is the one event whose payload is not wrapped in a data envelope — the fields sit directly on payload.
  - [task.created](https://truss-api.readme.io/reference/post_task-created.md): Triggered when a new task is created
  - [task.modified](https://truss-api.readme.io/reference/post_task-modified.md): Triggered when a task is modified
  - [comment.created](https://truss-api.readme.io/reference/post_comment-created.md): Triggered when a new comment is created
  - [status.modified](https://truss-api.readme.io/reference/post_status-modified.md): Triggered when a project status is modified
  - [esignature.completed](https://truss-api.readme.io/reference/post_esignature-completed.md): Triggered when an e-signature request is completed
  - [entity.created](https://truss-api.readme.io/reference/post_entity-created.md): Triggered when a new entity is created.
  - [entity.contact_linked](https://truss-api.readme.io/reference/post_entity-contact-linked.md): Triggered when a contact is linked to an entity. Note the payload is the linked contact, not the entity.
  - [entity.project_linked](https://truss-api.readme.io/reference/post_entity-project-linked.md): Triggered when a project is linked to an entity. Note the payload is the linked project, not the entity.
  - [stripe.complete](https://truss-api.readme.io/reference/post_stripe-complete.md): Triggered when an invoice task is paid through Stripe Checkout. Fires only for a task that was still to_do; the task moves to pending_review as part of the same change. The payload is the task, not…
- Project Notes
  - [Get project note (latest)](https://truss-api.readme.io/reference/get_projects-project-id-note.md): Returns the project's most recent internal note about the project itself (task notes are left out). Projects can have many notes; use GET /projects/{project_id}/notes to list them all.
  - [Create project note](https://truss-api.readme.io/reference/post_projects-project-id-note.md): Creates an internal note about the project when it has none (task notes don't count). Returns 422 if the project already has one - use PUT to update it, or POST /projects/{project_id}/notes to add…
  - [Update project note (latest)](https://truss-api.readme.io/reference/put_projects-project-id-note.md): Updates the body of the project's most recent note about the project itself (never a task's note) and records the current user as last_edited_by.
  - [Delete project note (latest)](https://truss-api.readme.io/reference/delete_projects-project-id-note.md): Deletes the project's most recent note about the project itself (never a task's note). Its history is kept.
  - [List project notes](https://truss-api.readme.io/reference/get_projects-project-id-notes.md): Returns all of the project's internal notes, newest first.
  - [Add a project note](https://truss-api.readme.io/reference/post_projects-project-id-notes.md): Adds an internal note to the project, optionally linked to one of its tasks. A task can have any number of notes.
  - [Get a project note](https://truss-api.readme.io/reference/get_projects-project-id-notes-id.md)
  - [Update a project note](https://truss-api.readme.io/reference/put_projects-project-id-notes-id.md): Changes the note's body, its task link, or both, and records the current user as last_edited_by. Anyone on the firm can edit any note; every change is recorded in its history.
  - [Delete a project note](https://truss-api.readme.io/reference/delete_projects-project-id-notes-id.md): Deletes the note. Its history is kept and stays readable at /notes/{id}/history.
  - [Get a project note's history](https://truss-api.readme.io/reference/get_projects-project-id-notes-id-history.md): Every change to the note, oldest first - who made it, when, how, and the content before and after. Available after the note is deleted.
- Files
  - [Get OCR text for a file](https://truss-api.readme.io/reference/get_files-file-id-text-extraction.md): Returns the OCR status and normalized plain text for a task, assignee task, or drive folder file. OAuth clients must have the files_read scope. Text is null while OCR is still processing or when OCR…
- Templates
  - [List templates](https://truss-api.readme.io/reference/get_templates.md): Lists the firm's templates for the requested template type. Checklist templates return their task names; engagement letter templates return whether all clients must sign.
- Drive Folders
  - [List root drive sub-folders](https://truss-api.readme.io/reference/get_drive-folders.md): List all top-level sub-folders under the firm's root drive folder. Results are paginated using `page` and `per_page` parameters.
  - [Get signed URL for direct-to-cloud upload](https://truss-api.readme.io/reference/post_drive-folders-direct-upload.md): Get a signed URL for direct-to-cloud upload using ActiveStorage. Requires the drive_folders_write scope.
  - [Add files to folder](https://truss-api.readme.io/reference/post_drive-folders-id-add-files-to-folder.md): Upload files into a drive folder using external URLs. Files are downloaded by Truss, stored in S3, and attached to the folder. Root folder cannot accept files.
  - [Create drive folder](https://truss-api.readme.io/reference/post_drive-folders.md): Create a new folder under the specified parent folder. Drive must be activated for the firm.
  - [Get drive folder](https://truss-api.readme.io/reference/get_drive-folders-id.md): Get a single drive folder, including nested sub-folders and attached files.
  - [Update drive folder](https://truss-api.readme.io/reference/put_drive-folders-id.md): Update a drive folder's name and client visibility. Root folder and entity folders cannot be updated (update the entity name instead).
  - [Delete drive folder](https://truss-api.readme.io/reference/delete_drive-folders-id.md): Soft-delete a drive folder. Root folder and entity folders cannot be deleted.
  - [Get drive folder including deleted files](https://truss-api.readme.io/reference/get_drive-folders-id-show-folder-with-deleted-files.md): Get a single drive folder including its deleted files (files that were previously removed from the folder).
  - [Edit file in folder](https://truss-api.readme.io/reference/patch_drive-folders-id-edit-file-in-folder.md): Update a file's filename and/or client visibility within a folder. Supports both regular and client-visible files.
  - [Delete file from folder](https://truss-api.readme.io/reference/delete_drive-folders-id-delete-file-from-folder.md): Soft-delete a file from a drive folder by moving it into the folder's deleted files collection.
  - [Restore deleted file from folder](https://truss-api.readme.io/reference/post_drive-folders-id-restore-file-from-folder.md): Restore a deleted file from a drive folder by moving it back into the folder's files collection.
  - [Move file between folders](https://truss-api.readme.io/reference/post_drive-folders-move-file-to-folder.md): Move a file from one folder to another. Files cannot be moved into the root folder.
  - [Move folder to a different parent](https://truss-api.readme.io/reference/post_drive-folders-move-folder.md): Move a folder (and all its sub-folders) under a new parent folder.