Create Identity

Creates a new Person or Institution Identity on the Paxos Platform.

A successful response indicates that the identity has been created and is PENDING approval. The identity is only available to use on the Platform once it is APPROVED. For a full description of statuses read the status guide here.

For detailed guidance on which fields are required for your integration or the lifecycle of an Identity on the platform, please read the Identity Developer Guide.

POST /identity/identities

cURL

Create Person Identity

curl --request POST \
  --url https://api.paxos.com/v2/identity/identities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "person_details": {
    "verifier_type": "PASSTHROUGH",
    "passthrough_verifier_type": "JUMIO",
    "passthrough_verified_at": "2021-06-16T09:28:14Z",
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1980-01-01",
    "phone_number": "[phone]",
    "email": "[e-mail]",
    "cip_id": "111-11-1234",
    "cip_id_type": "SSN",
    "cip_id_country": "USA",
    "nationality": "USA",
    "address": {
      "country": "USA",
      "address1": "1 Example St",
      "city": "New York",
      "province": "NY",
      "zip_code": "10001"
    },
    "metadata": {
      "custom_property1": "custom value 1",
      "custom_property2": "custom value 2"
    }
  },
  "ref_id": "33ece656-eef1-43b5-a851-b6b9099089a5"
}
'

200

Create Person Identity with Passthrough

{
  "created_at": "2022-02-15T05:46:50.957068Z",
  "id": "36ae1728-c54a-4046-86df-8a413e0ab9b3",
  "person_details": {
    "additional_screening_status": "PENDING",
    "address": {
      "address1": "1 Example St",
      "city": "New York",
      "country": "USA",
      "province": "NY",
      "zip_code": "10001"
    },
    "cip_id": "111-11-1234",
    "cip_id_country": "USA",
    "cip_id_type": "SSN",
    "date_of_birth": "1980-01-01",
    "first_name": "John",
    "govt_id": "111-11-1234",
    "govt_id_type": "SSN",
    "id_verification_status": "APPROVED",
    "last_name": "Doe",
    "nationality": "USA",
    "passthrough_verified_at": "2021-06-16T09:28:14Z",
    "passthrough_verifier_type'": "JUMIO",
    "sanctions_verification_status": "PENDING",
    "verifier_type": "PASSTHROUGH"
  },
  "ref_id": "33ece656-eef1-43b5-a851-b6b9099089a5",
  "summary_status": "PENDING",
  "tax_details": [
    {
      "tax_payer_country": "USA",
      "tax_payer_id": "111-11-1234"
    }
  ],
  "type": "PERSON",
  "updated_at": "2022-02-15T05:46:50.957068Z"
}

OAuth Scope

identity:write_identity

Authorizations

Authorization · string · header · required

Paxos APIs use OAuth 2 with the client credentials grant flow.

Token URLs:

• Production: https://oauth.paxos.com/oauth2/token
• Sandbox: https://oauth.sandbox.paxos.com/oauth2/token

Learn more in the API credentials guide →

Body

application/json

person_details · object

Show child attributes

metadata · API User-facing metadata · object

Show child attributes

ref_id · string

A user-facing ID to prevent duplicate identity creation. Unique for all identities created by the same API user.

institution_details · object

Show child attributes

institution_members · object[]

Required for all institution identity types. The required roles and number of members vary by institution type; see the developer guide for details.

Show child attributes

tax_details · object[]

List of tax details associated with the identity. Must be set if tax_details_not_required is false or not set.

Show child attributes

tax_details_not_required · boolean

Set to true if tax details are not legally required. Must not be true when cip_id_country is USA.

customer_due_diligence · object

Show child attributes

is_merchant · boolean

Set to true to indicate that this identity is a merchant.

Response

200

application/json

A successful response.

id · string · required

metadata · API User-facing metadata · object

Show child attributes

status · enum<string>

Available options: PENDING, ERROR, APPROVED, DENIED, DISABLED

status_details · object

Show child attributes

summary_status · enum<string>

Available options: PENDING, ERROR, APPROVED, DENIED, DISABLED

user_disabled · boolean

Deprecated: use status_details.active_controls instead.

admin_disabled · boolean

Deprecated: use status_details.active_controls instead.

person_details · object

Show child attributes

type · enum<string>

Available options: PERSON, INSTITUTION

ref_id · string

A user-facing ID to prevent duplicate account creation. Unique for all accounts created by the same API user.

institution_details · object

Show child attributes

institution_members · members associated with institution identity type · object[]

Show child attributes

created_at · string<date-time>

The time at which the identity is created at. RFC3339 format, like YYYY-MM-DDTHH:MM:SS.sssZ. ex: 2006-01-02T15:04:05Z.

updated_at · string<date-time>

The time at which the identity is updated at. RFC3339 format, like YYYY-MM-DDTHH:MM:SS.sssZ. ex: 2006-01-02T15:04:05Z.

tax_details · tax payer details · object[]

Show child attributes

tax_details_not_required · boolean

summary_tin_verification_status · enum<string>

The TIN verification status for the associated tax_payer_id.

Available options: TIN_VERIFICATION_PENDING, TIN_VERIFICATION_ERROR, TIN_VERIFICATION_VALID

customer_due_diligence · object

Show child attributes

is_merchant · boolean

True if the identity is a merchant.

last_kyc_refresh_date · string<date-time>

The last timestamp the identity has undergone a periodic kyc refresh. RFC3339 format, like YYYY-MM-DDTHH:MM:SS.sssZ. ex: 2006-01-02T15:04:05Z.