# 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` ### URI Query Parameters ### 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-v34) 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-v34) | Specifies the ID of DID for verification task. | | addresses | [Addresses](../addresses/address-object.html#addresses-object-v34) | Specifies the ID of Address for verification task. | | onetime\_files | [Encrypted Files Object](../encrypted-files/encrypted-files-object.html#encrypted-files-object-v34) | 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-v34), 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 ``` POST /v3/address_verifications HTTP/1.1 Host: api.didww.com Content-Type: application/vnd.api+json Accept: application/vnd.api+json Api-Key: [API token] { "data": { "type": "address_verifications", "attributes": { "callback_url": "http://example.com", "callback_method": "get" }, "relationships": { "dids": { "data": [ { "id": "b0c54164-03b9-42fa-b052-68a95bdab67b", "type": "dids" }, { "id": "95e9d153-4881-4a6a-85a0-9b9e68f817eb", "type": "dids" } ] }, "address": { "data": { "id": "a1f03dae-ea44-4348-993f-ce1c68ca1c21", "type": "addresses" } } } } } ``` curl ``` curl -i -X POST https://api.didww.com/v3/address_verifications -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --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 ``` HTTP/1.1 201 Created Content-Type: application/vnd.api+json { "data": { "id": "b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6", "type": "address_verifications", "attributes": { "service_description": null, "callback_url": "http://example.com", "callback_method": "get", "status": "pending", "reject_reasons": [], "reject_comment": null, "reference": "TTC-388920", "created_at": "2023-02-27T09:01:04.275Z", "external_reference_id": null }, "relationships": { "dids": { "links": { "self": "https://sandbox-api.didww.com/v3/address_verifications/b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6/relationships/dids", "related": "https://sandbox-api.didww.com/v3/address_verifications/b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6/dids" } }, "address": { "links": { "self": "https://sandbox-api.didww.com/v3/address_verifications/b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6/relationships/address", "related": "https://sandbox-api.didww.com/v3/address_verifications/b2f40660-2cdb-4ed6-98e0-2a7c23c0bce6/address" } } } }, "meta": { "api_version": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] [[DIDWW-API-EXAMPLE-START]] http ``` POST /v3/address_verifications HTTP/1.1 Host: api.didww.com Content-Type: application/vnd.api+json Accept: application/vnd.api+json Api-Key: [API token] { "data": { "type": "address_verifications", "attributes": { "callback_url": "http://example.com", "callback_method": "get", "service_description": "string" }, "relationships": { "onetime_files": { "data": [ { "id": "96fb69e0-d5bb-4637-b740-28349f1a4274", "type": "encrypted_files" } ] }, "dids": { "data": [ { "id": "723ba6a6-ec10-45f5-b2ba-84be6a4e0eb2", "type": "dids" } ] }, "address": { "data": { "id": "f13240d5-d3cc-4c05-a529-fb63a0027118", "type": "addresses" } } } } } ``` curl ``` curl -i -X POST https://api.didww.com/v3/address_verifications -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --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 ``` HTTP/1.1 201 Created Content-Type: application/vnd.api+json { "data": { "id": "89c0164e-752f-4995-a0fa-0ced21e60e4a", "type": "address_verifications", "attributes": { "service_description": "string", "callback_url": "http://example.com", "callback_method": "get", "status": "pending", "reject_reasons": [], "reject_comment": null, "created_at": "2021-03-23T12:20:04.584Z", "reference": "SHB-485120", "external_reference_id": null }, "relationships": { "dids": { "links": { "self": "https://sandbox-api.didww.com/v3/address_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/dids", "related": "https://sandbox-api.didww.com/v3/address_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/dids" } }, "address": { "links": { "self": "https://sandbox-api.didww.com/v3/address_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/relationships/address", "related": "https://sandbox-api.didww.com/v3/address_verifications/89c0164e-752f-4995-a0fa-0ced21e60e4a/address" } } } }, "meta": { "api_version": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] [[DIDWW-API-EXAMPLE-START]] http ``` POST /v3/address_verifications HTTP/1.1 Host: api.didww.com Content-Type: application/vnd.api+json Accept: application/vnd.api+json Api-Key: [API token] { "data": { "type": "address_verifications", "attributes": { "callback_url": "http://example.com", "callback_method": "get", "service_description": "string" }, "relationships": { "onetime_files": { "data": [ { "id": "606911e3-ae91-4717-8d16-39d85de906fc", "type": "encrypted_files" } ] }, "dids": { "data": [ { "id": "e750ea2f-b1a0-4cf7-887d-0cab23ee4138", "type": "dids" } ] }, "address": { "data": { "id": "ef8bedc8-4e2a-4064-b2b2-e08270eabe1b", "type": "addresses" } } } } } ``` curl ``` curl -i -X POST https://api.didww.com/v3/address_verifications -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --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 ``` HTTP/1.1 422 Unprocessable Entity Content-Type: application/vnd.api+json {"errors": [ { "title": "one-time document is not needed", "detail": "one-time document is not needed", "code": "100", "source": {"pointer": "/data"}, "status": "422" }, { "title": "service description is not needed", "detail": "service description is not needed", "code": "100", "source": {"pointer": "/data"}, "status": "422" } ]} ``` [[DIDWW-API-EXAMPLE-END]] [[DIDWW-API-EXAMPLE-START]] http ``` POST /v3/address_verifications HTTP/1.1 Host: api.didww.com Content-Type: application/vnd.api+json Accept: application/vnd.api+json Api-Key: [API token] { "data": { "type": "address_verifications", "attributes": { "callback_url": "http://example.com", "callback_method": "get" }, "relationships": { "dids": { "data": [ { "id": "dd769be0-d5ef-4c6f-b000-89cd2a780d7f", "type": "dids" } ] }, "address": { "data": { "id": "4f97a28d-d8be-4c00-bf72-df175e4d44c3", "type": "addresses" } } } } } ``` curl ``` curl -i -X POST https://api.didww.com/v3/address_verifications -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --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 ``` HTTP/1.1 422 Unprocessable Entity Content-Type: application/vnd.api+json {"errors": [ { "title": "1 Identity Proof(s) (National ID, Passport) required", "detail": "1 Identity Proof(s) (National ID, Passport) required", "code": "100", "source": {"pointer": "/data"}, "status": "422" }, { "title": "Following Supporting Document(s) required (Germany Registration Form)", "detail": "Following Supporting Document(s) required (Germany Registration Form)", "code": "100", "source": {"pointer": "/data"}, "status": "422" }, { "title": "1 Address Proof(s) (Copy of Phone Bill, Utility Bill, Rental Receipt, Other) required", "detail": "1 Address Proof(s) (Copy of Phone Bill, Utility Bill, Rental Receipt, Other) required", "code": "100", "source": {"pointer": "/data"}, "status": "422" } ]} ``` [[DIDWW-API-EXAMPLE-END]] [[DIDWW-API-EXAMPLE-START]] http ``` POST /v3/address_verifications HTTP/1.1 Host: api.didww.com Content-Type: application/vnd.api+json Accept: application/vnd.api+json Api-Key: [API token] { "data": { "type": "address_verifications", "attributes": { "callback_url": "http://example.com", "callback_method": "get" }, "relationships": { "dids": { "data": [ { "id": "a2eca370-0873-4b2e-b58b-3216ad3db98c", "type": "dids" } ] }, "address": { "data": { "id": "1703ec4d-2fc8-4965-b7d3-3645a2e90fac", "type": "addresses" } } } } } ``` curl ``` curl -i -X POST https://api.didww.com/v3/address_verifications -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --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 ``` HTTP/1.1 422 Unprocessable Entity Content-Type: application/vnd.api+json { "errors": [ { "title": "Following mandatory fields are not filled in (Contact Email)", "detail": "Following mandatory fields are not filled in (Contact Email)", "code": "100", "source": { "pointer": "/data" }, "status": "422" } ] } ``` [[DIDWW-API-EXAMPLE-END]] ## Other Responses | Code | Success | Description | | --- | --- | --- | | 404 | No | [Not Found](../../../specification/errors/index.html#api-not-found) | | 401 | No | [Unauthorized](../../../configuration.html#api-key) | On this page