> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.monite.com/v2023-09-01/entities/index/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server.

# Entities

## Overview

**Entities** represent the customers of Monite API [partners](../references/glossary#partner) and can be either organizations or individuals (persons).

An entity 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 Monite.

> **Note**
>
> Learn more about [entities, entity users, and the Monite account structure](../intro/account-structure).

## Create an entity representing your customer

To create a new entity, call [`POST /entities`](/v2023-09-01/api/entities/post-entities). The entity can be either an *organization* or an *individual*:

#### Organization

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/entities' \
     -H 'X-Monite-Version: 2023-09-01' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "type": "organization",
       "email": "sales@example.com",
       "phone": "+4903023125000",
       "website": "https://example.com",
       "tax_id": "DE123456789",
       "address": {
         "country": "DE",
         "city": "Berlin",
         "state": "BE",
         "postal_code": "10115",
         "line1": "Flughafenstrasse 52"
       },
       "organization": {
         "legal_name": "Acme Inc.",
         "representative_provided": true,
         "directors_provided": true,
         "executives_provided": true,
         "owners_provided": true,
         "legal_entity_id": "506700GE1G29325QX363",
         "business_structure": "private_corporation"
       }
     }'
```

#### Individual

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/entities' \
     -H 'X-Monite-Version: 2023-09-01' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "type": "individual",
       "email": "bob@example.com",
       "phone": "+4903023125000",
       "website": "https://example.com",
       "tax_id": "DE123456789",
       "address": {
         "country": "DE",
         "city": "Berlin",
         "state": "BE",
         "postal_code": "10115",
         "line1": "Flughafenstrasse 52"
       },
       "individual": {
         "title": "Mr.",
         "first_name": "Bob",
         "last_name": "Jones",
         "date_of_birth": "1993-03-14",
         "id_number": "NL000099998B57",
         "ssn_last_4": "0001"
       }
     }'
```

Explanation of the request fields:

* For `organization` entities:
  * `business_structure` - Required for EU and US entities to accept payments. Possible values:
    * EU: `incorporated_partnership`, `private_corporation`, `public_corporation`, `unincorporated_partnership`
    * US organizations: `multi_member_llc`, `private_corporation`, `private_partnership`, `public_corporation`, `public_partnership`, `single_member_llc`, `sole_proprietorship`, `unincorporated_association`

* For `individual` entities:
  * `id_number` - Required for Dutch individuals to accept payments. The person's Burgerservicenummer (BSN) or Dutch Citizen Service Number.
  * `ssn_last_4` Required for US individual to accept payments. The last four digits of the person's Social Security Number (SSN).

* `tax_id` - the taxpayer registration number. If the entity will use Monite's [Account Receivable API](../accounts-receivable/index), either `tax_id` or [VAT ID](./vat-ids), or both must be specified.
  * In France, the `tax_id` is the [SIREN/SIRET](https://entreprendre.service-public.fr/vosdroits/F32135?lang=en) number.
  * In the Netherlands, the `tax_id` is the [Dutch Business Register number](https://business.gov.nl/starting-your-business/registering-your-business/lei-rsin-vat-and-kvk-number-which-is-which/) (KVK).
  * A Liberian entity's tax number must be specified as its [VAT ID](./vat-ids) rather than the `tax_id`.

A successful response returns the unique ID assigned to the created entity, along with the rest of the entity information:

```json
{
  "id": "aea39c7e-630f-4664-a449-de899ebd4912",
  "created_at": "2022-04-21T14:23:01.691982+00:00",
  "updated_at": "2022-04-21T14:23:01.691994+00:00",
  ...
}
```

Notes:

* Spanish entities registered in the Canary Islands must use the country code `IC` instead of `ES` in their address.

  Spanish entities registered in Ceuta and Melilla must use the country code `EA` instead of `ES`.

* Entities can use Monite payment rails to accept and send payments. For this, the entity [must be onboarded](../payments/onboarding/index). Providing as much information as possible during the entity's registration process will make the onboarding process smoother.

* After an entity is created, you must also add its [bank accounts](./bank-accounts).

* Entities of the `organization` type must also add information of the legally responsible individuals associated with the organization. See the [Persons page](../payments/onboarding/via-api/persons) for details.

## Upload entity logo \[#logo]

You can provide the entity logo for use in the PDF documents generated by the entity (such as Accounts Receivable [invoices](../accounts-receivable/invoices/index) and [credit notes](../accounts-receivable/credit-notes)). The logo will also appear on the [payment page](../payments/payment-links) if the entity uses Monite payment rails.

The logo image can be PNG or JPG up to 10 MB in size.

To upload the logo for an entity, call [`PUT /entities/{entity_id}/logo`](/v2023-09-01/api/entities/put-entities-id-logo) with a `multipart/form-data` body containing the image in the `file` field:

```sh
curl -X PUT 'https://api.sandbox.monite.com/v1/entities/{entity_id}/logo' \
     -H 'X-Monite-Version: 2023-09-01' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: multipart/form-data' \
     -F 'file=@logo.png;type=image/png'
```

The specified logo is stored on Monite servers, and the successful response returns the logo file information:

```json
{
  "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://monite-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 entity information with [`GET /entities/{entity_id}`](/v2023-09-01/api/entities/get-entities-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 sending a `DELETE` request to the `/entities/{entity_id}/logo`.

## List all entities

To get information about all the entities managed by the partner, call [`GET /entities`](/v2023-09-01/api/entities/get-entities). This endpoint supports the standard [pagination, sorting, and filtering parameters](/v2023-09-01/api/concepts/pagination-sorting-filtering).

## Get a single entity

To get information about a specific entity, call [`GET /entities/{entity_id}`](../../api/entities/get-entities-id):

```sh
curl 'https://api.sandbox.monite.com/v1/entities/c5f499a7-19ea-4057-9191-112da7effa31' \
  -H 'X-Monite-Version: 2023-09-01' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

> **Info**
>
> Requests authenticated with an [entity user token](./users#get-entity-user-token) can access only that user's entity.
> The user must have a role with the `entity.read` permission.

## Update entity information \[#update]

To update the details of an existing entity, call [`PATCH /entities/{entity_id}`](../../api/entities/patch-entities-id):

```sh
curl -X PATCH 'https://api.sandbox.monite.com/v1/entities/c5f499a7-19ea-4057-9191-112da7effa31' \
     -H 'X-Monite-Version: 2023-09-01' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{ "email": "info@example.com" }'
```

> **Info**
>
> Requests authenticated with an [entity user token](./users#get-entity-user-token) can update only that user's entity.
> The user must have a role with the `entity.update` permission.

## Access the current user's entity

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

* [`GET /entity_users/my_entity`](/v2023-09-01/api/entities/get-entity-users-my-entity) - get entity information.
* [`PATCH /entity_users/my_entity`](/v2023-09-01/api/entities/patch-entity-users-my-entity) - update entity information.

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

> Learn how Monite API Partners can manage their customers.