# Get Identities

Returns a list of Identities on your account.

## Request

HTTP Method: `GET`

URI Path: `/v3/identities`

Note

For all returned data attributes, see [Identity Object](identity-object.html).

### URI Query Parameters

| Name | Type | Is Required? | Description |
| --- | --- | --- | --- |
| include | `string` | No | [Inclusion](../../../specification/includes.html#api-includes) |
| filter[<filter\_name>] | `string`, `date` | No | [Filtering](../../../specification/filtering.html#api-filters) |
| fields[identities] | `string` | No | [Sparse fieldsets](../../../specification/sparse-fieldsets.html#api-sparse-fieldsets) |
| sort | `string` | No | [Sorting](../../../specification/sorting.html#api-sorting) |
| page[number] | `integer` | No | [Page number](../../../specification/pagination.html#api-pagination). |
| page[size] | `integer` | No | [Page size](../../../specification/pagination.html#api-pagination). Pagination defaults to `50` records per page. The maximum is `100`. |

### Includes

| Value | Description |
| --- | --- |
| country | [Country Object](../../coverage-resources/countries/country-object.html#country-object-v35) |
| birth\_country | [Country Object](../../coverage-resources/countries/country-object.html#country-object-v35) |
| proofs | [Proofs Object](../proofs/proofs-object.html#proofs-object-v35) |
| addresses | [Addresses Object](../addresses/address-object.html#addresses-object-v35) |
| addresses.country | [Country Object](../../coverage-resources/countries/country-object.html#country-object-v35) |
| proofs.proof\_type | [Proof Types Object](../proof-types/proof-types-object.html#proof-types-object-v35) |
| permanent\_documents | [Permanent Documents Object](../permanent-documents/permanent-documents-object.html#permanent-documents-object-v35) |
| permanent\_documents.template | [Supporting Document Template Object](../supporting-document-templates/supporting-document-templates-object.html#supporting-document-templates-object-v35) |

### Filters

| Filter Name | Type | Allow Blank | Allow Array | Filters by: |
| --- | --- | --- | --- | --- |
| id | `string` | No | Yes | The `id` field. |
| first\_name | `string` | Yes | No | The `first_name` field. |
| first\_name\_contains | `string` | Yes | No | The `first_name_contains` field. |
| last\_name | `string` | Yes | No | The `last_name` field. |
| last\_name\_contains | `string` | Yes | No | The `last_name_contains` field. |
| phone\_number | `string` | Yes | No | The `phone_number` field. |
| phone\_number\_contains | `string` | Yes | No | The `phone_number_contains` field. |
| id\_number | `string` | Yes | No | The `id_number` field. |
| id\_number\_contains | `string` | Yes | No | The `id_number_contains` field. |
| birth\_date | `date` | No | No | The `birth_date` field. |
| company\_name | `string` | Yes | No | The `company_name` field. |
| company\_name\_contains | `string` | Yes | No | The `company_name_contains` field. |
| company\_website | `string` | Yes | No | The `company_website` field (exact match). |
| company\_website\_contains | `string` | Yes | No | The `company_website_contains` field. |
| company\_reg\_number | `string` | Yes | No | The `company_reg_number` field. |
| company\_reg\_number\_contains | `string` | Yes | No | The `company_reg_number_contains` field. |
| vat\_id | `string` | Yes | No | The `vat_id` field. |
| vat\_id\_contains | `string` | Yes | No | The `vat_id_contains` field. |
| description | `string` | Yes | No | The `description` field. |
| description\_contains | `string` | Yes | No | The `description_contains` field. |
| personal\_tax\_id | `string` | Yes | No | The `personal_tax_id` field. |
| personal\_tax\_id\_contains | `string` | Yes | No | The `personal_tax_id_contains` field. |
| identity\_type | `string` | No | No | The `identity_type` field. Possible values: `personal`, `business`. |
| country.id | `string` | No | Yes | The `country.id` field. |
| external\_reference\_id | `string` | No | No | The `external_reference_id` field. |

### Sorting

| Value | Sorts by: |
| --- | --- |
| first\_name | The `first_name` field. |
| last\_name | The `last_name` field. |
| phone\_number | The `phone_number` field. |
| id\_number | The `id_number` field. |
| birth\_date | The `birth_date` field. |
| company\_name | The `company_name` field. |
| company\_website | The `company_website` field. |
| company\_reg\_number | The `company_reg_number` field. |
| vat\_id | The `vat_id` field. |
| description | The `description` field. |
| personal\_tax\_id | The `personal_tax_id` field. |
| contact\_email | The `contact_email` field. |
| created\_at | The `created_at` field. |
| verified | The `verified` field. |
| external\_reference\_id | The `external_reference_id` field. |

## Examples

Simple RequestFilter first\_name\_containsInclude country

[[DIDWW-API-EXAMPLE-START]]

http

```
1GET /v3/identities HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
```

curl

```
1curl -i -X GET https://api.didww.com/v3/identities -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]"
```

response

```
 1HTTP/1.1 200 OK
 2Content-Type: application/vnd.api+json
 3
 4        {
 5            "data": [
 6                {
 7                    "id": "0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c",
 8                    "type": "identities",
 9                    "attributes": {
10                        "first_name": "Jane",
11                        "last_name": "Smith",
12                        "phone_number": "35319015266",
13                        "id_number": "0000000000",
14                        "birth_date": "2000-01-01",
15                        "company_name": null,
16                        "company_website": null,
17                        "company_reg_number": null,
18                        "vat_id": null,
19                        "description": "Personal details",
20                        "personal_tax_id": null,
21                        "identity_type": "personal",
22                        "created_at": "2020-09-14T07:29:41.393Z",
23                        "external_reference_id": null,
24                        "verified": false,
25                        "contact_email": "contact@email.com"
26                    },
27                    "relationships": {
28                        "country": {
29                            "links": {
30                                "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/country",
31                                "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/country"
32                            }
33                        },
34                        "birth_country": {
35                            "links": {
36                                "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/birth_country",
37                                "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/birth_country"
38                            }
39                        },
40                        "proofs": {
41                            "links": {
42                                "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/proofs",
43                                "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/proofs"
44                            }
45                        },
46                        "addresses": {
47                            "links": {
48                                "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/addresses",
49                                "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/addresses"
50                            }
51                        },
52                        "permanent_documents": {
53                            "links": {
54                                "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/permanent_documents",
55                                "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/permanent_documents"
56                            }
57                        }
58                    }
59                }
60            ],
61            "meta": {
62                "total_records": 4,
63                "api_version": "2026-11-19"
64            },
65            "links": {
66                "first": "https://api.didww.com/v3/identities?page%5Bnumber%5D=1&page%5Bsize%5D=50",
67                "last": "https://api.didww.com/v3/identities?page%5Bnumber%5D=1&page%5Bsize%5D=50"
68            }
69        }
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
1GET /v3/identities?filter%5Bfirst_name_contains%5D=Jane HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
```

curl

```
1curl -i -X GET 'https://api.didww.com/v3/identities?filter%5Bfirst_name_contains%5D=Jane' -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]"
```

response

```
 1HTTP/1.1 200 OK
 2Content-Type: application/vnd.api+json
 3
 4        {
 5            "data": [
 6                {
 7                    "id": "0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c",
 8                    "type": "identities",
 9                    "attributes": {
10                        "first_name": "Jane",
11                        "last_name": "Smith",
12                        "phone_number": "35319015266",
13                        "id_number": "0000000000",
14                        "birth_date": "2000-01-01",
15                        "company_name": null,
16                        "company_website": null,
17                        "company_reg_number": null,
18                        "vat_id": null,
19                        "description": "Personal details",
20                        "personal_tax_id": null,
21                        "identity_type": "personal",
22                        "created_at": "2020-09-14T07:29:41.393Z",
23                        "external_reference_id": null,
24                        "verified": false,
25                        "contact_email": "contact@email.com"
26                    },
27                    "relationships": {
28                        "country": {
29                            "links": {
30                                "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/country",
31                                "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/country"
32                            }
33                        },
34                        "birth_country": {
35                            "links": {
36                                "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/birth_country",
37                                "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/birth_country"
38                            }
39                        },
40                        "proofs": {
41                            "links": {
42                                "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/proofs",
43                                "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/proofs"
44                            }
45                        },
46                        "addresses": {
47                            "links": {
48                                "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/addresses",
49                                "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/addresses"
50                            }
51                        },
52                        "permanent_documents": {
53                            "links": {
54                                "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/permanent_documents",
55                                "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/permanent_documents"
56                            }
57                        }
58                    }
59                }
60            ],
61            "meta": {
62                "total_records": 4,
63                "api_version": "2026-11-19"
64            },
65            "links": {
66                "first": "https://api.didww.com/v3/identities?filter%5Bfirst_name_contains%5D=Jane&page%5Bnumber%5D=1&page%5Bsize%5D=50",
67                "last": "https://api.didww.com/v3/identities?filter%5Bfirst_name_contains%5D=Jane&page%5Bnumber%5D=1&page%5Bsize%5D=50"
68            }
69        }
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
1GET /v3/identities?include=country HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
```

curl

```
1curl -i -X GET 'https://api.didww.com/v3/identities?include=country' -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]"
```

response

```
 1HTTP/1.1 200 OK
 2Content-Type: application/vnd.api+json
 3
 4        {
 5            "data": [
 6                {
 7                    "id": "0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c",
 8                    "type": "identities",
 9                    "attributes": {
10                        "first_name": "Jane",
11                        "last_name": "Smith",
12                        "phone_number": "35319015266",
13                        "id_number": "0000000000",
14                        "birth_date": "2000-01-01",
15                        "company_name": null,
16                        "company_website": null,
17                        "company_reg_number": null,
18                        "vat_id": null,
19                        "description": "Personal details",
20                        "personal_tax_id": null,
21                        "identity_type": "personal",
22                        "created_at": "2020-09-14T07:29:41.393Z",
23                        "external_reference_id": null,
24                        "verified": false,
25                        "contact_email": "contact@email.com"
26                    },
27          "relationships":{
28             "country":{
29                "links":{
30                   "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/country",
31                   "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/country"
32                },
33                "data":{
34                   "type": "countries",
35                   "id": "683c77a5-fcb0-48a0-8501-4de6284a2889"
36                }
37             },
38             "birth_country":{
39                "links":{
40                   "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/birth_country",
41                   "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/birth_country"
42                }
43             },
44             "proofs": {"links":{
45                "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/proofs",
46                "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/proofs"
47             }},
48             "addresses": {"links":{
49                "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/addresses",
50                "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/addresses"
51             }},
52             "permanent_documents": {"links":{
53                "self": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/relationships/permanent_documents",
54                "related": "https://api.didww.com/v3/identities/0c95a4c3-c5e6-4ea0-a8ba-bfb65850913c/permanent_documents"
55             }}
56          }
57       }],
58       "included": [{
59          "id": "683c77a5-fcb0-48a0-8501-4de6284a2889",
60          "type": "countries",
61          "attributes":{
62             "name": "Lithuania",
63             "prefix": "370",
64             "iso": "LT"
65          },
66          "relationships": {"regions": {"links":{
67             "self": "https://api.didww.com/v3/countries/683c77a5-fcb0-48a0-8501-4de6284a2889/relationships/regions",
68             "related": "https://api.didww.com/v3/countries/683c77a5-fcb0-48a0-8501-4de6284a2889/regions"
69          }}}
70       }],
71       "meta":    {
72          "total_records": 1,
73          "api_version": "2026-11-19"
74       },
75       "links":    {
76          "first": "https://api.didww.com/v3/identities?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50",
77          "last": "https://api.didww.com/v3/identities?include=country&page%5Bnumber%5D=1&page%5Bsize%5D=50"
78       }
79    }
```

[[DIDWW-API-EXAMPLE-END]]

## Other Responses

| Code | Success | Description |
| --- | --- | --- |
| 400 | No | [Bad Request](../../../specification/errors/index.html#api-bad-request). Malformed request: unknown filter, bad pagination or bad sort field. |
| 401 | No | [Unauthorized](../../authentication.html#authentication-v35) |
| 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. |
