Entity Groups

API Reference

Many times, you want to manage a group of businesses as a group. Some examples of this include:

1. A group of franchise businesses owned by the same person, where each location is a seperate LLC
2. A parent company with multiple subsidiaries
3. An accountant who is managing the finances for multiple unrelated companies

Entity groups make managing these multi-entity situations much easier.

Creating a Group

An entity group consists of a list of entities. Entities can be added to more than one group, though this is typically not recommended.

You can create a group without any entities and add them later, or create the entities first and then add them to the group.

1
curl -X POST https://api.mercoa.com/entityGroup \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "foreignId": "your-group-id",
6
  "name": "AcmeConglomerate",
7
  "emailToName": "acmegroup",
8
  "entityIds": [
9
    "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
10
    "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"
11
  ]
12
}'

Email Inbox

Entity groups have an email inbox that is independant of the entities in the group. Invoices that are sent to this inbox get created in the UNASSIGNED state, and then can be assigned to an entity in the group for further processing.

Managing Users

Many times, you will want to manage users at the group level. For example, the same admin user might need access to all entities in the group. Mercoa uses the user’s foreignId to identity users across a group. Users can be added and removed from all entities in the group in a single API call, and roles can be managed on a per-entity basis.

1
curl -X POST https://api.mercoa.com/entityGroup/entg_8545a84e-a45f-41bf-bdf1-33b42a55812c/user \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "foreignId": "MY-DB-ID-12345",
6
  "email": "john.doe@acme.com",
7
  "name": "John Doe",
8
  "entities": [
9
    {
10
      "roles": [
11
        "admin",
12
        "approver"
13
      ],
14
      "entityId": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"
15
    },
16
    {
17
      "roles": [
18
        "viewer"
19
      ],
20
      "entityId": "ent_574s93r-3943-fu39-g9dfr-33b42a55812c"
21
    }
22
  ]
23
}'

Authentication

Entity groups allow you to create a JWT token at the group level or group user level. This token gives access to all entities in the group without needed to generate an unique token for every entity in the group.

1
curl -X POST https://api.mercoa.com/entityGroup/entg_a0f6ea94-0761-4a5e-a416-3c453cb7eced/user/MY-DB-ID-12345/token \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "expiresIn": "1h"
6
}'

This token can be used in the Mercoa API, SDKs, and React Library.