Skip to main content

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.

Organizations represent the customers of Tesouro partners. 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 /identity/v1/organizations: 
curl -X POST 'https://api.sandbox.tesouro.com/identity/v1/organizations' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "displayName": "Acme Inc.",
       "legalName": "Acme Incorporated",
       "shortName": "acme",
       "mccsAllowed": ["5411"],
       "type": "EMBEDDED",
       "email": "sales@example.com",
       "phoneNumber": "+12125551234",
       "address": {
         "address1": "5th Avenue",
         "city": "New York",
         "stateOrProvince": "NY",
         "postalCode": "10001",
         "country": "US"
       }
     }'
Explanation of the request fields:
  • displayName — The name shown in the UI.
  • legalName — The official registered legal name of the organization.
  • shortName — A short alphanumeric slug identifier (letters, digits, and hyphens only).
  • mccsAllowed — List of merchant category codes (MCCs) permitted for this organization.
  • type — The organizational type. Possible values: EMBEDDED, TRANSACTOR, VERTICAL_SOFTWARE_PROVIDER. The response returns this as types (an array).
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",
  "displayName": "Acme Inc.",
  "legalName": "Acme Incorporated",
  "shortName": "acme",
  "types": ["EMBEDDED"],
  "isEnabled": true,
  "email": "sales@example.com",
  "phoneNumber": "+12125551234",
  "mccsAllowed": ["5411"],
  "address": {
    "address1": "5th Avenue",
    "city": "New York",
    "stateOrProvince": "NY",
    "postalCode": "10001",
    "country": "US"
  }
}
Notes:
  • After an organization is created, you must also add its bank accounts.
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 /identity/v1/organizations/{organizationId}/logo with a multipart/form-data body containing the image in the file field: 
curl -X PUT 'https://api.sandbox.tesouro.com/identity/v1/organizations/{organizationId}/logo' \
     -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",
  "createdAt": "2022-09-08T00:20:04.961397",
  "fileType": "organization-logo",
  "name": "upload",
  "region": "eu-central-1",
  "md5": "7537d5833741469a03162ce7a73bd4e8",
  "mimetype": "image/png",
  "url": "https://tesouro-file-saver-organization-logo-eu-central-1.s3.com/logo.png",
  "size": 1691,
  "previews": [],
  "pages": []
}
The logo file information will also be returned in the logo response field when you retrieve organization information with GET /identity/v1/organizations/{organizationId} 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 /identity/v1/organizations/{organizationId}/logo.

​
List all organizations

To get information about all the organizations managed by the partner, call GET /identity/v1/organizations. This endpoint supports pagination and filtering via query parameters.

​
Get a single organization

To get information about a specific organization, call GET /identity/v1/organizations/{organizationId}: 
curl 'https://api.sandbox.tesouro.com/identity/v1/organizations/c5f499a7-19ea-4057-9191-112da7effa31' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Requests authenticated with an organization user token can access any organization visible in the caller’s hierarchy. The token must have the org:read:all scope.

​
Update organization information

To update the details of an existing organization, call PATCH /identity/v1/organizations/{organizationId}: 
curl -X PATCH 'https://api.sandbox.tesouro.com/identity/v1/organizations/c5f499a7-19ea-4057-9191-112da7effa31' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{ "displayName": "Acme Corp" }'
Requests authenticated with an organization user token can update any organization visible in the caller’s hierarchy. The token must have the org:write scope.

​
Disable and enable organizations

Organizations have an isEnabled field that is true when active and false when disabled. Partners can disable organizations to control access. New organizations are enabled by default.
  • To disable an organization, call POST /identity/v1/organizations/{organizationId}/disable.
  • To enable an organization, call POST /identity/v1/organizations/{organizationId}/enable.
Both app tokens and organization user tokens can disable and enable organizations. The token must have the org:write:all scope. Only EMBEDDED and VERTICAL_SOFTWARE_PROVIDER organizations can be disabled or enabled — TRANSACTOR organizations cannot.

​
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.