Organization settings

Overview

Tesouro’s organization settings are a way to customize the behavior of certain functionality for your organizations. The organization settings API provides functionality for managing and configuring settings specific to organizations within the Tesouro platform. They allow you to personalize and customize certain aspects of your organizations’ integration. Some of these customizations include enabling payment and overdue reminders, customizing document number formatting, setting default currencies and currency exchange rates, and other organization-specific configurations.

Roles and permissions

To get or update organization settings using an organization user token, this organization user must have a role with the read and update permissions for the entity resource. If using a partner-level token, no special permissions are needed.

Get organization settings

To retrieve settings for an organization, send a GET request to the /organizations/{organization_id}/settings endpoint:

curl -X GET 'https://api.sandbox.tesouro.com/identity/v1/organizations/5b031d0c...44df31ebf0db/settings' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer ACCESS_TOKEN'

A successful request returns the current settings for the organization provided.

{
  ...
  "currency": {},
  "defaultBankAccount": {
    "type": "BANK_DETAILS",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "documentIds": {
    "includeDate": false,
    "prefix": "string",
    "separator": "-",
    "minDigits": 5,
    "documentTypePrefix": {
      "quote": "Q",
      "invoice": "INV",
      "creditNote": "CN",
      "purchaseOrder": "PO"
    }
  },
  "documentRendering": {
    "displayOrganizationBankAccount": true,
    "invoice": {
      "displayOrganizationBankAccount": true
    },
    "quote": {
      "displayOrganizationBankAccount": true,
      "displaySignature": true
    },
    "creditNote": {
      "displayOrganizationBankAccount": true
    }
  },
  ...
  "language": "en",
  "paymentPriority": "working_capital",
  ...
  "receivableEditFlow": "compliant",
  "reminder": {
    "enabled": true
  },
  "quoteSignatureRequired": false,
  ...
}

Update organization settings

To update the details of an organization, make a PATCH request to the /organizations/{organization_id}/settings endpoint. The following snippet shows an example of the payload for the PATCH /organizations/{organization_id}/settings endpoint that enables payment reminders for organization invoices and updates the document ID format for invoices and quotes.

curl -X PATCH 'https://api.sandbox.tesouro.com/identity/v1/organizations/5b031d0c...44df31ebf0db/settings' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "reminder": {
         "enabled": true
       },
       "quoteSignatureRequired": true,
       "language": "fr",
       "documentIds": {
         "includeDate": true,
         "minDigits": 4,
         "documentTypePrefix": {
           "invoice": "IN"
         }
       }
     }'

The successful request returns the complete organization settings object with the updated fields. The language field on the organization settings object determines the language of the organization’s PDFs.

Document rendering

documentRendering controls what appears on the PDF documents an organization generates. displayOrganizationBankAccount controls the payment block that carries the organization’s bank account details. It exists at the top level and once per document type, and both must be true for the block to render. Each defaults to true.

curl -X PATCH 'https://api.sandbox.tesouro.com/identity/v1/organizations/5b031d0c...44df31ebf0db/settings' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "documentRendering": {
         "invoice": {
           "displayOrganizationBankAccount": false
         }
       }
     }'

The per-document-type flag is read from the organization settings, so setting it on an individual document has no effect. Paid invoices never show the payment block, whatever the setting. To learn which fields the block contains, see What appears on the invoice PDF.

Default bank account

defaultBankAccount holds the account an organization is paid into by default, as a type and id pair. See Set a default bank account.

Getting started

Embedded components

Authentication

Roles & permissions

Manage organizations

Common objects

Accounts payable

Accounts receivable

Expense management

Payments

Advanced

Accounting integrations

Organization settings

Overview

Roles and permissions

Get organization settings

Update organization settings

Document rendering

Default bank account

​Overview

​Roles and permissions

​Get organization settings

​Update organization settings

​Document rendering

​Default bank account

Overview

Roles and permissions

Get organization settings

Update organization settings

Document rendering

Default bank account