Identities

Use the Identities resource to retrieve and manage personal or business identity records used for DID registration and verification.

An Identity represents the person or business responsible for a DID phone number. It stores contact and registration details and can be related to a country, birth country, Addresses, Proofs, and Permanent Supporting Documents. The verified attribute indicates whether the Identity has been verified.

Before creating an Identity, retrieve the applicable Address Requirement. The requirement determines which identity type can be used, where the Identity must be located, which fields are mandatory, and whether proofs or supporting documents are needed.

Note

For the complete registration workflow, see Regulation Resources. For an end-to-end purchasing and verification example, see Buy a DID Number That Requires Verification.

Requirements and behavior

• Set identity_type to personal or business when creating an Identity.

• A personal Identity requires first_name, last_name, and phone_number.

• A business Identity also requires company_name and the first name, last name, and phone number of the company representative.

• Fields that are normally optional become required when they appear in the Address Requirement’s personal_mandatory_fields or business_mandatory_fields array.

• In API version 2026-04-16, country and birth_country are separate relationships. Assigning country does not assign birth_country automatically.

• Proofs can be linked to an Identity when proof of personal or business identity is required. Permanent Supporting Documents can also be linked for reuse.

• Once approved, an Identity may be reused for DID types with the same level of restrictions, provided that it continues to satisfy the applicable Address Requirement.

Endpoints

Action	Method	Endpoint
Retrieve all Identities	GET	/v3/identities
Retrieve Identity	GET	/v3/identities/{id}
Create Identity	POST	/v3/identities
Update Identity	PATCH	/v3/identities/{id}
Delete Identity	DELETE	/v3/identities/{id}

Retrieve all Identities

Retrieves all Identities associated with the account.

Use this endpoint to find existing records before creating another Identity. Results can be filtered by personal or business details, identity type, country ID, or external reference ID. Related countries, birth countries, Proofs, Addresses, and Permanent Supporting Documents can be included in the response.

See Retrieve All Identities.

GET /v3/identities

Retrieve Identity

Retrieves a specific Identity by its unique ID.

Use this endpoint to inspect the Identity’s attributes, verified status, and related country, birth country, Proofs, Addresses, or Permanent Supporting Documents.

See Retrieve Identity.

GET /v3/identities/{id}

Create Identity

Creates a personal or business Identity.

Use the applicable Address Requirement to select the identity type and supply all required attributes and country relationships. Set birth_country explicitly when it is required.

See Create Identity.

POST /v3/identities

Update Identity

Updates an existing Identity by its unique ID.

Use this endpoint to correct or complete personal details, business details, contact data, external references, or country relationships. Updating country does not update birth_country automatically.

See Update Identity.

PATCH /v3/identities/{id}

Delete Identity

Permanently deletes an Identity by its unique ID. A deleted Identity cannot be restored.

See Delete Identity.

DELETE /v3/identities/{id}

Data reference

See Identity Object for all attributes and relationships returned by the resource.

Common Identity use cases

Use case	Description
Find a reusable Identity	Search existing records before creating a duplicate Identity for another DID verification.
Create a personal Identity	Store the personal and contact details required for an individual end user.
Create a business Identity	Store company details and the required details of its representative.
Meet mandatory field requirements	Supply the fields listed in personal_mandatory_fields or business_mandatory_fields for the applicable Address Requirement.
Add identity proofs	Link accepted Proofs when the Address Requirement requires proof of personal or business identity.
Reuse permanent documents	Link Permanent Supporting Documents to an Identity for regulations that accept the same reusable document.
Review verification readiness	Retrieve the Identity with its related Addresses, Proofs, and Permanent Supporting Documents before validating the registration data.
Reconcile external records	Store and filter by external_reference_id to associate the Identity with a record in another system.

Related resources

• Address Requirements — Determine the allowed identity type, location restrictions, mandatory fields, and required evidence.

• Addresses — Create and manage addresses linked to the Identity.

• Proofs — Link accepted evidence to a personal or business Identity.

• Permanent Supporting Documents — Attach reusable supporting documents to the Identity.

• Address Verifications — Submit DIDs and the prepared compliance records for review.

• Countries — Retrieve country IDs for the country and birth_country relationships.