HomeGuidesRecipesAPI ExplorerForumSupport
Partner Portal
Partner Portal

Entities

Learn how Monite API Partners can manage their customers.

Suggest Edits

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-01-31' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "type": "organization",
       "email": "[email protected]",
       "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"
       }
     }'

curl -X POST 'https://api.sandbox.monite.com/v1/entities' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
  "type": "individual",
  "email": "[email protected]",
  "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, either tax_id or VAT ID, or both must be specified.

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

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 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/{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: 2024-01-31' \
     -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. 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. 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-01-31' \
  -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: 2024-01-31' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{ "email": "[email protected]" }'

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.

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.

Updated about 1 month ago