v1

latestOpenAPI 3.0.02026-07-241220330.3 KB

Entities

Create a person entity

Creates a person entity

post/entities/persons

Request body

external_entity_idstring

genderstring

birth_datestring

name_firststring

name_middlestring

name_laststring

document_ssnstring

document_id_cardstring

document_licensestring

document_passportstring

addressesobject[]

pii_status'successful' | 'failed' | 'pending'

Example request

{
  "external_entity_id": "person-entity",
  "gender": "male",
  "birth_date": "1998-02-03",
  "name_first": "John",
  "name_last": "Doe",
  "document_ssn": "123456789",
  "document_id_card": null,
  "document_license": null,
  "document_passport": null,
  "addresses": [
    {
      "address_line_1": "41 E. 11th",
      "address_city": "New York",
      "address_state": "NY",
      "address_postal_code": "10003",
      "address_country_code": "US",
      "type": "primary"
    }
  ],
  "emails": [
    {
      "email_address": "john@alloy.com"
    }
  ],
  "phones": [
    {
      "phone_number": "555-000-1234"
    }
  ],
  "pii_status": "successful"
}

Response

Entity

status_codestring

entity_tokenstring

external_entity_idstring

created_atnumber

person_details_updated_atnumber

When the entity was most recently updated

genderstring

birth_datestring

name_firststring

name_middlestring

name_laststring

document_ssnstring

document_id_cardstring

document_licensestring

document_passportstring

addressesobject[]

typestring

Example response

{
  "entity_token": "P-urpS2U0hekJZW9UHMwAK",
  "external_entity_id": "1234abcd",
  "created_at": 1652195922608,
  "gender": "male",
  "birth_date": "1999-12-31",
  "name_first": "John",
  "name_last": "Doe",
  "document_ssn": "123456789",
  "document_id_card": null,
  "document_license": null,
  "document_passport": null,
  "addresses": [
    {
      "address_line_1": "41 E. 11th",
      "address_city": "New York",
      "address_state": "NY",
      "address_postal_code": "10003",
      "address_country_code": "US",
      "type": "primary"
    }
  ],
  "emails": [
    {
      "email_address": "john@alloy.com"
    }
  ],
  "phones": [
    {
      "phone_number": "555-000-1234"
    }
  ],
  "entity_groups": [
    {
      "external_entity_group_ids": [
        "81999dc0-20de-4953-b0b2-2b2f5809c87d"
      ],
      "entity_group_token": "EG-nqnHfUO9NtkazKzVWVqR",
      "entity_group_name": "Jane's Biscuit Company",
      "entity_group_type": "business",
      "roles": [
        "director",
        "beneficial_owner"
      ],
      "ownership_percentage": "20",
      "title": "Director of Sales",
      "entity_group_relationship_status": "successful",
      "relationship_created_at": "2025-12-18T14:01:00.000Z",
      "entity_group_created_at": "2025-12-16T14:53:10.538Z"
    }
  ],
  "_embedded": {
    "document_ssns": [
      {
        "document_ssn": "123456789",
        "evaluation_token": "L-x8Odl62GlJF93KDEml1d",
        "created_at": 1652367121580
      }
    ],
    "birth_dates": [
      {
        "birth_date": "1999-12-31",
        "evaluation_token": "L-CjsOLGbHtGhNEMd97XN1",
        "created_at": 1698681900932
      }
    ],
    "external_entity_ids": [
      {
        "external_entity_id": "1234abcd",
        "external_entity_id_type": null
      }
    ],
    "notes": [
      {
        "text": "This is a note",
        "created_at": 1698681900932,
        "updated_at": 1698681900932,
        "email": "janedoe@alloy.com",
        "name": "Jane Doe"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/v1/entities/persons/P-urpS2U0hekJZW9UHMwAK"
    }
  }
}