> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Comments

> Learn how to associate comments with payables.

## Overview

[Payables](/finops/guides/accounts-payable/payables/index) stored in Tesouro can have comments associated with them. Tesouro API Partners can use comments to store additional information about payables.

[Webhooks](/finops/guides/getting-started/webhooks/index) are sent every time a comment is created, updated, or deleted.

## Roles and permissions

To use the `/comments*` endpoints with an [organization user token](/finops/guides/organizations/users#get-organization-user-token), this organization user must have a [role](/finops/guides/organizations/users#create-role) with the `comment` permission.

If using a [partner-level token](/finops/guides/authentication/client-credentials), no special permissions are needed.

## Create a comment

To create a comment, call [`POST /comments`](/finops/reference/openapi/comments/post-comments) with the request body containing the comment text and the ID of the payable object to which the comment is related. The `object_type` field must be set to `"payable"`. If the comment is a reply to another user, you can include the `reply_to_entity_user_id` field:

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/comments' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
        "text": "Comment about a payable.",
        "reply_to_entity_user_id": "6e8b3d61-edc6-41d5-94ff-e3980606dc0f",
        "object_type": "payable",
        "object_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }'
```

The successful response contains information about the newly created comment and the object to which the comment is related:

```json lines theme={null}
{
  "id": "d95eb59f-2781-4c58-b763-4526b3b27b0d",
  "created_at": "2023-09-06T07:10:53.879Z",
  "updated_at": "2023-09-06T07:10:53.879Z",
  "created_by_entity_user_id": "9fabf3e8-76bd-400e-85cc-776d42e71c07",
  "entity_id": "ba2ee5e3-b29d-4594-942c-d962ae9765ed",
  "object_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "object_type": "payable",
  "reply_to_entity_user_id": "6e8b3d61-edc6-41d5-94ff-e3980606dc0f",
  "status": "active",
  "text": "Comment about a payable."
}
```

## List all comments

To get a list of all the comments related to a specific object, call [`GET /comments`](/finops/reference/openapi/comments/get-comments) passing the `object_type` and the `object_id` of the object to which the comments are related as query parameters:

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/comments?object_type=payable&object_id=9d2b4c8f-2087-4738-ba91-7359683c49a4&order=asc&limit=100' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
```

The successful response contains information about all the comments associated with the supplied object:

```json expandable lines theme={null}
{
  "data": [
    {
      "id": "d95eb59f-2781-4c58-b763-4526b3b27b0d",
      "created_at": "2023-09-06T07:10:53.879Z",
      "updated_at": "2023-09-06T07:10:53.879Z",
      "created_by_entity_user_id": "9fabf3e8-76bd-400e-85cc-776d42e71c07",
      "entity_id": "ba2ee5e3-b29d-4594-942c-d962ae9765ed",
      "object_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "object_type": "payable",
      "reply_to_entity_user_id": "6e8b3d61-edc6-41d5-94ff-e3980606dc0f",
      "status": "active",
      "text": "Comment about a payable."
    }
  ],
  "prev_pagination_token": null,
  "next_pagination_token": null
}
```

## Retrieve a comment

To get information about a specific comment associated with a specific object, call [`GET /comments/{comment_id}`](/finops/reference/openapi/comments/get-comments-id).

## Edit a comment

To edit an existing comment, call [`PATCH /comments/{comment_id}`](/finops/reference/openapi/comments/patch-comments-id). Only the creator of the comment is allowed to change it.

```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/comments/d95eb59f-2781-4c58-b763-4526b3b27b0d' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "text": "Updated comment about a payable.",
       "reply_to_entity_user_id": "9fabf3e8-76bd-400e-85cc-776d42e71c07"
     }'
```

## Delete a comment

To delete an existing comment, call [`DELETE /comments/{comment_id}`](/finops/reference/openapi/comments/delete-comments-id).