# Create Address Verification

Creates an Address Verification task and configures a callback to receive status updates.
Supports linking DIDs, addresses, and optional supporting files.

## Request

HTTP Method: `POST`

URI Path: `/v3/address_verifications`

### Request Body Object Attributes

| Name | Type | Is Required? | Description |
| --- | --- | --- | --- |
| service\_description | `string` | No | The description of verification task. |
| external\_reference\_id | `string` | No | Optional identifier for the verification task in the customer's external system. Maximum length is 100 characters. |
| callback\_url | `string` | No | The HTTP or HTTPS endpoint to where events related to verification task will be delivered. |
| callback\_method | `string` | No | The HTTP Method used for verification task events. `post` and `get` are supported methods. |

See [Address Verification callback details](../../callbacks-details.html#callbacks-address-verification-v35) for
information about `callback_url`, `callback_method`, and the callback payload.

### Request Body Object Relationships

| Title | Type | Description |
| --- | --- | --- |
| dids | [DID](../../inventory-resources/did/did-object.html#did-object-v35) | Specifies the ID of DID for verification task. |
| address | [Addresses](../addresses/address-object.html#addresses-object-v35) | Specifies the ID of Address for verification task. |
| onetime\_files | [Encrypted Files Object](../encrypted-files/encrypted-files-object.html#encrypted-files-object-v35) | Specifies Onetime files for verification task. |

## Testing

Confirm the correct functioning of your integration by simulating approvals and rejections in the **sandbox**
environment.
This can be achieved by assigning specific testing values to the **id\_number** attribute of the
[Identity](../identities/identity-object.html#identity-object-v35), which will be utilized when creating the Address
Verification.
Refer to the table below for the available options.

| Action | id\_number value |
| --- | --- |
| approve | 11111111-1111-1111-1111-111111111111 |
| reject | 22222222-2222-2222-2222-222222222222 |

## Examples

Create Address VerificationCreate Address Verification with Service DescriptionVerification ErrorVerification Error:
Missing proofsVerification Error: Missing mandatory fields

[[DIDWW-API-EXAMPLE-START]]

http

```
 1POST /v3/address_verifications 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": "address_verifications",
10    "attributes": {
11      "callback_url": "http://example.com",
12      "callback_method": "get"
13    },
14    "relationships": {
15      "dids": {
16        "data": [
17          {
18            "id": "b0c54164-03b9-42fa-b052-68a95bdab67b",
19            "type": "dids"
20          },
21          {
22            "id": "95e9d153-4881-4a6a-85a0-9b9e68f817eb",
23            "type": "dids"
24          }
25        ]
26      },
27      "address": {
28        "data": {
29          "id": "a1f03dae-ea44-4348-993f-ce1c68ca1c21",
30          "type": "addresses"
31        }
32      }
33    }
34  }
35}
```

curl

```
1curl -i -X POST https://api.didww.com/v3/address_verifications -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"callback_method": "get", "callback_url": "http://example.com"}, "relationships": {"address": {"data": {"id": "a1f03dae-ea44-4348-993f-ce1c68ca1c21", "type": "addresses"}}, "dids": {"data": [{"id": "b0c54164-03b9-42fa-b052-68a95bdab67b", "type": "dids"}, {"id": "95e9d153-4881-4a6a-85a0-9b9e68f817eb", "type": "dids"}]}}, "type": "address_verifications"}}'
```

response

```
 1HTTP/1.1 201 Created
 2Content-Type: application/vnd.api+json
 3
 4{
 5    "data": {
 6        "id": "b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6",
 7        "type": "address_verifications",
 8        "attributes": {
 9            "service_description": null,
10            "callback_url": "http://example.com",
11            "callback_method": "get",
12            "status": "pending",
13            "reject_reasons": null,
14            "reject_comment": null,
15            "reference": "TTC-388920",
16            "created_at": "2023-02-27T09:01:04.275Z",
17            "external_reference_id": null
18        },
19        "relationships": {
20            "dids": {
21                "links": {
22                    "self": "https://api.didww.com/v3/address_verifications/b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6/relationships/dids",
23                    "related": "https://api.didww.com/v3/address_verifications/b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6/dids"
24                }
25            },
26            "address": {
27                "links": {
28                    "self": "https://api.didww.com/v3/address_verifications/b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6/relationships/address",
29                    "related": "https://api.didww.com/v3/address_verifications/b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6/address"
30                }
31            }
32        }
33    },
34    "meta": {
35        "api_version": "2026-11-19"
36    }
37}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
 1POST /v3/address_verifications 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": "address_verifications",
10    "attributes": {
11    "callback_url": "http://example.com",
12    "callback_method": "get",
13    "service_description": "string"
14    },
15    "relationships": {
16      "onetime_files": {
17        "data": [
18          {
19            "id": "96fb69e0-d5bb-4637-b740-28349f1a4274",
20            "type": "encrypted_files"
21          }
22        ]
23      },
24      "dids": {
25        "data": [
26          {
27            "id": "723ba6a6-ec10-45f5-b2ba-84be6a4e0eb2",
28            "type": "dids"
29          }
30        ]
31      },
32      "address": {
33        "data": {
34          "id": "f13240d5-d3cc-4c05-a529-fb63a0027118",
35          "type": "addresses"
36        }
37      }
38    }
39  }
40}
```

curl

```
1curl -i -X POST https://api.didww.com/v3/address_verifications -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"callback_method": "get", "callback_url": "http://example.com", "service_description": "string"}, "relationships": {"address": {"data": {"id": "f13240d5-d3cc-4c05-a529-fb63a0027118", "type": "addresses"}}, "dids": {"data": [{"id": "723ba6a6-ec10-45f5-b2ba-84be6a4e0eb2", "type": "dids"}]}, "onetime_files": {"data": [{"id": "96fb69e0-d5bb-4637-b740-28349f1a4274", "type": "encrypted_files"}]}}, "type": "address_verifications"}}'
```

response

```
 1HTTP/1.1 201 Created
 2Content-Type: application/vnd.api+json
 3
 4{
 5  "data": {
 6    "id": "89c0164e-752f-4995-a0fa-0ced21e60e4a",
 7    "type": "address_verifications",
 8    "attributes": {
 9      "service_description": "string",
10      "callback_url": "http://example.com",
11      "callback_method": "get",
12      "status": "pending",
13      "reject_reasons": null,
14      "reject_comment": null,
15      "created_at": "2021-03-23T12:20:04.584Z",
16      "reference": "SHB-485120",
17      "external_reference_id": null
18    },
19    "relationships": {
20      "dids": {
21        "links": {
22          "self": "https://api.didww.com/v3/address_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/dids",
23          "related": "https://api.didww.com/v3/address_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/dids"
24        }
25      },
26      "address": {
27        "links": {
28          "self": "https://api.didww.com/v3/address_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/address",
29          "related": "https://api.didww.com/v3/address_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/address"
30        }
31      }
32    }
33  },
34  "meta": {
35    "api_version": "2026-11-19"
36  }
37}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
 1POST /v3/address_verifications 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": "address_verifications",
10        "attributes": {
11        "callback_url": "http://example.com",
12        "callback_method": "get",
13        "service_description": "string"
14        },
15        "relationships": {
16          "onetime_files": {
17                "data": [
18                  {
19                        "id": "606911e3-ae91-4717-8d16-39d85de906fc",
20                        "type": "encrypted_files"
21                  }
22                ]
23          },
24          "dids": {
25                "data": [
26                  {
27                        "id": "e750ea2f-b1a0-4cf7-887d-0cab23ee4138",
28                        "type": "dids"
29                  }
30                ]
31          },
32          "address": {
33                "data": {
34                  "id": "ef8bedc8-4e2a-4064-b2b2-e08270eabe1b",
35                  "type": "addresses"
36                }
37          }
38        }
39  }
40}
```

curl

```
1curl -i -X POST https://api.didww.com/v3/address_verifications -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"callback_method": "get", "callback_url": "http://example.com", "service_description": "string"}, "relationships": {"address": {"data": {"id": "ef8bedc8-4e2a-4064-b2b2-e08270eabe1b", "type": "addresses"}}, "dids": {"data": [{"id": "e750ea2f-b1a0-4cf7-887d-0cab23ee4138", "type": "dids"}]}, "onetime_files": {"data": [{"id": "606911e3-ae91-4717-8d16-39d85de906fc", "type": "encrypted_files"}]}}, "type": "address_verifications"}}'
```

response

```
 1HTTP/1.1 422 Unprocessable Entity
 2Content-Type: application/vnd.api+json
 3
 4{"errors": [
 5      {
 6      "title": "one-time document is not needed",
 7      "detail": "one-time document is not needed",
 8      "code": "100",
 9      "source": {"pointer": "/data"},
10      "status": "422"
11   },
12      {
13      "title": "service description is not needed",
14      "detail": "service description is not needed",
15      "code": "100",
16      "source": {"pointer": "/data"},
17      "status": "422"
18   }
19]}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
 1POST /v3/address_verifications 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": "address_verifications",
10    "attributes": {
11      "callback_url": "http://example.com",
12      "callback_method": "get"
13    },
14    "relationships": {
15      "dids": {
16        "data": [
17          {
18            "id": "dd769be0-d5ef-4c6f-b000-89cd2a780d7f",
19            "type": "dids"
20          }
21        ]
22      },
23      "address": {
24        "data": {
25          "id": "4f97a28d-d8be-4c00-bf72-df175e4d44c3",
26          "type": "addresses"
27        }
28      }
29    }
30  }
31}
```

curl

```
1curl -i -X POST https://api.didww.com/v3/address_verifications -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"callback_method": "get", "callback_url": "http://example.com"}, "relationships": {"address": {"data": {"id": "4f97a28d-d8be-4c00-bf72-df175e4d44c3", "type": "addresses"}}, "dids": {"data": [{"id": "dd769be0-d5ef-4c6f-b000-89cd2a780d7f", "type": "dids"}]}}, "type": "address_verifications"}}'
```

response

```
 1HTTP/1.1 422 Unprocessable Entity
 2Content-Type: application/vnd.api+json
 3
 4{"errors": [
 5      {
 6      "title": "1 Identity Proof(s) (National ID, Passport) required",
 7      "detail": "1 Identity Proof(s) (National ID, Passport) required",
 8      "code": "100",
 9      "source": {"pointer": "/data"},
10      "status": "422"
11   },
12      {
13      "title": "Following Supporting Document(s) required (Germany Registration Form)",
14      "detail": "Following Supporting Document(s) required (Germany Registration Form)",
15      "code": "100",
16      "source": {"pointer": "/data"},
17      "status": "422"
18   },
19      {
20      "title": "1 Address Proof(s) (Copy of Phone Bill, Utility Bill, Rental Receipt, Other) required",
21      "detail": "1 Address Proof(s) (Copy of Phone Bill, Utility Bill, Rental Receipt, Other) required",
22      "code": "100",
23      "source": {"pointer": "/data"},
24      "status": "422"
25   }
26]}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
 1POST /v3/address_verifications 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": "address_verifications",
10    "attributes": {
11      "callback_url": "http://example.com",
12      "callback_method": "get"
13    },
14    "relationships": {
15      "dids": {
16        "data": [
17          {
18            "id": "a2eca370-0873-4b2e-b58b-3216ad3db98c",
19            "type": "dids"
20          }
21        ]
22      },
23      "address": {
24        "data": {
25          "id": "1703ec4d-2fc8-4965-b7d3-3645a2e90fac",
26          "type": "addresses"
27        }
28      }
29    }
30  }
31}
```

curl

```
1curl -i -X POST https://api.didww.com/v3/address_verifications -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"callback_method": "get", "callback_url": "http://example.com"}, "relationships": {"address": {"data": {"id": "1703ec4d-2fc8-4965-b7d3-3645a2e90fac", "type": "addresses"}}, "dids": {"data": [{"id": "a2eca370-0873-4b2e-b58b-3216ad3db98c", "type": "dids"}]}}, "type": "address_verifications"}}'
```

response

```
 1HTTP/1.1 422 Unprocessable Entity
 2Content-Type: application/vnd.api+json
 3
 4{
 5    "errors": [
 6        {
 7            "title": "Following mandatory fields are not filled in (Contact Email)",
 8            "detail": "Following mandatory fields are not filled in (Contact Email)",
 9            "code": "100",
10            "source": {
11                "pointer": "/data"
12            },
13            "status": "422"
14        }
15    ]
16}
```

[[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 Object](../../../specification/errors/index.html#api-validation-error-object). The submission 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. |
