---
title: "Create a person entity"
method: POST
path: "/entities/persons"
tags: ["Entities"]
---

# Create a person entity

`POST /entities/persons`

Creates a person entity

## Request body

- object
  - `external_entity_id` string
  - `gender` string
  - `birth_date` string
  - `name_first` string
  - `name_middle` string
  - `name_last` string
  - `document_ssn` string
  - `document_id_card` string
  - `document_license` string
  - `document_passport` string
  - `addresses` object[]
  - `emails` object[]
    - `email_address` string
  - `phones` object[]
    - `phone_number` string
  - `pii_status` 'successful' | 'failed' | 'pending'

## Response `201`

Entity

- object
  - `status_code` string
  - `entity_token` string
  - `external_entity_id` string
  - `created_at` number
  - `person_details_updated_at` number — When the entity was most recently updated
  - `gender` string
  - `birth_date` string
  - `name_first` string
  - `name_middle` string
  - `name_last` string
  - `document_ssn` string
  - `document_id_card` string
  - `document_license` string
  - `document_passport` string
  - `addresses` object[]
  - `emails` object[]
    - `email_address` string
  - `phones` object[]
    - `phone_number` string
    - `type` string
  - `entity_groups` object[]
    - `external_entity_group_ids` string[]
    - `entity_group_token` string
    - `entity_group_name` string
    - `entity_group_type` 'business' | 'joint_account' | 'membership' | 'merchant'
    - `roles` string[]
    - `ownership_percentage` string
    - `title` string
    - `entity_group_relationship_status` string
    - `relationship_created_at` string
    - `entity_group_created_at` string
  - `type` string
  - `_embedded` object
    - `notes` Items[] — unresolved $ref
    - `document_ssns` object[]
      - `document_ssn` string — The plaintext value of the entity's SSN.
      - `evaluation_token` string — The evaluation in which the SSN was added to the entity
      - `created_at` number — When the SSN was added to the entity
    - `external_entity_ids` object[]
      - `external_entity_id` string
      - `external_entity_id_type` string
    - `birth_dates` object[]
      - `birth_date` string, date — The plaintext value of the entity's date of birth
      - `evaluation_token` string — The evaluation in which the date of birth was added to the entity
      - `created_at` number — When the date of birth was added to the entity
  - `_links` object
    - `self` object
      - `href` string — A link back to this entity

## Other responses

- `400` — Missing required fields

---

[API](https://skmtc.dev/alloy/apis/alloy-api.md) · [All operations](https://skmtc.dev/alloy/apis/alloy-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/alloy/alloy-api/revisions/405799de4d2a/schema)