> ## 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

> Learn how Tesouro API Partners can manage their customers.

**Organizations** represent the customers of Tesouro [partners](/finops/support/glossary#partner).

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.

<Note>
  Learn more about [organizations, organization users, and the Tesouro account
  structure](/finops/guides).
</Note>

## Create an organization representing your customer

To create a new organization, call `POST /identity/v1/organizations`:

```sh expandable lines theme={null}
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)](https://en.wikipedia.org/wiki/Merchant_category_code) 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:

```json lines theme={null}
{
  "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](/finops/guides/organizations/bank-accounts).

### Upload organization logo

You can provide the organization logo for use in the PDF documents generated by the organization (such as Accounts Receivable [invoices](/finops/guides/accounts-receivable/invoices/index) and [credit notes](/finops/guides/accounts-receivable/credit-notes)). The logo will also appear on the [payment page](/finops/guides/payments/payment-links) 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`](/finops/reference/openapi/identity/uploads-a-logo-for-an-organization) with a `multipart/form-data` body containing the image in the `file` field:

```sh lines theme={null}
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:

```json lines theme={null}
{
  "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}`](/finops/reference/openapi/identity/gets-details-for-a-specific-organization) 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`](/finops/reference/openapi/identity/deletes-a-logo-for-an-organization).

## 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}`:

```sh lines theme={null}
curl 'https://api.sandbox.tesouro.com/identity/v1/organizations/c5f499a7-19ea-4057-9191-112da7effa31' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

<Info>
  Requests authenticated with an [organization user token](/finops/guides/organizations/users#get-organization-user-token) can
  access any organization visible in the caller's hierarchy. The token must have the `org:read:all` scope.
</Info>

## Update organization information

To update the details of an existing organization, call `PATCH /identity/v1/organizations/{organizationId}`:

```sh lines theme={null}
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" }'
```

<Info>
  Requests authenticated with an [organization user token](/finops/guides/organizations/users#get-organization-user-token) can
  update any organization visible in the caller's hierarchy. The token must have the `org:write` scope.
</Info>

## 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`.

<Info>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.</Info>

## Access the current user's organization

If you use [organization user tokens](/finops/guides/organizations/users#get-organization-user-token) to authenticate Tesouro API requests, the following endpoints let you access the current user's organization without providing its ID:

* [`GET /entity-users/my-organization`](/finops/reference/openapi/entities/get-entity-users-my-entity) - get organization information.
* [`PATCH /entity-users/my-organization`](/finops/reference/openapi/entities/patch-entity-users-my-entity) - update organization information.

To use these endpoints, the organization user in question must have a [role](/finops/guides/organizations/users#create-role) with the `entity.read` and `entity.update` permissions, respectively.