# 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](../requirements/index.html). 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](../index.html). For
an end-to-end purchasing and verification example, see [Buy a DID Number That
Requires Verification](../../../examples/buy-dids-with-verification.html).

## 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-identities.html).

```
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-identity.html).

```
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](create-identity.html).

```
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](update-identity.html).

```
PATCH /v3/identities/{id}
```

## Delete Identity

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

See [Delete Identity](delete-identity.html).

```
DELETE /v3/identities/{id}
```

## Data reference

See [Identity Object](identity-object.html) 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](../requirements/index.html) - Determine the allowed identity
  type, location restrictions, mandatory fields, and required evidence.
- [Addresses](../addresses/index.html) - Create and manage addresses linked to the
  Identity.
- [Proofs](../proofs/index.html) - Link accepted evidence to a personal or business
  Identity.
- [Permanent Supporting Documents](../permanent-documents/index.html) - Attach reusable
  supporting documents to the Identity.
- [Address Verifications](../address-verifications/index.html) - Submit DIDs and the
  prepared compliance records for review.
- [Countries](../../coverage-resources/countries/index.html) - Retrieve country IDs for
  the `country` and `birth_country` relationships.

On this page