Entity Groups
API Reference
Many times, you want to manage a group of businesses as a group. Some examples of this include:
- A group of franchise businesses owned by the same person, where each location is a seperate LLC
- A parent company with multiple subsidiaries
- 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.
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.
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.
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.
- A west coast business called “West Coast Corp” with an entity id if
ent_e8c2af94-61cd-4036-a765-80341209167b
- A east coast business called “East Coast Inc” with an entity id of
ent_1176dd0c-12e1-41c7-85a5-ae9b4746e64b
- 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:
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.
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.
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.