Create Identity#

Create single Identity owned by your account.

Request#

HTTP Method: POST

URI Path: /v3/identities/

Request Body Object Attributes#

Name

Type

Is Required?

Description

first_name

string

Yes

First name of the personal identity.

last_name

string

Yes

Last name of the personal identity.

phone_number

string

Yes

Phone number of the personal identity. Only digits allowed.

personal_tax_id

string

No

Personal tax ID of the personal identity.

birth_date

string

No

Birth date of the personal identity in ISO 8601 format.

id_number

string

No

ID number of the personal identity.

description

string

No

Description of the personal identity.

external_reference_id

string

No

Identifier for identity in external system

identity_type

string

Yes

Type of identity. Write personal to create a personal identity.

contact_email

string

No

Contact email address of identity. Must be a valid email address.

company_website is not accepted for a personal identity: sending a value returns 422 Unprocessable Entity.

Request Body Object Relationships#

Title

Type

Description

country

Country Object

Specifies the country for identity. Required when vat_id is set.

birth_country

Country Object

Specifies the birth country for identity. In version 2026-11-19, it is handled separately from country and is not auto-assigned.

Note

Assigning country does not automatically assign birth_country. Set birth_country explicitly when needed.

Examples#

http

 1POST /v3/identities HTTP/1.1
 2Host: api.didww.com
 3Content-Type: application/vnd.api+json
 4Accept: application/vnd.api+json
 5Authorization: Bearer [access token]
 6
 7{
 8  "data": {
 9    "type": "identities",
10    "attributes": {
11      "first_name": "string",
12      "last_name": "string",
13      "phone_number": "35319015266",
14      "birth_date": null,
15      "id_number": "string",
16      "description": "string",
17      "personal_tax_id": "string",
18      "external_reference_id": "string",
19      "identity_type": "personal",
20      "contact_email": "jane@example.com"
21    }
22  }
23}

curl

1curl -i -X POST https://api.didww.com/v3/identities -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"birth_date": null, "contact_email": "jane@example.com", "description": "string", "external_reference_id": "string", "first_name": "string", "id_number": "string", "identity_type": "personal", "last_name": "string", "personal_tax_id": "string", "phone_number": "35319015266"}, "type": "identities"}}'

response

 1HTTP/1.1 201 Created
 2Content-Type: application/vnd.api+json
 3
 4{
 5  "data": {
 6    "id": "39623bf9-381f-4da6-ab29-2d3eb8783d81",
 7    "type": "identities",
 8    "attributes": {
 9      "first_name": "string",
10      "last_name": "string",
11      "phone_number": "35319015266",
12      "id_number": "string",
13      "birth_date": null,
14      "company_name": null,
15      "company_website": null,
16      "company_reg_number": null,
17      "vat_id": null,
18      "description": "string",
19      "personal_tax_id": "string",
20      "identity_type": "personal",
21      "created_at": "2021-03-22T11:53:32.240Z",
22      "external_reference_id": "string",
23      "verified": false,
24      "contact_email": "jane@example.com"
25    },
26    "relationships": {
27      "country": {
28        "links": {
29          "self": "https://api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/relationships/country",
30          "related": "https://api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/country"
31        }
32      },
33      "birth_country": {
34        "links": {
35          "self": "https://api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/relationships/birth_country",
36          "related": "https://api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/birth_country"
37        }
38      },
39      "proofs": {
40        "links": {
41          "self": "https://api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/relationships/proofs",
42          "related": "https://api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/proofs"
43        }
44      },
45      "addresses": {
46        "links": {
47          "self": "https://api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/relationships/addresses",
48          "related": "https://api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/addresses"
49        }
50      },
51      "permanent_documents": {
52        "links": {
53          "self": "https://api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/relationships/permanent_documents",
54          "related": "https://api.didww.com/v3/identities/39623bf9-381f-4da6-ab29-2d3eb8783d81/permanent_documents"
55        }
56      }
57    }
58  },
59  "meta": {
60    "api_version": "2026-11-19"
61  }
62}

Other Responses#

Code

Success

Description

400

No

Bad Request. The body carries a member the API does not accept.

401

No

Unauthorized

403

No

The access token carries the read scope, which does not cover this method (title Insufficient scope). The response carries WWW-Authenticate: Bearer error="insufficient_scope". See Scopes.

422

No

Validation error. The identity was rejected.

429

No

The request budget of the account for the current window is spent (too_many_requests). Retry-After gives the number of seconds to wait.