Skip to main content

​
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: 2024-05-25' \
     -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.",
         "business_structure": "private_corporation"
       }
     }'
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 individuals to accept payments. The last four digits of the person’s Social Security Number (SSN).
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",
  "status": "active",
  "created_at": "2022-04-21T14:23:01.691982+00:00",
  "updated_at": "2022-04-21T14:23:01.691994+00:00",
  ...
}
Notes:
  • An entity’s country (address.country) cannot be changed after the entity has been created.
  • US entities that wish to use payments must provide their phone number. It can be a US or international number.
  • 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.
  • After an entity is created, you must also add its bank accounts.
  • Entities can use Monite payment rails to accept and send payments. For this, the entity must be onboarded. Providing as much information as possible during the entity’s registration process will make the onboarding process smoother.
  • To use payments, entities of the organization type must also add information of the legally responsible individuals associated with the organization. See the Persons page for details.

​
Entity tax ID and VAT ID

This information applies to accounts receivable. The term “VAT” is used to collectively refer to VAT and sales tax (e.g. GST).
Monite requires at least one of tax ID or VAT ID specified for entities. Depending on the entity’s country and type (organization or individual), it may have both tax and VAT IDs or only one of them. In some countries, the tax ID is the same as VAT ID.
  • If an entity provides a VAT ID, Monite considers this entity VAT-registered and applies the corresponding regulatory validations to invoices.
  • If the entity is not VAT-registered, Monite expects that the entity provides its tax_id instead.
    • For organizations, tax_id can be the tax number or a similar business identifier.
    • For individuals, tax_id can be a government-issued identification number such as the taxpayer number, passport number, national ID, or similar.

​
Tax and VAT ID examples

Below are some examples of which values to provide in tax_id and VAT ID for various countries:
Counterpart countrytax_id valueVAT ID value
AustraliaABN
CanadaBusiness number (BN)GST/HST number, PST number (for British Columbia, Manitoba, and Saskatchewan), and/or QST number (for Québec). Use the corresponding type values when adding these numbers.
FranceRCS numberFrench VAT number
GermanyTax number (Steuernummer)German VAT number (USt-IdNr)
LiberiaTax Identification Number (TIN) *
LesothoTax Identification Number (TIN)
NetherlandsDutch Business Register number (KVK)Dutch VAT number
New ZealandIRD or NZBNGST number
PhilippinesTaxpayer Identification Number (TIN)Also TIN, if it’s registered for VAT
Spain: Canary IslandsNIF number
* Liberian tax number needs to be specified as the entity’s VAT ID rather than as its tax_id.
Monite does not validate tax and VAT IDs in national registries and does not check the value format.You are responsible for the accuracy of the entity information. Invoices will include the entity’s tax and/or VAT IDs whether or not they are valid.

​
Check if tax ID or VAT ID is required

Whether an entity’s tax ID and VAT ID are required on an invoice for it to be compliant depends on several factors, for example, the transaction type (e.g. B2B or B2C) or whether the sale is local or cross-border. Providing both the tax ID and VAT ID for entities (if available) helps reduce potential validation errors when issuing invoices. Before creating an invoice, you can use GET /receivables/required_fields to check the requirements for a parcitular customer country and type: 
GET /receivables/required_fields
  ? counterpart_country = <two-letter country code>
  & counterpart_type    = <organization | individual>
This endpoint returns invoice requirements for tax ID and VAT ID for the entity making the API call: 
{
  ...
  "entity": {
    "tax_id": {
      "description": "...",
      "required": false
    },
    "vat_id": {
      "description": "...",
      "required": true
    }
  },
  ...
}
You can provide the entity logo for use in the PDF documents generated by the entity (such as Accounts Receivable invoices and credit notes). The logo will also appear on the payment page 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//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: 2024-05-25' \
     -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: 
{
  "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. You can also delete the logo by calling DELETE /entities//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: 2024-05-25' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
Requests authenticated with an entity user token can access only that user’s entity. The user must have a role with the entity.read permission.

​
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: 2024-05-25' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{ "email": "info@example.com" }'
You can update all fields except address.country. The country of existing entities cannot be changed for regulatory reasons. The only way to change an entity’s country is to create a new entity.
Requests authenticated with an entity user token can update only that user’s entity. The user must have a role with the entity.update permission.

​
Deactivate and reactivate entities

Entities have a status field that can be active or inactive. Partners can deactivate entities to control access. New entities are created as active by default.
Only partner tokens can activate/deactivate entities.

​
Access the current user’s entity

If you use entity user tokens to authenticate Monite API requests, the following endpoints let you access the current user’s entity without providing its ID: To use these endpoints, the entity user in question must have a role with the entity.read and entity.update permissions, respectively.