Submit a ticket My Tickets
Login  Sign up

How to Use External ID's in Alloy

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 that a client passes us, 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>


  • 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, 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<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.

In the dashboard, that new external entity id will show up here:

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.