Creating Entities and Accounts
Creating Entities
The first step in integrating Alloy for any ongoing monitoring use case is to create Entities. If you're using Alloy for onboarding and ongoing monitoring, your onboarding integration is responsible for this step, and Entities will automatically be created when submitting new applications through a Journey or Workflow.
Alloy strongly recommends using External Entity IDs to uniquely identify Entities, so you can re-use them later instead of referencing Alloy's assigned Entity Token. The identifier you choose for External Entity ID should be the best identification for a specific Person or Business record in your system of record - for example, a CIF Number or User ID. If you don’t assign an External Entity ID until after onboarding, you can update Alloy later to sync it to the Entity record retroactively.
If you aren't using Alloy for onboarding, or if you need to backfill Entities which were onboarded outside of Alloy, you can do so by submitting person_created or business_created Events, depending on the Entity type. As noted above, you should assign an external_entity_id upon Entity creation so that you can re-use it later when submitting other event types.
Examples
Person Created:
{
"event_type": "person_created",
"event_status": "successful",
"event_lifecycle_id": "X12-43jf-8743jkfdsa",
"data": {
"external_entity_id": "cf88a0a1-34d6-492d-b617-c8b43785e7b7",
"timestamp": "2024-03-25T22:23:07.712Z",
"name_first": "John",
"name_last": "Doe",
"birth_date": "1990-01-01",
"document_ssn": "666666666",
"phones": [{
"phone_number": "+19344281891"
}],
"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"
}],
"meta": {
"channel": "online"
},
"supplemental_data": {}
}
}
{
"status_code": 201,
"event_request_token": "EV-6E6Yj33Iz3DmTcglFFwa",
"_links": {
"self": {
"href": "/v1/events/EV-6E6Yj33Iz3DmTcglFFwa"
}
},
"event": {
"event_type": "person_created",
"event_status": "PROCESSED",
"data": {
"entity_token": "P-TfkFe6lCPkElc9Xktd3V",
"external_entity_id": "cf88a0a1-34d6-492d-b617-c8b43785e7b7",
"created_at": 1711405410009,
"person_details_updated_at": 1711405409394,
"gender": null,
"birth_date": "*********",
"name_first": "John",
"name_middle": null,
"name_last": "Doe",
"document_ssn": "*********",
"document_license": null,
"document_passport": null,
"addresses": [{
"line_1": "123 Allen St",
"line_2": "Apt 1",
"city": "New York",
"state": "NY",
"postal_code": "10002",
"country_code": "US",
"type": "primary"
}],
"emails": [{
"email_address": "[email protected]"
}],
"phones": [{
"phone_number": "+1934428189"
}],
"type": "person",
"_embedded": {
"document_ssns": [
{
"document_ssn": "*********",
"created_at": 1711405409394
}
],
"birth_dates": [
{
"birth_date": "*********",
"created_at": 1711405409394
}
]
},
"_links": {
"self": {
"href": "/v1/entities/persons/P-TfkFe6lCPkElc9Xktd3V"
}
}
},
"evaluations": [],
"journey_applications": []
}
}
Business Created:
{
"event_type": "business_created",
"event_status": "successful",
"event_lifecycle_id": "X12-43jf-8432favmjjja",
"data": {
"external_entity_id": "e3065d04-95aa-47a1-915c-84b575ff3855",
"business_name": "Operative Inc.",
"timestamp": "2024-03-25T22:06:56.771Z",
"business_federal_ein": "586179405",
"emails": [{
"email_address": "[email protected]"
}],
"addresses": [
{
"line_1": "123 Allen St",
"line_2": "Suite 1",
"city": "New York",
"state": "NY",
"postal_code": "10002",
"country_code": "US",
"type": "business_primary"
}
],
"supplemental_data": {},
"meta": {
"channel": "online"
}
}
}
{
"status_code": 201,
"event_request_token": "EV-YtbNK8AxWHJbMukXONsh",
"_links": {
"self": {
"href": "/v1/events/EV-YtbNK8AxWHJbMukXONsh"
}
},
"event": {
"event_type": "business_created",
"event_status": "PROCESSED",
"data": {
"entity_token": "B-4x8WzjvGz5Oz8RWA6MvY",
"external_entity_id": "e3065d04-95aa-47a1-915c-84b575ff3855",
"created_at": 1711404359986,
"business_name": "Operative Inc.",
"business_alternate_name": null,
"business_federal_ein": "586179405",
"business_registry_id": null,
"addresses": [
{
"line_1": "123 Allen St",
"line_2": "Suite 1",
"city": "New York",
"state": "NY",
"postal_code": "10002",
"created_at": 1711404359538,
"type": "business_primary",
"evaluation_token": null
}
],
"emails": [
{
"email_address": "[email protected]"
}
],
"phones": [],
"type": "business",
"_links": {
"self": {
"href": "/v1/entities/businesses/B-4x8WzjvGz5Oz8RWA6MvY"
}
}
},
"evaluations": [],
"journey_applications": []
}
}
Creating Accounts
If you're using Alloy to monitor transactions, in addition to creating Entity records, you'll also need to create an Account. You can create Accounts using the bank_account_created event type.
The entities[] array is a required field when creating new Account records, so you'll always need to create Entities first before creating a Account record. For real-time integrations, Alloy recommends creating an Account as soon as it's booked to your core and the account number (or equivalent unique identifier) is known.
Note: although creating Accounts is not required for certain types of ongoing monitoring (such as Logins), they must be created in order to use Alloy for monitoring transactions. If you're considering sending transaction data to Alloy for monitoring in the future, you may want to consider building Account creation into your integration in advance to make implementing transaction monitoring easier in the future.
When creating an account, you’ll need to supply an external_account_id as your unique identifier for the Account record, similar to the Entity’s external_entity_id.
Examples
Bank Account Created:
{
"event_type": "bank_account_created",
"event_status": "successful",
"event_lifecycle_id": "X99-43jf-434klj",
"data": {
"external_account_id": "8b75f5e2-b671-450c-9fb2-5aa05c286309",
"external_entity_id": "e3065d04-95aa-47a1-915c-84b575ff3855",
"timestamp": "2024-03-25T22:40:02.982Z",
"account_class": "deposit",
"account_name": "John Doe Business",
"product_name": "Alloy Business Checking",
"product_code": "DDA01",
"account_number": "76396628",
"routing_number": "000123456789",
"opening_date": "2023-03-22T00:00:00Z",
"closing_date": null,
"maturity_date": null,
"cif_number": null,
"card_network": "visa",
"country_code": "US",
"currency": "USD",
"status": "Active",
"status_detail": "Account is active",
"account_balance": 500000,
"entities": [
{
"account_holder_type": "primary",
"external_entity_id": "e3065d04-95aa-47a1-915c-84b575ff3855"
},
{
"account_holder_type": "secondary",
"external_entity_id": "9e82d5e7-ada0-4957-a8fd-4d937c99bae8"
}
],
"meta": {
"somedata": "string"
},
"supplemental_data": {}
}
}
{
"status_code": 201,
"event_request_token": "EV-feHKM66JaWfuJJ5BTApy",
"_links": {
"self": {
"href": "/v1/events/EV-feHKM66JaWfuJJ5BTApy"
}
},
"event": {
"event_type": "bank_account_created",
"event_status": "PROCESSED",
"data": {
"cif_number": null,
"product_code": "DDA01",
"product_name": "Alloy Business Checking",
"opening_date": "2023-03-22T00:00:00.000Z",
"meta": {
"somedata": "string"
},
"routing_number": "000123456789",
"card_network": "visa",
"account_name": "John Doe Business",
"account_class": "deposit",
"country_code": "US",
"entities": [
{
"entity_token": "P-TfkFe6lCPkElc9Xktd3V",
"external_entity_id": "9e82d5e7-ada0-4957-a8fd-4d937c99bae8",
"account_holder_type": "secondary"
},
{
"entity_token": "B-4x8WzjvGz5Oz8RWA6MvY",
"external_entity_id": "e3065d04-95aa-47a1-915c-84b575ff3855",
"account_holder_type": "primary"
}
],
"currency": "USD",
"account_number": "76396628",
"account_balance": "500000.00",
"credit_limit": null,
"status": "Active",
"status_detail": "Account is active",
"as_of_date": "2024-03-25T00:00:00.000Z",
"external_account_id": "8b75f5e2-b671-450c-9fb2-5aa05c286309",
"external_entity_id": "e3065d04-95aa-47a1-915c-84b575ff3855",
"account_token": "A-Rbdws17NItHaEy3HrHkL"
},
"evaluations": [],
"journey_applications": []
}
}
Updated 2 months ago