Entities PII

For customers using Alloy’s Entity API, a variety of functionality is available; whether you wish to see current entity information, create new entities, or update current associated data, the following information outlines capabilities of the API, and how best to utilize it for your needs.

GET: To fetch entity data for given entityToken, make a GET request to the following endpoints

Persons

HTTP Request: GET https://sandbox.alloy.co/v1/entities/persons/:entityToken

Sample Response:

{
    "entity_token": "P-sjabhefikwh",
    "external_entity_id": 'go-entities-go',
    "created_at":1620147294277,
    "person_details_updated_at":1620147403493,
    "type": "person",   
    "gender":null,
    "birth_date":null,
    "name_first":null,
    "name_middle":null,
    "name_last":null,
    "document_ssn":null,
    "document_id_card":null,
    "document_license":null,
    "document_passport":null,
    "addresses": [
      {
        "address_line_1": "",
        "address_line_2": "",
        "address_city": "",
        "address_state": "",
        "address_postal_code": "",
        "address_country_code": "",
        "type": "primary", // "secondary", "previous", "business_...",
        "created_at": 123412341234,
            "evaluation_token": "some-token"
      },{...}
    ],
    "emails": [
      {
        "email_address": "[email protected]"
        "created_at": 123412341234,
            "evaluation_token": "some-token"
      },{...}
    ],
    "phones": [
      {
        "phone_number": "2342342345",
        "type": "cell", // "cell", "home", "fax"
        "created_at": 123412341234,
            "evaluation_token": "some-token"
      },{...}
    ],
    "_embedded": {
        "document_ssns": [
          {
             "document_ssn": "123456789",
             "evaluation_token": "some-token",
             "created_at": 123412341234
          },{...}
        ],
        "birth_dates": [
          {
             "birth_date": "2019-10-23",
             "evaluation_token": "some-token",
             "created_at": 123412341234
          },{...}
        ],
    },
    "_links": {
        "self": {
                "href": "/v1/entities/persons/:entityToken"
        }
    }
}

Businesses

HTTP Request: GET https://sandbox.alloy.co/v1/entities/businesses/:entityToken

Sample Response:

{
  "status_code": 200,
  "error": null,
  "entity_token": "B-Fl0oPoO50vtlkJhGh8Sf",
  "created_at": "2023-01-05T00:29:46.729Z",
  "business_name": "First Mile Group, Inc.",
  "type": "business",
  "_links": {
    "self": {
      "href": "/v1/entities/businesses/B-Fl0oPoO50vtlkJhGh8Sf"
    }
  }
}

POST: To create new entity data, make a POST request to the following endpoints

Persons

HTTP Request: POST https://sandbox.alloy.co/v1/entities/persons

Sample Request:

{
    "external_entity_id": 'go-entities-go',
    "gender":null,
    "birth_date":null,
    "name_first":null,
    "name_middle":null,
    "name_last":null,
    "document_ssn":null,
    "document_id_card":null,
    "document_license":null,
    "document_passport":null,
    "addresses": [
      {
        "address_line_1": "",
        "address_line_2": "",
        "address_city": "",
        "address_state": "",
        "address_postal_code": "",
        "address_country_code": "",
        "type": "primary", // "secondary", "previous", "business_...",
      },{...}
    ],
    "emails": [
      {
        "email_address": "[email protected]"
      },{...}
    ],
    "phones": [
      {
        "phone_number": "2342342345"
      },{...}
    ]
}

Sample Response:

{
    "entity_token": "P-sjabhefikwh",
    "external_entity_id": 'go-entities-go',
    "type": "person",   
    "gender":null,
    "birth_date":null,
    "name_first":null,
    "name_middle":null,
    "name_last":null,
    "document_ssn":null,
    "document_id_card":null,
    "document_license":null,
    "document_passport":null,
    "addresses": [
      {
        "address_line_1": "",
        "address_line_2": "",
        "address_city": "",
        "address_state": "",
        "address_postal_code": "",
        "address_country_code": "",
        "type": "primary", // "secondary", "previous", "business_...",
      },{...}
    ],
    "emails": [
      {
        "email_address": "[email protected]"
      },{...}
    ],
    "phones": [
      {
        "phone_number":"2342342345"
      },{...}
    ],
    "_embedded": {
        "document_ssns": [
          {
             "document_ssn": "123456789",
          },{...}
        ],
        "birth_dates": [
          {
             "birth_date": "2019-10-23",
          },{...}
        ],
    },
    "_links": {
        "self": {
                "href": "/v1/entities/persons/:entityToken"
        }
    }
}

Businesses

HTTP Request: POST https://sandbox.alloy.co/v1/entities/businesses

Sample Request:

{
    "external_entity_id": "go-entities-go",
    "business_name": "Alloy",
    "addresses": [
      {
        "address_line_1": "123 W Fake St",
        "address_line_2": "Apt 1",
        "address_city": "New York",
        "address_state": "NY",
        "address_postal_code": "10003",
        "address_country_code": "US",
        "type": "primary", // "secondary", "previous", "business_..."
      },{...}
    ],
    "emails": [
      {
        "email_address": "[email protected]"
      },{...}
    ],
    "phones": [
      {
        "phone_number": "2342342345"
      },{...}
    ]
}

Sample Response:

{
  "status_code": 201,
  "error": null,
  "entity_token": "B-iy8XUzBXGc1Yg5PI6C0A",
  "created_at": "2023-01-05T00:33:58.610Z",
  "business_name": "Alloy",
  "type": "business",
  "_links": {
    "self": {
      "href": "/v1/entities/businesses/B-iy8XUzBXGc1Yg5PI6C0A"
    }
  }
}

PATCH: To update entity data, make a PATCH request to the following endpoints

Persons

HTTP Request: PATCH https://sandbox.alloy.co/v1/entities/persons/:entityToken

Sample Request:

{
    "gender":null,
    "birth_date":null,
    "name_first":null,
    "name_middle":null,
    "name_last":null,
    "document_ssn":null,
    "document_id_card":null,
    "document_license":null,
    "document_passport":null,
    "addresses": [
          {
            "address_line_1": "",
            "address_line_2": "",
            "address_city": "",
            "address_state": "",
            "address_postal_code": "",
            "address_country_code": "",
            "type": "primary", // "secondary", "previous", "business_...",
          },{...}
    ],
    "emails": [
      {
        "email_address": "[email protected]"
      },{...}
    ],
    "phones": [
      {
        "phone_number": "2342342345"
      },{...}
    ]
}

Sample Response:

{
    "external_entity_id": "go-entities-go",
    "type": "person",   
    "gender":null,
    "birth_date":null,
    "name_first":null,
    "name_middle":null,
    "name_last":null,
    "document_ssn":null,
    "document_id_card":null,
    "document_license":null,
    "document_passport":null,
    "addresses": [
          {
            "address_line_1": "",
            "address_line_2": "",
            "address_city": "",
            "address_state": "",
            "address_postal_code": "",
            "address_country_code": "",
            "type": "primary", // "secondary", "previous", "business_...",
          },{...}
    ],
    "emails": [
      {
        "email_address": "[email protected]"
      },{...}
    ],
    "phones": [
      {
        "phone_number": "2342342345"
      },{...}
    ],
    "_embedded": {
        "document_ssns": [
          {
             "document_ssn": "123456789",
             "evaluation_token": "some-token",
          },{...}
        ],
        "birth_dates": [
          {
             "birth_date": "2019-10-23",
             "evaluation_token": "some-token",
          },{...}
        ],
    },
    "_links": {
        "self": {
                "href": "/v1/entities/persons/:entityToken"
        }
    }
}

Businesses

HTTP Request: PATCH https://sandbox.alloy.co/v1/entities/businesses/:entityToken

Sample Request:

{
    "business_name": "Alloy",
    "addresses": [
          {
            "address_line_1": "",
            "address_line_2": "",
            "address_city": "",
            "address_state": "",
            "address_postal_code": "",
            "address_country_code": "",
            "type": "primary", // "secondary", "previous", "business_..."
          },{...}
        ],
    "emails": [
      {
        "email_address": "[email protected]"
      },{...}
    ],
    "phones": [
      {
        "phone_number":"2342342345",
        "type": "cell"
      },{...}
    ]
}

Sample Response: