Entities
Learn how Monite API Partners can manage their customers.
Overview
Entities represent the customers of Monite API partners 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.
Learn more about entities, entity users, and the Monite account structure.
Create an entity representing your customer
To create a new entity, call POST /entities
. The entity can be either an organization or an individual:
curl -X POST 'https://api.sandbox.monite.com/v1/entities' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"type": "organization",
"email": "[email protected]",
"phone": "5551235476",
"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"
}
}'
curl -X POST 'https://api.sandbox.monite.com/v1/entities' \
-H 'X-Monite-Version: 2023-04-12' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"type": "individual",
"email": "[email protected]",
"phone": "5551235476",
"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
- EU:
- 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, eithertax_id
or VAT ID, or both must be specified.- In France, the
tax_id
is the SIREN/SIRET number. - In the Netherlands, the tax_id is the Dutch Business Register number (KVK).
- A Liberian entity's tax number must be specified as its VAT ID rather than the
tax_id
.
- In France, the
A successful response returns the unique ID assigned to the created entity, along with the rest of the entity information:
{
"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",
...
}
Important
- Entities can be enabled to accept payments via Monite payment rails. For this, the entity must be onboarded. Check the list of required information for onboarding the entity for payments acceptance. 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.
- Entities of the
organization
type must also register the information of the legally responsible individuals associated with the organization. See the Persons page for further information.
Upload entity logo
You can provide the entity logo for use in the PDF documents generated by the entity (such as invoices and credit notes). 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
with a multipart/form-data
body containing the image in the file
field:
curl -X PUT 'https://api.sandbox.monite.com/v1/entities/{entity_id}/logo' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
-H 'Content-Type: multipart/form-data' \
-F '[email protected];type=image/png'
The specified logo is stored on Monite 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://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} or similar requests.
You can update the logo at any time later by uploading a new logo.
List all entities
To get information about all the entities managed by the partner, call GET /entities. This endpoint supports the standard pagination, sorting, and filtering parameters.
Get a single entity
To get information about a specific entity, call GET /entities/{entity_id}:
curl 'https://api.sandbox.monite.com/v1/entities/c5f499a7-19ea-4057-9191-112da7effa31' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'Authorization: Bearer ACCESS_TOKEN'
Alternatively, you can call GET /entities/me and provide the entity ID in the X-Monite-Entity-Id
header instead of in the request URL:
curl 'https://api.sandbox.monite.com/v1/entities/me' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: c5f499a7-19ea-4057-9191-112da7effa31' \
-H 'Authorization: Bearer ACCESS_TOKEN'
Update entity information
To update the details of an existing entity, call PATCH /entities/{entity_id}:
curl -X PATCH 'https://api.sandbox.monite.com/v1/entities/c5f499a7-19ea-4057-9191-112da7effa31' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "email": "[email protected]" }'
Alternatively, you can call PATCH /entities/me and provide the entity ID in the X-Monite-Entity-Id
header instead of in the request URL:
curl -X PATCH 'https://api.sandbox.monite.com/v1/entities/me' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: c5f499a7-19ea-4057-9191-112da7effa31' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "email": "[email protected]" }'
Updated about 1 month ago