Skip to main content
Organizations represent the customers of Tesouro partners and can be either organizations or individuals (persons). An organization registers its operations and stores financial documents (such as payables or bank transactions) via the partner’s applications. Those financial documents are in turn stored and processed by Tesouro.
Learn more about organizations, organization users, and the Tesouro account structure.

​
Create an organization representing your customer

To create a new organization, call POST /entities. The organization can be either an organization or an individual: 
curl -X POST 'https://api.sandbox.tesouro.com/v1/entities' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer YOUR_APP_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "type": "organization",
       "email": "sales@example.com",
       "phone": "+12125551234",
       "website": "https://example.com",
       "tax_id": "123456789",
       "address": {
         "country": "US",
         "city": "New York",
         "state": "NY",
         "postal_code": "10001",
         "line1": "5th Avenue"
       },
       "organization": {
         "legal_name": "Acme Inc.",
         "business_structure": "private_corporation"
       }
     }'
Explanation of the request fields:
  • For organization-type organizations:
    • business_structure - Required for organizations that accept payments. Possible values by region:
      • US organizations: multi_member_llc, private_corporation, private_partnership, public_corporation, public_partnership, single_member_llc, sole_proprietorship, unincorporated_association
  • For individual-type organizations:
    • ssn_last_4 - Required for US individuals to accept payments. The last four digits of the person’s Social Security Number (SSN).
A successful response returns the unique ID assigned to the created organization, along with the rest of the organization information: 
{
  "id": "aea39c7e-630f-4664-a449-de899ebd4912",
  "status": "active",
  "created_at": "2022-04-21T14:23:01.691982+00:00",
  "updated_at": "2022-04-21T14:23:01.691994+00:00",
  ...
}
Notes:
  • An organization’s country (address.country) cannot be changed after the organization has been created.
  • After an organization is created, you must also add its bank accounts.
  • An organization can optionally add their tax ID - this will then be displayed on invoices created by that organization.
You can provide the organization logo for use in the PDF documents generated by the organization (such as Accounts Receivable invoices and credit notes). The logo will also appear on the payment page if the organization uses Tesouro payment rails. The logo image can be PNG or JPG up to 10 MB in size. To upload the logo for an organization, call PUT /entities/logo with a multipart/form-data body containing the image in the file field: 
curl -X PUT 'https://api.sandbox.tesouro.com/v1/entities/{entity_id}/logo' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: multipart/form-data' \
     -F 'file=@logo.png;type=image/png'
The specified logo is stored on Tesouro servers, and the successful response returns the logo file information: 
{
  "id": "c5f499a7-19ea-4057-9191-112da7effa31",
  "created_at": "2022-09-08T00:20:04.961397",
  "file_type": "entity-logo",
  "name": "upload",
  "region": "eu-central-1",
  "md5": "7537d5833741469a03162ce7a73bd4e8",
  "mimetype": "image/png",
  "url": "https://tesouro-file-saver-entity-logo-eu-central-1.s3.com/logo.png",
  "size": 1691,
  "previews": [],
  "pages": []
}
The logo file information will also returned in the logo response field when you retrieve organization information with GET /entities/{entity_id} or similar requests. You can update the logo at any time later by uploading a new logo. You can also delete the logo by calling DELETE /entities//logo.

​
List all organizations

To get information about all the organizations managed by the partner, call GET /entities. This endpoint supports the standard pagination, sorting, and filtering parameters.

​
Get a single organization

To get information about a specific organization, call GET /entities/{entity_id}: 
curl 'https://api.sandbox.tesouro.com/v1/entities/c5f499a7-19ea-4057-9191-112da7effa31' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
Requests authenticated with an organization user token can access only that user’s organization. The user must have a role with the entity.read permission.

​
Update organization information

To update the details of an existing organization, call PATCH /entities/{entity_id}: 
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/entities/c5f499a7-19ea-4057-9191-112da7effa31' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{ "email": "info@example.com" }'
You can update all fields except address.country. The country of existing organizations cannot be changed for regulatory reasons. The only way to change an organization’s country is to create a new organization.
Requests authenticated with an organization user token can update only that user’s organization. The user must have a role with the entity.update permission.

​
Deactivate and reactivate organizations

Organizations have a status field that can be active or inactive. Partners can deactivate organizations to control access. New organizations are created as active by default.
Only app tokens can activate/deactivate organizations.

​
Access the current user’s organization

If you use organization user tokens to authenticate Tesouro API requests, the following endpoints let you access the current user’s organization without providing its ID: To use these endpoints, the organization user in question must have a role with the entity.read and entity.update permissions, respectively.