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' \
  -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 'x-monite-entity-id: 9d2b4c8f-2087-4738-ba91-7359683c49a4' \
     -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}.

📘

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


Did this page help you?