Common Concepts

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 separate 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.

POST
/entityGroup
1from mercoa import Mercoa
2from mercoa.entity_group_types import EntityGroupCreateRequest
3
4client = Mercoa(
5    token="YOUR_TOKEN",
6)
7client.entity_group.create(
8    request=EntityGroupCreateRequest(
9        foreign_id="your-group-id",
10        name="AcmeConglomerate",
11        email_to_name="acmegroup",
12        entity_ids=[
13            "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
14            "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
15        ],
16    ),
17)

Email Inbox

Entity groups have an email inbox that is independent 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.

POST
/entityGroup/:entityGroupId/user
1from mercoa import Mercoa
2from mercoa.entity_group_types import (
3    EntityGroupUserEntityRequest,
4    EntityGroupUserRequest,
5)
6
7client = Mercoa(
8    token="YOUR_TOKEN",
9)
10client.entity_group.user.create(
11    entity_group_id="entg_8545a84e-a45f-41bf-bdf1-33b42a55812c",
12    request=EntityGroupUserRequest(
13        foreign_id="MY-DB-ID-12345",
14        email="john.doe@acme.com",
15        name="John Doe",
16        entities=[
17            EntityGroupUserEntityRequest(
18                roles=["admin", "approver"],
19                entity_id="ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
20            ),
21            EntityGroupUserEntityRequest(
22                roles=["viewer"],
23                entity_id="ent_9e02a20e-7749-47de-8d8a-f8ff2859fa90",
24            ),
25        ],
26    ),
27)

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.

POST
/entityGroup/:entityGroupId/user/:foreignId/token
1from mercoa import Mercoa
2from mercoa.entity_types import TokenGenerationOptions
3
4client = Mercoa(
5    token="YOUR_TOKEN",
6)
7client.entity_group.user.get_token(
8    entity_group_id="entg_a0f6ea94-0761-4a5e-a416-3c453cb7eced",
9    foreign_id="MY-DB-ID-12345",
10    request=TokenGenerationOptions(
11        expires_in="1h",
12    ),
13)

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

Example

In this example, we have three entities that are part of the same group.

  1. A west coast business called “West Coast Corp” with an entity id if ent_e8c2af94-61cd-4036-a765-80341209167b
  2. A east coast business called “East Coast Inc” with an entity id of ent_1176dd0c-12e1-41c7-85a5-ae9b4746e64b
  3. A southern business called “Southern Company” with an entity id of ent_3dbb4ede-2d1d-49be-a996-a5dfad3641be

Create a group

First, we can create this group with these three entities:

POST
/entityGroup
1from mercoa import Mercoa
2from mercoa.entity_group_types import EntityGroupCreateRequest
3
4client = Mercoa(
5    token="YOUR_TOKEN",
6)
7client.entity_group.create(
8    request=EntityGroupCreateRequest(
9        foreign_id="your-group-id",
10        name="Coastal Corporation",
11        email_to_name="coastalcorp",
12        entity_ids=[
13            "ent_e8c2af94-61cd-4036-a765-80341209167b",
14            "ent_1176dd0c-12e1-41c7-85a5-ae9b4746e64b",
15            "ent_3dbb4ede-2d1d-49be-a996-a5dfad3641be",
16        ],
17    ),
18)

Add a user to all entities in the group with the same role

Next, let’s say we want to add a user to all entities in the group with the “admin” role.

POST
/entityGroup/:entityGroupId/user
1from mercoa import Mercoa
2from mercoa.entity_group_types import (
3    EntityGroupUserEntityRequest,
4    EntityGroupUserRequest,
5)
6
7client = Mercoa(
8    token="YOUR_TOKEN",
9)
10client.entity_group.user.create(
11    entity_group_id="entg_8545a84e-a45f-41bf-bdf1-33b42a55812c",
12    request=EntityGroupUserRequest(
13        foreign_id="MY-DB-ID-12345",
14        email="john.doe@acme.com",
15        name="John Doe",
16        entities=[
17            EntityGroupUserEntityRequest(
18                roles=["admin", "approver"],
19                entity_id="ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
20            ),
21            EntityGroupUserEntityRequest(
22                roles=["viewer"],
23                entity_id="ent_9e02a20e-7749-47de-8d8a-f8ff2859fa90",
24            ),
25        ],
26    ),
27)

Add a user to specific entities in the group with different roles

Next, let’s say we want to add a user to all entities in the group, but we want to give the user a different role for each entity.

POST
/entityGroup/:entityGroupId/user
1from mercoa import Mercoa
2from mercoa.entity_group_types import (
3    EntityGroupUserEntityRequest,
4    EntityGroupUserRequest,
5)
6
7client = Mercoa(
8    token="YOUR_TOKEN",
9)
10client.entity_group.user.create(
11    entity_group_id="entg_8545a84e-a45f-41bf-bdf1-33b42a55812c",
12    request=EntityGroupUserRequest(
13        foreign_id="MY-DB-ID-12345",
14        email="john.doe@acme.com",
15        name="John Doe",
16        entities=[
17            EntityGroupUserEntityRequest(
18                roles=["admin", "approver"],
19                entity_id="ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
20            ),
21            EntityGroupUserEntityRequest(
22                roles=["viewer"],
23                entity_id="ent_9e02a20e-7749-47de-8d8a-f8ff2859fa90",
24            ),
25        ],
26    ),
27)

Add another entity to the group

Next, let’s say we want to add another entity to the group.

When adding an entity to a group, you can optionally copy the users from an existing entity in the group. Do this using the copyUsersFrom field. You can specify an entity ID or set this to true to copy users from the entity with the most users that has been updated most recently.

Sync Users

If at any point users have been added to a specific entity in the group instead of the group itself, you can sync the users from the entity to the group.

This will let you make sure that all entities in the group have the same users as needed.

POST
/entityGroup/:entityGroupId/sync-users
1from mercoa import Mercoa
2from mercoa.entity_group_types import EntityGroupUserSyncRequest
3
4client = Mercoa(
5    token="YOUR_TOKEN",
6)
7client.entity_group.user.sync(
8    entity_group_id="entg_8545a84e-a45f-41bf-bdf1-33b42a55812c",
9    request=EntityGroupUserSyncRequest(
10        filter_roles=["approver", "viewer"],
11    ),
12)