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.

Create an entity representing your customer

To create a new entity, call POST /entities. The partner-level token is required for this action.

In the example below, the entity is created as an individual:

curl -X POST 'https://api.sandbox.monite.com/v1/entities' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
  "type": "individual",
  "email": "[email protected]",
  "address": {
    "country": "DE",
    "city": "Berlin",
    "state": "BE",
    "postal_code": "10115",
    "line1": "Flughafenstrasse 52"
  },
  "individual": {
    "first_name": "Bob",
    "last_name": "Jones",
    "tax_id": "1234567890"
  }
}'

The successful response contains the entity created as an individual:

{
  "address": {
    "country": "DE",
    "city": "Berlin",
    "state": "BE",
    "postal_code": "10115",
    "line1": "Flughafenstrasse 52",
    "line2": null
  },
  "email": "[email protected]",
  "partner_reference": null,
  "phone": null,
  "created_at": "2022-04-21T14:23:01.691982+00:00",
  "id": "aea39c7e-630f-4664-a449-de899ebd4912",
  "mailboxes": [
    {
      "id": "8a7f0edc-8842-46f3-94bc-5d363121d4d9",
      "entity_id": "aea39c7e-630f-4664-a449-de899ebd4912",
      "status": "active",
      "related_object_type": "payable",
      "mailbox_name": "460601980904250494_payables",
      "mailbox_full_address": "[email protected]",
      "belongs_to_mailbox_domain_id": null
    }
  ],
  "logo": null,
  "status": "active",
  "updated_at": "2022-04-21T14:23:01.691994+00:00",
  "type": "individual",
  "individual": {
    "first_name": "Bob",
    "last_name": "Jones",
    "vat_id": null,
    "tax_id": "1234567890",
    "title": null
  }
}

To create the entity as an organization, change the following parameters in the request body:

{
  ...
  "type": "organization",
  "organization": {
    "legal_name": "string",
    "vat_id": "string",
    "legal_entity_id": "string"
  }
  ...
}

Create the roles for this entity

If the customer represented by this entity has employees, which Monite refers to as entity users, a set of roles must be created for them in advance.

The role is created by calling POST /roles. The partner-level token and the entity ID are required for this action.

In the example below, a new role is created to allow the read permission for comment and payable objects:

curl -X POST 'https://api.sandbox.monite.com/v1/roles' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "View payables",
  "permissions": {
    "objects": [
      {
        "object_type": "comment",
        "actions": [
          {
            "action_name": "read",
            "permission": "allowed"
          }
        ]
      },
      {
        "object_type": "payable",
        "actions": [
          {
            "action_name": "read",
            "permission": "allowed"
          }
        ]
      }
    ]
  }
}'

The successful response contains the information about the role, including the role ID:

{
  "id": "2724e6bf-17b8-4462-b2ed-7d3e16c4a133",
  "name": "View payables",
  "permissions": {
    "objects": [
      {
        "object_type": "comment",
        "actions": [
          {
            "action_name": "read",
            "permission": "allowed"
          }
        ]
      },
      {
        "object_type": "payable",
        "actions": [
          {
            "action_name": "read",
            "permission": "allowed"
          }
        ]
      }
    ]
  },
  "status": "active",
  "created_at": "2022-09-28T12:06:01.589258+00:00",
  "updated_at": "2022-09-28T12:06:01.589272+00:00"
}

📘

This role ID will be used when creating entity users.

Update the logo of an entity

You can update the logo of a specific entity. The image can be PNG or JPG up to 10 MB in size.

To update the logo of an entity, call PUT /entities/{entity_id}/logo:

curl -X PUT 'https://api.sandbox.monite.com/v1/entities/{entity_id}/logo' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: multipart/form-data' \
     -F '[email protected];type=image/png'

The successful response contains information about the new logo:

{
  "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/jpeg",
  "url": "https://monite-file-saver-entity-logo-eu-central-1.s3.com/image.jpg",
  "size": 1691,
  "previews": [],
  "pages": []
}

List all entities

To get information about all the entities managed by the partner, call GET /entities.

Edit an entity

To edit an existing entity, call PATCH /entities/{entity_id}.

Retrieve an entity

To get information about a specific entity, call GET /entities/{entity_id}.

Manage entity's bank accounts

Add a bank account to an entity

Entities can have bank account information associated with them. To add a bank account to an entity, call POST /bank_accounts passing the entity ID in the header:

curl -X POST 'https://api.sandbox.monite.com/v1/bank_accounts' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "iban": "GB33BUKB20201555555555",
       "bic": "GB33BUKB202",
       "bank_name": "Bank",
       "display_name": "Bank",
       "is_default": false
     }'

The successful response returns the information about the newly added bank account:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "iban": "GB33BUKB20201555555555",
  "bic": "GB33BUKB202",
  "bank_name": "Bank",
  "display_name": "Bank",
  "is_default": false,
  "was_created_by_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Set the default bank account

Once the bank accounts are added to the entity, select a default bank account by calling POST /bank_accounts/{bank_account_id}/make_default:

curl -X POST 'https://api.sandbox.monite.com/v1/bank_accounts/3fa8...f66afa6/make_default' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d ''

The successful response contains information about the bank account marked as default:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "iban": "GB33BUKB20201555555555",
  "bic": "GB33BUKB202",
  "bank_name": "Bank name",
  "is_default": true,
  "display_name": "My main account",
  "was_created_by_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

List all bank accounts

To get information about all bank accounts associated with the specified entity, call GET /bank_accounts.

Retrieve a bank account

To get information about a specific bank account associated with the specified entity, call GET /bank_accounts/{entity_bank_account_id}.

Edit a bank account

To edit an existing bank account of the specified entity, call PATCH /bank_accounts/{entity_bank_account_id}.

Delete a bank account

To delete an existing bank account from the list of bank accounts associated with the specified entity, call DELETE /bank_accounts/{entity_bank_account_id}.

📘

Learn more about entities, entity users, and the Monite account structure.