# Create Identity

Create single Identity owned by your account.

## Request

HTTP Method: `POST`

URI Path: `/v3/identities/`

### Request Body Object Attributes

PersonalBusiness

| 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`.

| Name | Type | Is Required? | Description |
| --- | --- | --- | --- |
| company\_name | `string` | Yes | Company name of the business identity. |
| company\_website | `string` | No | Company website of the business identity. Can be `null`. |
| company\_reg\_number | `string` | No | Company registration number of the business identity. |
| vat\_id | `string` | No | Company VAT ID of the business identity. Listed as `tax_id` in the mandatory fields of the address and emergency requirements. |
| first\_name | `string` | Yes | Company's representative First name of the business identity. |
| last\_name | `string` | Yes | Company's representative Last name of the business identity. |
| phone\_number | `string` | Yes | Company's representative Phone number of the business identity. Only digits allowed. |
| personal\_tax\_id | `string` | No | Company's representative Tax ID of the business identity. |
| birth\_date | `string` | No | Company's representative Birth date of the business identity in ISO 8601 format. |
| id\_number | `string` | No | Company's representative ID number of the business identity. |
| description | `string` | No | Company's representative description of the business identity. |
| external\_reference\_id | `string` | No | Identifier for identity in external system. |
| identity\_type | `string` | Yes | Identity type. Write `business` to create a business identity. |
| contact\_email | `string` | No | Contact email address of identity. Must be a valid email address. |

### Request Body Object Relationships

| Title | Type | Description |
| --- | --- | --- |
| country | [Country Object](../../coverage-resources/countries/country-object.html#country-object-v35) | Specifies the country for identity. Required when `vat_id` is set. |
| birth\_country | [Country Object](../../coverage-resources/countries/country-object.html#country-object-v35) | 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

Create Personal IdentityCreate Personal Identity with Country and Birth CountryCreate Business Identity

[[DIDWW-API-EXAMPLE-START]]

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}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

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    "relationships": {
23      "country": {
24        "data": {
25          "id": "c8647639-fc9c-47b2-acec-7c9e14465c25",
26          "type": "countries"
27        }
28      },
29      "birth_country": {
30        "data": {
31          "id": "c8647639-fc9c-47b2-acec-7c9e14465c25",
32          "type": "countries"
33        }
34      }
35    }
36  }
37}
```

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"}, "relationships": {"birth_country": {"data": {"id": "c8647639-fc9c-47b2-acec-7c9e14465c25", "type": "countries"}}, "country": {"data": {"id": "c8647639-fc9c-47b2-acec-7c9e14465c25", "type": "countries"}}}, "type": "identities"}}'
```

response

```
 1HTTP/1.1 201 Created
 2Content-Type: application/vnd.api+json
 3
 4{
 5    "data": {
 6        "id": "874390d1-ea6f-47c0-8d30-c9baaaeebdd9",
 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": "2023-01-31T09:23:10.406Z",
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/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/relationships/country",
30                    "related": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/country"
31                }
32            },
33            "birth_country": {
34                "links": {
35                    "self": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/relationships/birth_country",
36                    "related": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/birth_country"
37                }
38            },
39            "proofs": {
40                "links": {
41                    "self": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/relationships/proofs",
42                    "related": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/proofs"
43                }
44            },
45            "addresses": {
46                "links": {
47                    "self": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/relationships/addresses",
48                    "related": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/addresses"
49                }
50            },
51            "permanent_documents": {
52                "links": {
53                    "self": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/relationships/permanent_documents",
54                    "related": "https://api.didww.com/v3/identities/874390d1-ea6f-47c0-8d30-c9baaaeebdd9/permanent_documents"
55                }
56            }
57        }
58    },
59    "meta": {
60        "api_version": "2026-11-19"
61    }
62}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

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      "id_number": "string",
15      "birth_date": "1990-01-01",
16      "company_name": "string",
17      "company_website": "https://example.com",
18      "company_reg_number": "string",
19      "vat_id": null,
20      "description": "string",
21      "personal_tax_id": "string",
22      "external_reference_id": "string",
23      "identity_type": "business",
24      "contact_email": "jane@example.com"
25    },
26    "relationships": {
27      "country": {
28        "data": {
29          "id": "6d0effab-3fe3-4e07-acc6-1d3ddc717ebc",
30          "type": "countries"
31        }
32      },
33      "birth_country": {
34        "data": {
35          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
36          "type": "countries"
37        }
38      }
39    }
40  }
41}
```

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": "1990-01-01", "company_name": "string", "company_reg_number": "string", "company_website": "https://example.com", "contact_email": "jane@example.com", "description": "string", "external_reference_id": "string", "first_name": "string", "id_number": "string", "identity_type": "business", "last_name": "string", "personal_tax_id": "string", "phone_number": "35319015266", "vat_id": null}, "relationships": {"birth_country": {"data": {"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "type": "countries"}}, "country": {"data": {"id": "6d0effab-3fe3-4e07-acc6-1d3ddc717ebc", "type": "countries"}}}, "type": "identities"}}'
```

response

```
 1HTTP/1.1 201 Created
 2Content-Type: application/vnd.api+json
 3
 4{
 5  "data": {
 6    "id": "fb7f3f67-014c-496b-b918-f874f2689a40",
 7    "type": "identities",
 8    "attributes": {
 9      "first_name": "string",
10      "last_name": "string",
11      "phone_number": "35319015266",
12      "id_number": "string",
13      "birth_date": "1990-01-01",
14      "company_name": "string",
15      "company_website": "https://example.com",
16      "company_reg_number": "string",
17      "vat_id": null,
18      "description": "string",
19      "personal_tax_id": "string",
20      "identity_type": "business",
21      "created_at": "2021-03-22T12:08:29.987Z",
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/fb7f3f67-014c-496b-b918-f874f2689a40/relationships/country",
30          "related": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/country"
31        }
32      },
33      "birth_country": {
34        "links": {
35          "self": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/relationships/birth_country",
36          "related": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/birth_country"
37        }
38      },
39      "proofs": {
40        "links": {
41          "self": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/relationships/proofs",
42          "related": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/proofs"
43        }
44      },
45      "addresses": {
46        "links": {
47          "self": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/relationships/addresses",
48          "related": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/addresses"
49        }
50      },
51      "permanent_documents": {
52        "links": {
53          "self": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/relationships/permanent_documents",
54          "related": "https://api.didww.com/v3/identities/fb7f3f67-014c-496b-b918-f874f2689a40/permanent_documents"
55        }
56      }
57    }
58  },
59  "meta": {
60    "api_version": "2026-11-19"
61  }
62}
```

[[DIDWW-API-EXAMPLE-END]]

## Other Responses

| Code | Success | Description |
| --- | --- | --- |
| 400 | No | [Bad Request](../../../specification/errors/index.html#api-bad-request). The body carries a member the API does not accept. |
| 401 | No | [Unauthorized](../../authentication.html#authentication-v35) |
| 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](../../authentication.html#authentication-scopes-v35). |
| 422 | No | [Validation error](../../../specification/errors/index.html#api-validation-error-object). 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. |
