For Individual Applicants:
The reference point for an individual or business in Alloy is the Entity Token - however, we can also ingest an Alloy-External-Entity-ID, which we then map to an Alloy Entity Token. The external ID can be anything, like a Customer ID.
Sending a header of Alloy-External-Entity-ID with any request to Alloy will create the mapping on the first call and retrieve the entity token on any subsequent calls to link the entity.
Alloy-External-Entity-ID: <your id>
Now,
Once we create the original Alloy Entity, we will not keep creating new Entities if the same External ID is passed with each subsequent call
Your ID is now permanently linked to our Alloy Entity Token
We'll return your External ID in every request to Alloy
Your external ID will be interchangeable with the Alloy Entity token for that Entity. So you'd be able to make a GET request to /entities/<your external ID>, for example, if you passed that External ID in with every request. This works on all endpoints across Alloy, including all Document endpoints.
For Groups:
When using Groups, which is a legacy feature of Alloy's, as laid out in our "How to Create a Group" documentation, you'll want to generate an Alloy-External-Group-ID, which will be your application ID, a unique ID that corresponds to the whole application session. It will be used to associate the applicants together into one group.
You'll want to pass the header in with each POST request to /evaluations with this header:
Alloy-External-Group-ID: <your group id>
How to Add an External Entity ID Later:
You can link an external ID to an Alloy Entity after it's already been created by using the PATCH /entities endpoint.
curl -X curl -X PATCH https://alloy.sandbox.co/v1/entities/<entity_token> \
-u application_token:application_secret \
-H "Content-Type: application/json" \
-d $'{
"external_entity_id": "110356540650141"
}'
The response from that request should then contain all the Entity's information (which you'd normally get from a GET request to that endpoint), plus an external_entity_id field.