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 for information about callback_url, callback_method, and the callback payload.

Request Body Object Relationships#

Title

Type

Description

dids

DID

Specifies the ID of DID for verification task.

address

Addresses

Specifies the ID of Address for verification task.

onetime_files

Encrypted Files Object

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, 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#

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}

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