Ongoing Monitoring with Entity Groups
Entity Group is a new record type, which can be used to associate multiple Person and Business Entities together at the point of onboarding and update throughout the entity lifecycle. The primary purpose of Entity Groups is to create data/relationships to enable decisioning across multiple entities. Entity Groups serve as the connective value that each Person and Business Entity can have a relationship to and each relationship will support contextual values.
The Events API supports creating and updating Entity Group data across multiple event types (see examples) so that clients can manage Entity Group data throughout the entity lifecycle.
- Adding & Updating Entity to Entity Groups Relationships: Entity to entity group relationships can be added and updated through
entity_group_*,person_*, andbusiness_*events - Removing Entities from Entity Groups: Entities can be removed through entity update events. When an entity is removed from an entity group, it will no longer be available in an entity group API response BUT entity group relationships are versioned so the data does still exist.
- To remove an entity from a group provide this boolean parameter to any entity within the array:
remove_entity
- To remove an entity from a group provide this boolean parameter to any entity within the array:
Request Overview
Entity Group Fields
Field | Type | Description |
|---|---|---|
entity_group_token | string | Alloy-defined Entity Group identifier that can be used to update existing Entity Groups. The Entity Group Token is assigned as soon as a new Entity record is created in Alloy’s system. |
external_entity_group_id | string | Client-defined Entity Group identifier that should be provided when providing new Entity Group information for the first time. Can also be used interchangeably with Entity Group Tokens to update existing Entity Groups. Recommended when creating a new Entity Group |
entity_group_name | string | Name or description of the Entity Group and the related Entities Recommended when creating a new Entity Group |
entity_group_type | string | Standardized type value for each Entity Group Supported Values: Recommended when creating a new Entity Group |
Entity Group Relationship Data Fields
Field | Type | Description |
|---|---|---|
roles | array | Designate the Entity role in relation to the Entity Group. Supported Values: * Each Entity Group must have a primary entity. For KYB/pKYB the primary entity should be a business entity. |
title | string | If relevant, the Entity's title related to the Entity Group (e.g., Chief Financial Officer, Primary Account Holder) |
ownership_percentage | string | The whole number percentage value of an Entity's ownership of a business Entity Group. Supports values 0-100. |
remove_entity | boolean | Set this field to |
Examples
Entity Group Created Request/Response
{
"data": {
"name": "Trust Co",
"type": "business",
"timestamp": "2025-12-04T23:29:20.839Z",
"entities": [
{
"external_entity_id": "f15481af-9bd0-44be-bcca-0deba23c203c",
"roles": [
"primary",
"shareholder"
]
},
{
"external_entity_id": "55fe8955-7e7b-4785-b9fa-60dac5e89fc8",
"roles": [
"shareholder",
"director"
],
"title": "Executive Director",
"ownership_percentage": 10
}
],
"external_entity_group_ids": [
{
"external_entity_id": "ccd37a77-9089-452d-ac55-c0ca7d7ffdff"
}
],
"supplemental_data": {},
"meta": {}
},
"external_event_id": "6514b21a-a791-4d7f-816c-9a3caa8bda45",
"external_lifecycle_id": "2983e9ce-b4e2-4cf1-a780-294615e08343",
"event_type": "entity_group_created"
}{
"status_code": 201,
"event_request_token": "EV-xcP0uOfisrvYVuQxI2O8",
"_links": {
"self": {
"href": "/v1/events/EV-xcP0uOfisrvYVuQxI2O8"
}
},
"event": {
"event_type": "entity_group_created",
"event_status": "PROCESSED",
"data": {
"entity_group_token": "EG-VuyHal5GhTORaNfi0eG8",
"entity_group_name": "Trust Co",
"entity_group_type": "business",
"created_at": "2026-01-06T18:48:56.997Z",
"archived_at": null,
"entity_group_external_identifiers": [
"5216d25f-fe44-483d-ab22-6ba0ae25bbcc"
],
"entity_group_relationships": [
{
"entity_token": "B-uiTne2ewkES7fLHN6UuD",
"name": "Trust Co",
"type": "business",
"roles": [
"primary",
"shareholder"
],
"relationship_created_at": "2025-12-04T23:29:20.839Z",
"bank_accounts": []
},
{
"entity_token": "P-ewaa6ImCcpv7FM2XhpNe",
"name": "Lucy Schoen",
"title": "Executive Director",
"type": "person",
"ownership_percentage": 10,
"roles": [
"shareholder",
"director"
],
"relationship_created_at": "2025-12-04T23:29:20.839Z",
"bank_accounts": []
}
],
"timestamp": "2025-12-04T23:29:20.839Z",
"_links": {
"self": {
"href": "/v1/entity-groups/EG-VuyHal5GhTORaNfi0eG8"
}
}
},
"evaluations": [],
"journey_applications": []
}
}Entity Group Updated Request/Response
{
"data": {
"name": "Trusting Operations",
"timestamp": "2025-12-10T23:29:20.839Z",
"entities": [
{
"entity_token": "P-ewaa6ImCcpv7FM2XhpNe",
"roles": [
"authorized_signer",
"shareholder"
],
"ownership_percentage": 10
},
{
"external_entity_id": "55fe8955-7e7b-4785-b9fa-60dac5e89fc8",
"ownership_percentage": 0,
"remove_entity": true
},
],
"external_entity_group_ids": [
{
"external_entity_id": "5216d25f-fe44-483d-ab22-6ba0ae25bbcc"
}
],
"supplemental_data": {},
"meta": {}
},
"external_event_id": "76d0ce8e-7c2a-4429-90c3-569927be1a53",
"external_lifecycle_id": "5fb3610d-066d-483d-bf45-1ddb0e9bfff5",
"event_type": "entity_group_updated"
}{
"status_code": 201,
"event_request_token": "EV-anrU0luX4aElzMX0Xm0T",
"_links": {
"self": {
"href": "/v1/events/EV-anrU0luX4aElzMX0Xm0T"
}
},
"event": {
"event_type": "entity_group_updated",
"event_status": "PROCESSED",
"data": {
"entity_group_token": "EG-VuyHal5GhTORaNfi0eG8",
"entity_group_name": "Trusting Operations",
"entity_group_type": "business",
"created_at": "2026-01-06T18:48:56.997Z",
"archived_at": null,
"entity_group_external_identifiers": [
"5216d25f-fe44-483d-ab22-6ba0ae25bbcc"
],
"entity_group_relationships": [
{
"entity_token": "B-uiTne2ewkES7fLHN6UuD",
"name": "Test biz",
"type": "business",
"roles": [
"primary",
"shareholder"
],
"relationship_created_at": "2025-12-04T23:29:20.839Z",
"bank_accounts": []
},
{
"entity_token": "P-g2g3YTOecIpAiZtFbhNi",
"name": "Jazmyn Streich",
"type": "person",
"ownership_percentage": 10,
"roles": [
"shareholder",
"authorized_signer"
],
"relationship_created_at": "2025-12-10T23:29:20.839Z",
"bank_accounts": []
},
{
"entity_token": "P-9NepEJvk53G9XVM7fH9f",
"name": "Leif Schaefer",
"title": "Finance Director",
"type": "person",
"ownership_percentage": null,
"roles": [
"shareholder",
"director"
],
"relationship_created_at": "2026-01-06T19:16:22.374Z",
"bank_accounts": []
},
{
"entity_token": "B-LTR8FbneLtGbirQqApFf",
"name": "GWR Inc",
"title": "Investor",
"type": "business",
"ownership_percentage": null,
"roles": [
"shareholder"
],
"relationship_created_at": "2026-01-06T19:33:22.137Z",
"bank_accounts": [
{
"bank_account_token": "A-cn8cN9IuEgK39nNweuvY",
"account_holder_type": "primary",
"external_account_id": "bag123"
}
]
}
],
"timestamp": "2025-12-11T23:29:20.839Z",
"_links": {
"self": {
"href": "/v1/entity-groups/EG-VuyHal5GhTORaNfi0eG8"
}
}
},
"evaluations": [],
"journey_applications": []
}
}Person Created Request/Response
{
"data": {
"external_entity_id": "3cf944b2-8a6f-46ff-96df-f00d4392bf44",
"timestamp": "2026-01-03T22:23:07.712Z",
"name_first": "Leif",
"name_last": "Schaefer",
"birth_date": "1990-01-01",
"document_ssn": "111111111",
"phones": [{
"phone_number": "5747945102"
}],
"emails": [{
"email_address": "[email protected]"
}],
"addresses": [{
"line_1": "41 E. 11th",
"line_2": null,
"city": "New York",
"state": "NY",
"postal_code": "10003",
"country_code": "US",
"type": "primary"
}],
"entity_groups": [
{
"external_entity_group_id": "5216d25f-fe44-483d-ab22-6ba0ae25bbcc",
"title": "Finance Director",
"type": "person",
"roles": [
"shareholder",
"director"
]
}
],
"meta": {
"channel": "online"
},
"supplemental_data": {}
},
"event_type": "person_created",
"event_status": "successful",
"event_lifecycle_id": "34b28eac-b490-41b0-8691-ce44a0362d93"
}'{
"status_code": 201,
"event_request_token": "EV-SxNli8UnFZdq77VxRY9t",
"_links": {
"self": {
"href": "/v1/events/EV-SxNli8UnFZdq77VxRY9t"
}
},
"event": {
"event_type": "person_created",
"event_status": "PROCESSED",
"event_lifecycle_id": "411cd721-db42-46f4-9842-b7950adef6fa",
"data": {
"entity_token": "P-9NepEJvk53G9XVM7fH9f",
"external_entity_id": "3cf944b2-8a6f-46ff-96df-f00d4392bf44",
"created_at": 1767726982254,
"person_details_updated_at": 1767478987712,
"gender": null,
"birth_date": "1990-01-01",
"name_first": "Leif",
"name_middle": null,
"name_last": "Schaefer",
"document_ssn": "111111111",
"document_license": null,
"document_passport": null,
"addresses": [
{
"line_1": "41 E. 11th",
"line_2": null,
"city": "New York",
"state": "NY",
"postal_code": "10003",
"country_code": "US",
"created_at": 1767478987712,
"type": "primary",
"evaluation_token": null
}
],
"emails": [
{
"email_address": "[email protected]",
"created_at": 1767478987712
}
],
"phones": [
{
"phone_number": "+15747945102",
"type": "home",
"created_at": 1767478987712
}
],
"type": "person",
"_embedded": {
"document_ssns": [
{
"document_ssn": "111111111",
"created_at": 1767478987712
}
],
"external_entity_ids": [
{
"external_entity_id": "3cf944b2-8a6f-46ff-96df-f00d4392bf44",
"external_entity_id_type": null
}
],
"birth_dates": [
{
"birth_date": "1990-01-01",
"created_at": 1767478987712
}
],
"notes": []
},
"_links": {
"self": {
"href": "/v1/entities/persons/P-9NepEJvk53G9XVM7fH9f"
}
},
"entity_groups": [
{
"external_entity_group_ids": [
"5216d25f-fe44-483d-ab22-6ba0ae25bbcc"
],
"entity_group_token": "EG-VuyHal5GhTORaNfi0eG8",
"entity_group_name": "Trusting Operations",
"entity_group_type": "business",
"roles": [
"director",
"shareholder"
],
"ownership_percentage": null,
"title": "Finance Director",
"entity_group_relationship_status": "successful",
"relationship_created_at": "2026-01-06T19:16:22.374Z",
"entity_group_created_at": "2026-01-06T18:48:56.997Z"
}
]
},
"evaluations": [],
"journey_applications": []
}
}Person Updated Request/Response
{
"data": {
"external_entity_id": "3cf944b2-8a6f-46ff-96df-f00d4392bf44",
"timestamp": "2026-01-03T22:23:07.712Z",
"phones": [{
"phone_number": "2372439169"
}],
"emails": [{
"email_address": "[email protected]"
}],
"addresses": [{
"line_1": "41 Broadway",
"line_2": null,
"city": "New York",
"state": "NY",
"postal_code": "10004",
"country_code": "US",
"type": "business_primary"
}],
"entity_groups": [
{
"external_entity_group_id": "5216d25f-fe44-483d-ab22-6ba0ae25bbcc",
"title": "VP of Finance",
"ownership_percentage": 10
}
],
"meta": {
"channel": "online"
},
"supplemental_data": {}
},
"event_type": "person_updated",
"event_status": "successful",
"event_lifecycle_id": "23820c14-d607-49f6-a3a1-2ea6ec5dc518"
}{
"status_code": 201,
"event_request_token": "EV-OgOAKQrBiOcM6hCnECVp",
"_links": {
"self": {
"href": "/v1/events/EV-OgOAKQrBiOcM6hCnECVp"
}
},
"event": {
"event_type": "person_updated",
"event_status": "PROCESSED",
"event_lifecycle_id": "576eab1b-d97a-41e7-b20f-d081ed2cd75b",
"data": {
"entity_token": "P-9NepEJvk53G9XVM7fH9f",
"external_entity_id": "3cf944b2-8a6f-46ff-96df-f00d4392bf44",
"created_at": 1767726982254,
"person_details_updated_at": 1767478987712,
"gender": null,
"birth_date": "1990-01-01",
"name_first": "Leif",
"name_middle": null,
"name_last": "Schaefer",
"document_ssn": "111111111",
"document_license": null,
"document_passport": null,
"addresses": [
{
"line_1": "41 Broadway",
"line_2": null,
"city": "New York",
"state": "NY",
"postal_code": "10004",
"country_code": "US",
"created_at": 1767478987712,
"type": "business_primary",
"evaluation_token": null
},
{
"line_1": "41 E. 11th",
"line_2": null,
"city": "New York",
"state": "NY",
"postal_code": "10003",
"country_code": "US",
"created_at": 1767478987712,
"type": "primary",
"evaluation_token": null
}
],
"emails": [
{
"email_address": "[email protected]",
"created_at": 1767478987712
},
{
"email_address": "[email protected]",
"created_at": 1767478987712
}
],
"phones": [
{
"phone_number": "+15747945102",
"type": "home",
"created_at": 1767478987712
},
{
"phone_number": "+12372439169",
"type": "home",
"created_at": 1767478987712
}
],
"type": "person",
"_embedded": {
"document_ssns": [
{
"document_ssn": "111111111",
"created_at": 1767478987712
}
],
"external_entity_ids": [
{
"external_entity_id": "3cf944b2-8a6f-46ff-96df-f00d4392bf44",
"external_entity_id_type": null
}
],
"birth_dates": [
{
"birth_date": "1990-01-01",
"created_at": 1767478987712
}
],
"notes": []
},
"_links": {
"self": {
"href": "/v1/entities/persons/P-9NepEJvk53G9XVM7fH9f"
}
}
},
"evaluations": [
{
"error": null,
"evaluation_token": "L-KbPeRcbBCV1m1woEUcvs",
"workflow_token": "PVIdeFAeYkzE4bTSYRdxRWQkPqd7q3Xg",
"workflow_version_id": 4,
"prefiltered": false,
"summary": {
"result": "success",
"outcome": "Manual Review",
"outcome_reasons": [],
"tags": []
},
"_links": {
"self": {
"href": "/v1/evaluations/L-KbPeRcbBCV1m1woEUcvs"
}
}
}
],
"journey_applications": []
}
}Business Created Request/Response
{
"data": {
"external_entity_id": "3e173a4d-9f40-40a3-894d-1eda3a48089d",
"timestamp": "2026-01-04T22:23:07.712Z",
"addresses": [
{
"type": "business_primary",
"line_1": "565 Weissnat Lakes",
"city": "Kayborough",
"postal_code": "AB111",
"state": "NY",
"country_code": "US"
}
],
"business_name": "Greenholt, Wilkinson and Romaguera",
"business_registry_id": "13145201",
"entity_groups": [
{
"external_entity_group_id": "5216d25f-fe44-483d-ab22-6ba0ae25bbcc",
"title": "Investor",
"type": "business",
"roles": [
"shareholder"
]
}
],
"supplemental_data": {}
},
"event_type": "business_created",
"event_status": "successful",
"event_lifecycle_id": "99c9168a-e378-4fdd-9464-47219ce07e2c"
}{
"status_code": 201,
"event_request_token": "EV-oMRq5dLMC5CM6R3FvfKy",
"_links": {
"self": {
"href": "/v1/events/EV-oMRq5dLMC5CM6R3FvfKy"
}
},
"event": {
"event_type": "business_created",
"event_status": "PROCESSED",
"event_lifecycle_id": "99c9168a-e378-4fdd-9464-47219ce07e2c",
"data": {
"entity_token": "B-LTR8FbneLtGbirQqApFf",
"external_entity_id": "3e173a4d-9f40-40a3-894d-1eda3a48089d",
"created_at": 1767728002045,
"business_name": "Greenholt, Wilkinson and Romaguera",
"business_alternate_name": null,
"business_federal_ein": null,
"business_registry_id": "13145201",
"addresses": [
{
"line_1": "565 Weissnat Lakes",
"line_2": null,
"city": "Kayborough",
"state": "NY",
"postal_code": "AB111",
"country_code": "US",
"created_at": 1767565387712,
"type": "business_primary",
"evaluation_token": null
}
],
"emails": [],
"phones": [],
"type": "business",
"_embedded": {
"external_entity_ids": [
{
"external_entity_id": "3e173a4d-9f40-40a3-894d-1eda3a48089d",
"external_entity_id_type": null
}
],
"notes": []
},
"_links": {
"self": {
"href": "/v1/entities/businesses/B-LTR8FbneLtGbirQqApFf"
}
},
"entity_groups": [
{
"external_entity_group_ids": [
"5216d25f-fe44-483d-ab22-6ba0ae25bbcc"
],
"entity_group_token": "EG-VuyHal5GhTORaNfi0eG8",
"entity_group_name": "Trusting Operations",
"entity_group_type": "business",
"roles": [
"shareholder"
],
"ownership_percentage": null,
"title": "Investor",
"entity_group_relationship_status": "successful",
"relationship_created_at": "2026-01-06T19:33:22.137Z",
"entity_group_created_at": "2026-01-06T18:48:56.997Z"
}
]
},
"evaluations": [],
"journey_applications": []
}
}Business Updated Request/Response
{
"data": {
"external_entity_id": "3e173a4d-9f40-40a3-894d-1eda3a48089d",
"timestamp": "2026-01-05T22:23:07.712Z",
"addresses": [
{
"type": "business_primary",
"line_1": "123 Main Street",
"city": "New York",
"postal_code": "10002",
"state": "NY",
"country_code": "US"
}
],
"business_name": "GWR Inc",
"entity_groups": [
{
"external_entity_group_id": "5216d25f-fe44-483d-ab22-6ba0ae25bbcc",
"ownership_percentage": 15
}
],
"supplemental_data": {}
},
"event_type": "business_updated",
"event_status": "successful",
"event_lifecycle_id": "87141355-155e-49bd-a564-cef4fae5dd29"
}{
"status_code": 201,
"event_request_token": "EV-2pXPA4iqFkvTX9V6HyUb",
"_links": {
"self": {
"href": "/v1/events/EV-2pXPA4iqFkvTX9V6HyUb"
}
},
"event": {
"event_type": "business_updated",
"event_status": "PROCESSED",
"event_lifecycle_id": "87141355-155e-49bd-a564-cef4fae5dd29",
"data": {
"entity_token": "B-LTR8FbneLtGbirQqApFf",
"external_entity_id": "3e173a4d-9f40-40a3-894d-1eda3a48089d",
"created_at": 1767728002045,
"business_name": "GWR Inc",
"business_alternate_name": null,
"business_federal_ein": null,
"business_registry_id": "13145201",
"addresses": [
{
"line_1": "123 Main Street",
"line_2": null,
"city": "New York",
"state": "NY",
"postal_code": "10002",
"country_code": "US",
"created_at": 1767651787712,
"type": "business_primary",
"evaluation_token": null
},
{
"line_1": "565 Weissnat Lakes",
"line_2": null,
"city": "Kayborough",
"state": "NY",
"postal_code": "AB111",
"country_code": "US",
"created_at": 1767565387712,
"type": "business_primary",
"evaluation_token": null
}
],
"emails": [],
"phones": [],
"type": "business",
"_embedded": {
"external_entity_ids": [
{
"external_entity_id": "3e173a4d-9f40-40a3-894d-1eda3a48089d",
"external_entity_id_type": null
}
],
"notes": []
},
"_links": {
"self": {
"href": "/v1/entities/businesses/B-LTR8FbneLtGbirQqApFf"
}
}
},
"evaluations": [],
"journey_applications": []
}
}Updated 2 days ago