---
agentTools:
  projectIndex: https://truss-api.readme.io/llms.txt
---

# Create task comment

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 send_notification_to_assignees is true. Plain newlines in content are converted to line breaks.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "API V1",
    "version": "v1",
    "description": "This is the first version of the Truss API"
  },
  "servers": [
    {
      "url": "https://app2.gettruss.io/api/v1"
    },
    {
      "url": "http://localhost:3000/api/v1"
    },
    {
      "url": "http://127.0.0.1:3000/api/v1"
    },
    {
      "url": "https://app2-staging.gettruss.io/api/v1"
    }
  ],
  "paths": {
    "/projects/{project_id}/tasks/{task_id}/comments": {
      "post": {
        "summary": "Create task comment",
        "tags": [
          "Tasks"
        ],
        "description": "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 send_notification_to_assignees is true. Plain newlines in content are converted to line breaks.\n",
        "parameters": [
          {
            "in": "path",
            "name": "project_id",
            "schema": {
              "type": "integer"
            },
            "required": true,
            "description": "ID of the project"
          },
          {
            "in": "path",
            "name": "task_id",
            "schema": {
              "type": "integer"
            },
            "required": true,
            "description": "ID of the task to comment on"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content": {
                    "type": "string",
                    "description": "The comment body. Supports the same limited HTML as task descriptions."
                  },
                  "send_notification_to_assignees": {
                    "type": "boolean",
                    "default": false,
                    "description": "Also email the assignees active on the task, the same as the \"notify assignees\" checkbox in the app. Ignored when the API user is restricted from sending emails.\n"
                  }
                },
                "required": [
                  "content"
                ]
              },
              "examples": {
                "plain": {
                  "value": {
                    "content": "Payment received - closing this out."
                  }
                },
                "notify_assignees": {
                  "value": {
                    "content": "Please upload the missing W-2 when you get a chance.",
                    "send_notification_to_assignees": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "comment created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Comment"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "missing the projects_write scope, or this user is restricted from commenting"
          },
          "404": {
            "description": "project or task not found"
          },
          "422": {
            "description": "content was blank"
          }
        }
      }
    }
  },
  "webhooks": {
    "project.created": {
      "post": {
        "description": "Triggered when a new project is created",
        "tags": [
          "Webhook Events"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string",
                    "example": "project.created"
                  },
                  "payload": {
                    "type": "object",
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/ProjectExtended"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "project.modified": {
      "post": {
        "description": "Triggered when a project is modified",
        "tags": [
          "Webhook Events"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string",
                    "example": "project.modified"
                  },
                  "payload": {
                    "type": "object",
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/ProjectExtended"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "project.ready": {
      "post": {
        "description": "Triggered when a project is marked as ready",
        "tags": [
          "Webhook Events"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string",
                    "example": "project.ready"
                  },
                  "payload": {
                    "type": "object",
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/ProjectExtended"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "contact.created": {
      "post": {
        "description": "Triggered when a new contact is created",
        "tags": [
          "Webhook Events"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string",
                    "example": "contact.created"
                  },
                  "payload": {
                    "type": "object",
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/ContactExtended"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "contact.modified": {
      "post": {
        "description": "Triggered when a contact is modified",
        "tags": [
          "Webhook Events"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string",
                    "example": "contact.modified"
                  },
                  "payload": {
                    "type": "object",
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/ContactExtended"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "file.created": {
      "post": {
        "description": "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.\n",
        "tags": [
          "Webhook Events"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string",
                    "example": "file.created"
                  },
                  "payload": {
                    "type": "object",
                    "properties": {
                      "file_name": {
                        "type": "string"
                      },
                      "file_url": {
                        "type": "string"
                      },
                      "task_name": {
                        "type": "string"
                      },
                      "task_id": {
                        "type": "integer"
                      },
                      "project_id": {
                        "type": "integer"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "task.created": {
      "post": {
        "description": "Triggered when a new task is created",
        "tags": [
          "Webhook Events"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string",
                    "example": "task.created"
                  },
                  "payload": {
                    "type": "object",
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/TaskExtended"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "task.modified": {
      "post": {
        "description": "Triggered when a task is modified",
        "tags": [
          "Webhook Events"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string",
                    "example": "task.modified"
                  },
                  "payload": {
                    "type": "object",
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/TaskExtended"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "comment.created": {
      "post": {
        "description": "Triggered when a new comment is created",
        "tags": [
          "Webhook Events"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string",
                    "example": "comment.created"
                  },
                  "payload": {
                    "type": "object",
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/Comment"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "status.modified": {
      "post": {
        "description": "Triggered when a project status is modified",
        "tags": [
          "Webhook Events"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string",
                    "example": "status.modified"
                  },
                  "payload": {
                    "type": "object",
                    "properties": {
                      "data": {
                        "allOf": [
                          {
                            "$ref": "#/components/schemas/Project"
                          },
                          {
                            "type": "object",
                            "properties": {
                              "previous_status": {
                                "type": "string",
                                "description": "Name of the status the project moved from, or \"Empty\" if it had none.",
                                "example": "In Progress"
                              },
                              "current_status": {
                                "type": "string",
                                "description": "Name of the status the project moved to, or \"Empty\" if it was cleared.",
                                "example": "Complete"
                              }
                            }
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "esignature.completed": {
      "post": {
        "description": "Triggered when an e-signature request is completed",
        "tags": [
          "Webhook Events"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string",
                    "example": "esignature.completed"
                  },
                  "payload": {
                    "$ref": "#/components/schemas/EsignatureRequestWebhook"
                  }
                }
              }
            }
          }
        }
      }
    },
    "entity.created": {
      "post": {
        "description": "Triggered when a new entity is created.",
        "tags": [
          "Webhook Events"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string",
                    "example": "entity.created"
                  },
                  "payload": {
                    "type": "object",
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/EntityExtended"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "entity.contact_linked": {
      "post": {
        "description": "Triggered when a contact is linked to an entity. Note the payload is the linked contact, not the entity.\n",
        "tags": [
          "Webhook Events"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string",
                    "example": "entity.contact_linked"
                  },
                  "payload": {
                    "type": "object",
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/ContactExtended"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "entity.project_linked": {
      "post": {
        "description": "Triggered when a project is linked to an entity. Note the payload is the linked project, not the entity.\n",
        "tags": [
          "Webhook Events"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string",
                    "example": "entity.project_linked"
                  },
                  "payload": {
                    "type": "object",
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/ProjectExtended"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "stripe.complete": {
      "post": {
        "description": "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 the payment.\n",
        "tags": [
          "Webhook Events"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event_type": {
                    "type": "string",
                    "example": "stripe.complete"
                  },
                  "payload": {
                    "type": "object",
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/TaskExtended"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your API key will be located in Truss top-right menu > Integrations > API Key"
      }
    },
    "schemas": {
      "Project": {
        "type": "object",
        "title": "Project (summary)",
        "description": "Summary representation of a project. Contains scalar attributes plus the owning user and status — no assignees, tasks, tags, or entity. Use GET /projects/{id}, or POST /projects, for the ProjectExtended representation that includes those associations.\n",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "tax_year": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Four-digit year parsed from the project name, or null if the name contains no recent year."
          },
          "idempotency_key": {
            "type": [
              "string",
              "null"
            ]
          },
          "metadata": {
            "type": "object"
          },
          "last_uploaded": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When a file was last uploaded to this project, or null if none has been."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "archived_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the project was archived, or null if it is active."
          },
          "user": {
            "$ref": "#/components/schemas/User"
          },
          "project_status": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ProjectStatus"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "ProjectNote": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "project_id": {
            "type": "integer"
          },
          "task_id": {
            "type": "integer",
            "nullable": true,
            "description": "The task this note is linked to, if any"
          },
          "created_by_id": {
            "type": "integer",
            "nullable": true,
            "description": "ID of the user who wrote the note"
          },
          "last_edited_by_id": {
            "type": "integer",
            "description": "ID of the user who last edited the note"
          },
          "deleted_task_name": {
            "type": "string",
            "nullable": true,
            "description": "Name of the task this note was linked to, after that task was deleted"
          },
          "comment_content": {
            "type": "string",
            "description": "Rich-text body rendered as sanitized HTML"
          },
          "comment_content_as_string": {
            "type": "string",
            "description": "Plain-text version of the body, suitable for non-HTML clients"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ProjectExtended": {
        "type": "object",
        "title": "Project (extended)",
        "description": "Full representation of a project, including assignees, tasks, tags, and the linked entity. Returned by GET /projects/{id}, POST /projects, get_by_idempotency_key, list_by_metadata_key, the tag endpoints, and the project.created / project.modified / project.ready webhooks.\n",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "tax_year": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Four-digit year parsed from the project name, or null if the name contains no recent year."
          },
          "idempotency_key": {
            "type": "string"
          },
          "metadata": {
            "type": "object"
          },
          "due_date": {
            "type": "string",
            "format": "date-time"
          },
          "reminder_schedule_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Name of the project's reminder schedule, or null if none is set."
          },
          "complexity_level": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "0",
              "1",
              "2",
              "3",
              null
            ],
            "description": "Return complexity from the project's organizer upload: \"0\" basic OCR, \"1\" low, \"2\" medium, \"3\" high. Null if the project has no organizer upload or its complexity hasn't been calculated.\n"
          },
          "assignees": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AssigneeWithContact"
            }
          },
          "tasks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Task"
            }
          },
          "user": {
            "$ref": "#/components/schemas/User"
          },
          "tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tag"
            }
          },
          "entity": {
            "description": "Summary of the project's linked entity. Null if no entity is linked.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/Entity"
              },
              {
                "type": "null"
              }
            ]
          },
          "project_status": {
            "$ref": "#/components/schemas/ProjectStatus"
          }
        }
      },
      "ProjectStatus": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "position": {
            "type": "integer"
          }
        }
      },
      "ContactExtended": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "nick_name": {
            "type": "string"
          },
          "company": {
            "type": "string"
          },
          "job_title": {
            "type": "string"
          },
          "client_id_number": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tag"
            }
          },
          "contact_emails": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactEmail"
            }
          },
          "contact_phones": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactPhone"
            }
          },
          "contact_addresses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactAddress"
            }
          },
          "entity_origins": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Entity"
            }
          }
        }
      },
      "EffectiveEmail": {
        "type": [
          "object",
          "null"
        ],
        "description": "The email to use for this contact in the containing entity or project context. Falls back to the contact's global primary email.",
        "properties": {
          "id": {
            "type": "integer"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "overridden": {
            "type": "boolean",
            "description": "Whether an entity-level override selected this email."
          },
          "source": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "manual",
              "cch_axcess",
              null
            ],
            "description": "Source of the entity-level override, or null when using the global primary email."
          }
        }
      },
      "ContactSummary": {
        "type": "object",
        "title": "Contact (summary)",
        "description": "Summary representation of a contact. Scalar attributes only — no emails, phones, addresses, tags, or linked entities. Use GET /contacts/{contact_id} for the ContactExtended representation that includes those.\n",
        "properties": {
          "id": {
            "type": "integer"
          },
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "nick_name": {
            "type": "string"
          },
          "company": {
            "type": "string"
          },
          "job_title": {
            "type": "string"
          },
          "client_id_number": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "EntityContactSummary": {
        "description": "Contact summary with the email resolved in the containing entity or project context.\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/ContactSummary"
          },
          {
            "type": "object",
            "properties": {
              "effective_email": {
                "$ref": "#/components/schemas/EffectiveEmail"
              }
            }
          }
        ]
      },
      "EntityContactExtended": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ContactExtended"
          },
          {
            "type": "object",
            "properties": {
              "effective_email": {
                "$ref": "#/components/schemas/EffectiveEmail"
              }
            }
          }
        ]
      },
      "ContactEmail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "email": {
            "type": "string"
          },
          "primary": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ContactPhone": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "phone_number": {
            "type": "string"
          },
          "country_code": {
            "type": "string"
          },
          "country_phone_code": {
            "type": "string"
          },
          "phone_type": {
            "type": "string",
            "enum": [
              "mobile",
              "home",
              "work",
              "fax",
              "office",
              "other"
            ]
          },
          "primary": {
            "type": "boolean"
          },
          "metadata": {
            "type": "object"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ContactAddress": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "street_address": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "zip": {
            "type": "string"
          },
          "primary": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Entity": {
        "type": "object",
        "title": "Entity (summary)",
        "description": "Summary representation of an entity. Contains scalar attributes only — no contacts, projects, or tags. Use GET /entities/{id}, or GET /entities?extended_view=true, for the EntityExtended representation that includes those associations.\n",
        "properties": {
          "id": {
            "type": "integer"
          },
          "client_id_number": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "metadata": {
            "type": "object",
            "description": "Additional metadata for the entity, contents may vary"
          },
          "ein": {
            "type": "string",
            "description": "Employer Identification Number (EIN)"
          },
          "other_ids": {
            "type": "object",
            "description": "Other identifying information, contents may vary"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "EntityWebhook": {
        "type": [
          "object",
          "null"
        ],
        "description": "Project's linked entity. Null if no entity is linked.",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "client_id_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "External client ID from entity.client_id_number."
          }
        }
      },
      "EsignatureSignerWebhook": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          },
          "recipient_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "recipient_id": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      },
      "EsignatureRequestWebhook": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "project_id": {
                "type": "integer"
              },
              "user_id": {
                "type": "integer"
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time"
              },
              "esignature_method": {
                "type": "string",
                "enum": [
                  "electronic",
                  "wet"
                ],
                "example": "electronic"
              },
              "esignature_type": {
                "type": "string",
                "description": "Type of e-signature document, such as 8879 or 7216.",
                "example": "8879"
              },
              "completed_document_url": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri"
              },
              "tax_year": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Four-digit year parsed from the linked project's name, or null."
              },
              "tax_return_type": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Return type from the linked project's assembly upload, or null."
              },
              "entity": {
                "$ref": "#/components/schemas/EntityWebhook"
              },
              "signers": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/EsignatureSignerWebhook"
                }
              }
            }
          }
        }
      },
      "Task": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string",
            "description": "Name of the task"
          },
          "description": {
            "type": "string",
            "description": "Description of the task - supports limited subset of HTML &lt;b&gt;, &lt;ul&gt;, &lt;li&gt;, &lt;br&gt;, and &lt;a&gt;."
          },
          "status": {
            "type": "string",
            "enum": [
              "to_do",
              "pending_review",
              "approved"
            ],
            "description": "Status of the task"
          },
          "due_date": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the task is due (ISO 8601). Null when no due date is set."
          }
        }
      },
      "AttachedFile": {
        "type": "object",
        "properties": {
          "attachment_id": {
            "type": "integer",
            "description": "Identifier used to retrieve this file's text extraction."
          },
          "blob_id": {
            "type": "integer"
          },
          "filename": {
            "type": "string"
          },
          "content_type": {
            "type": "string"
          },
          "byte_size": {
            "type": "integer",
            "format": "int64"
          },
          "download_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Temporary download URL valid for 1 hour."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TaskExtended": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string",
            "description": "Name of the task"
          },
          "description": {
            "type": "string",
            "description": "Description of the task - supports limited subset of HTML &lt;b&gt;, &lt;ul&gt;, &lt;li&gt;, &lt;br&gt;, and &lt;a&gt;."
          },
          "description_as_string": {
            "type": "string",
            "description": "Plain text description of the task"
          },
          "status": {
            "type": "string",
            "enum": [
              "to_do",
              "pending_review",
              "approved"
            ],
            "description": "Status of the task"
          },
          "due_date": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the task is due (ISO 8601). Null when no due date is set."
          },
          "task_type": {
            "type": "string",
            "nullable": true,
            "description": "The task's type - see Task types. Null for a plain task."
          },
          "amount_due": {
            "type": "string",
            "nullable": true,
            "description": "Invoice tasks only. Amount the client owes, in dollars."
          },
          "verification_types": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string",
              "enum": [
                "contact",
                "bank_accounts"
              ]
            },
            "description": "contact_info_verification tasks only. What the client is asked to confirm."
          },
          "payment_status": {
            "type": "string",
            "nullable": true,
            "enum": [
              "unpaid",
              "payment_pending",
              "paid"
            ],
            "description": "Invoice tasks only. \"payment_pending\" is an ACH payment Stripe has accepted but not yet settled; it can still fail and revert the task to unpaid.\n"
          },
          "project_notes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProjectNote"
            },
            "description": "The task's internal notes, newest first"
          },
          "document_category": {
            "type": "object",
            "nullable": true,
            "description": "The document type this task is filed under - see GET /document_categories. Null when it has none. Set it by passing document_category_id when creating or updating the task.\n",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string",
                "description": "Machine name, e.g. \"w_2\""
              },
              "display_name": {
                "type": "string",
                "description": "Human label, e.g. \"W-2\""
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "assignees": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Assignee"
            }
          },
          "comments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Comment"
            }
          },
          "project": {
            "$ref": "#/components/schemas/Project"
          },
          "attached_files": {
            "type": "array",
            "description": "Task-level and assignee task file attachments. On GET task, the uploaded_by query parameter narrows this to firm-uploaded (task-level) or client-uploaded (assignee task) files.\n",
            "items": {
              "$ref": "#/components/schemas/AttachedFile"
            }
          }
        }
      },
      "EntityExtended": {
        "type": "object",
        "title": "Entity (extended)",
        "description": "Full representation of an entity, including tags, contacts, and projects. Returned by GET /entities/{id}, GET /entities?extended_view=true, and the link_contact / link_project endpoints.\n",
        "properties": {
          "id": {
            "type": "integer"
          },
          "client_id_number": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "metadata": {
            "type": "object",
            "description": "Additional metadata for the entity, contents may vary"
          },
          "ein": {
            "type": "string",
            "description": "Employer Identification Number (EIN)"
          },
          "other_ids": {
            "type": "object",
            "description": "Other identifying information, contents may vary"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tag"
            },
            "description": "Tags applied to this entity"
          },
          "primary_contact": {
            "description": "Primary contact for this entity. Null if no primary contact is linked.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/EntityContactExtended"
              },
              {
                "type": "null"
              }
            ]
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EntityContactExtended"
            },
            "description": "List of contacts associated with this entity"
          },
          "projects": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProjectExtended"
            },
            "description": "List of projects associated with this entity"
          }
        }
      },
      "Comment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "commentable_type": {
            "type": "string",
            "description": "Type of the commentable (e.g. \"Task\")"
          },
          "commentable_id": {
            "type": "integer",
            "description": "ID of the commentable (e.g. \"Task\")"
          },
          "commenter_type": {
            "type": "string",
            "description": "Type of the commenter (e.g. \"User\" or \"Assignee\")"
          },
          "commenter_id": {
            "type": "integer",
            "description": "ID of the commenter (e.g. \"User\" or \"Assignee\")"
          },
          "content": {
            "type": "string",
            "description": "HTML content of the comment"
          },
          "content_as_string": {
            "type": "string",
            "description": "Plain text content of the comment"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Assignee": {
        "type": "object",
        "description": "Summary representation of an assignee.",
        "properties": {
          "id": {
            "type": "integer"
          },
          "display_name": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "description": "Contact's global primary email, or null if the contact has none."
          }
        }
      },
      "AssigneeWithContact": {
        "description": "Assignee including the linked contact, resolved in the containing project's entity context. Prefer contact.effective_email over the top-level email — the latter is always the contact's global primary address and ignores any entity-level override.\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/Assignee"
          },
          {
            "type": "object",
            "properties": {
              "magic_link": {
                "type": "string",
                "description": "Assignee's magic upload URL."
              },
              "contact": {
                "$ref": "#/components/schemas/EntityContactSummary"
              }
            }
          }
        ]
      },
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "email": {
            "type": "string"
          },
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "idempotency_key": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Tag": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Tasks",
      "description": "Manage tasks within a project.\n\n### Task types\n\nA task is a plain checklist item unless you pass `task_type` when creating it.\nEach native type adds its own fields and its own client-side behavior.\n\n| `task_type` | Creates | Extra fields | Requires |\n| --- | --- | --- | --- |\n| `null` | A plain task | — | — |\n| `invoice` | A Request Payment task | `amount_due` | A connected Stripe account |\n| `contact_info_verification` | A Contact Information Verification task, named after what it verifies | `verification_types`; omit `name` and `description` | — |\n| `ez_sign` | An engagement letter from a template or custom HTML, filed under engagement letters | Either `ez_sign_template_id` (omit `name`) or `body` plus `name`; optional `all_must_sign`; omit `document_category_id` | At least one client assigned to the project |\n\nSending a field that belongs to a different type (for example `amount_due` on a\n`contact_info_verification` task) is an error, not ignored.\n\nNew tasks are assigned to the project's default clients. When the project has no default\nclient, they go to every active client on it, so an engagement letter always has someone\nwho can sign it.\n\nAn engagement letter template with advanced merge fields is sent with those placeholders\nstill in it; fill them afterwards from the template's advanced merge field CSV, as in Truss.\n\nTo create a letter without a template, send `task_type: ez_sign`, `name`, and an HTML `body`.\nStandard merge fields are expanded; provide final custom values in the body because template-based\nadvanced merge CSVs do not apply to custom letters. Hosted images, including a logo at the top,\nare supported with `<img src=\"https://example.com/logo.png\" alt=\"Logo\" width=\"180\">`.\nImages are downloaded from public HTTPS URLs and embedded in the saved letter, so subsequent\nsigning and PDF rendering do not fetch the original URL. Base64 image data URIs are also accepted.\nSupported inputs: static PNG, JPEG, GIF and WebP; at most 10 images, 2 MB per image and 5 MB total across the entire request (including bulk creation).\nImages must be at most 4096 pixels per side and 4 megapixels and are normalized to static PNG before storage.\nPrivate-network destinations, unsafe redirects, unsupported formats and oversized images return 422.\nA failed image download rolls back creation, including the whole batch for bulk requests.\nUnsafe HTML and ActionText attachment tags are stripped; arbitrary scripts and page-level CSS are not supported.\n"
    },
    {
      "name": "Webhook Events",
      "description": "Webhook events that you can receive from Truss."
    }
  ],
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 99,
      "1": 173,
      "2": 53,
      "3": 51,
      "4": 170,
      "5": 198,
      "6": 91,
      "7": 0,
      "8": 56,
      "9": 42,
      "10": 172,
      "11": 14
    }
  }
}
```