Buy a DID Number That Requires Verification
This example shows the end-to-end process for purchasing a DID number that is subject to regulatory verification requirements and completing the verification flow required to activate it.
Certain DID numbers require end-user registration based on country, number type, or applicable regulatory rules. When registration applies, additional information such as an identity, address, proofs, and supporting documents must be collected, validated, and submitted before the DID can be activated.
The flow outlined below covers discovering available numbers and registration requirements, collecting and validating end-user data, and initiating the verification process needed for DID activation.
To purchase a DID and complete the required verification flow, follow these steps:
Find the country ID.
Find the city ID (if applicable).
Retrieve DID availability, pricing, and registration requirements.
Create the DID order.
Retrieve the DID ID created by the order.
Retrieve and review the registration requirements.
Create an identity (personal or business), based on the requirement.
Create an address linked to the identity.
Encrypt and upload required documents using encrypted files (if required).
Create identity and/or address proofs.
Create a permanent supporting document (if required).
Validate the identity, address, and submitted documents against the requirement.
Assign the validated identity and address to the DID and start the verification process.
Note
The UUIDs shown in the examples below are for illustration purposes only.
Always execute requests in your own environment and use the actual UUIDs returned in API responses.
Step 1: Find the Country ID
Retrieve the unique ID for the target country using the /countries endpoint.
From the response, save the country.id for use in later steps (for example,
when retrieving requirements or building address data).
For more information, see the /v3/countries endpoint documentation.
Use this approach when your application already knows the target country
(for example, from a stored customer selection or a predefined checkout flow).
Filter by ISO code to retrieve the matching country and its country.id.
http
GET /v3/countries?filter%5Biso%5D=DE HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/countries?filter%5Biso%5D=DE' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "f711b8ee-7576-4d40-9dd4-f51a69cee8a7",
"type": "countries",
"attributes": {
"name": "Germany",
"prefix": "49",
"iso": "DE"
}
}
],
"meta": {
"api_version": "2022-05-10"
}
}
Note
This example filters by country ISO code. Adjust filters as needed to match your use case.
Use this approach when building a country dropdown for end users.
This request returns countries that have DID groups in coverage and DID numbers
available for purchase. You can sort the results by name and use each item’s
attributes.name for display and id as the selected country.id for
later steps.
filter[is_available] is a boolean filter:
When
true, returns countries with DID numbers available for purchase.When
false, returns countries that exist in coverage but currently have no DID numbers available for purchase.
http
GET /v3/countries?filter%5Bis_available%5D=true&sort=name HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/countries?filter%5Bis_available%5D=true&sort=name' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "7549be3c-1077-433d-9a77-25416373660d",
"type": "countries",
"attributes": {
"name": "Sweden",
"prefix": "46",
"iso": "SE"
}
},
{
"id": "24eb6e85-f628-4765-bbb2-420e48de76f2",
"type": "countries",
"attributes": {
"name": "Canada",
"prefix": "1",
"iso": "CA"
}
}
],
"meta": {
"api_version": "2022-05-10"
}
}
Step 2: Find the City ID
Depending on your application flow, selecting a city may be optional or required.
If your application allows users to narrow DID availability by city (for
example, when displaying a coverage list for local numbers), you should retrieve
and store the corresponding city.id.
If your application does not differentiate availability by city (for example, when listing all cities within a country or purchasing non–city-specific DIDs), this step can be skipped.
Use the saved country.id to retrieve the city where the DID will be purchased.
From the response, save the city.id for use in later steps when retrieving
DID Groups or building address data.
For more information, see the /v3/cities endpoint documentation.
http
GET /v3/cities?filter%5Bcountry.id%5D=f711b8ee-7576-4d40-9dd4-f51a69cee8a7&filter%5Bname%5D=Aachen HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/cities?filter%5Bcountry.id%5D=f711b8ee-7576-4d40-9dd4-f51a69cee8a7&filter%5Bname%5D=Aachen' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "bc7df5b9-3852-401c-b21d-8c8871efd86f",
"type": "cities",
"attributes": {
"name": "Aachen"
}
}
],
"meta": {
"total_records": 1,
"api_version": "2022-05-10"
}
}
Note
This example filters the response by a single city name. Adjust the request parameters as needed to match your use case.
Step 3: Retrieve DID Availability, Pricing, and Registration Requirements
This step uses the /did_groups endpoint, which is the primary source for
building DID number coverage and availability in your application.
It allows you to present end users with:
available DID number types (Local, Mobile, National, Toll-free)
supported prefixes and geographic areas
available features (such as voice and SMS)
pricing options and included channel options
whether regulatory registration is required before activation
Include stock_keeping_units and requirement in the request to obtain
the following information:
Stock Keeping Units (SKU) – Represents individual inventory units within the DID Group. Each SKU defines the price of the DID and the number of included channels.
Registration requirement – Indicates whether end-user registration is required for DIDs in this area. Optionally, the restriction message can be displayed to the user before purchase to inform them that additional details will be required to activate the number.
From the GET /did_groups response, save the following values:
stock_keeping_units.id– Required to create the DID order in the next step.requirement.id– Optional at this step. It can be used in later steps to validate identity and address information once the DID country and type are known and registration requirements apply (see Step 12: Validate Identity and Address Against Requirements).
For more information, see the /v3/did_groups endpoint documentation.
Use this approach when your flow narrows down availability by location (for example, after the user selects a country and a city/area). The response can be used to list purchasable DID Groups for that location and to determine whether registration is required before ordering.
http
GET /v3/did_groups?include=stock_keeping_units%2Crequirement&filter%5Bcity.id%5D=bc7df5b9-3852-401c-b21d-8c8871efd86f HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/did_groups?include=stock_keeping_units%2Crequirement&filter%5Bcity.id%5D=bc7df5b9-3852-401c-b21d-8c8871efd86f' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "16f7a8ea-cbfd-4429-8b94-995421d73814",
"type": "did_groups",
"attributes": {
"prefix": "3",
"features": [
"voice_in",
"sms_out"
],
"is_metered": false,
"area_name": "Aachen",
"allow_additional_channels": true
},
"relationships": {
"stock_keeping_units": {
"data": [
{
"type": "stock_keeping_units",
"id": "9438cb3c-8e82-4d48-8b66-ec995dc13132"
},
{
"type": "stock_keeping_units",
"id": "fedaec98-af1e-4441-bd7e-1c6668312ad5"
}
]
},
"requirement": {
"data": {
"type": "requirements",
"id": "c6f606d8-106a-43d6-997e-17c7da5ae5d7"
}
}
},
"meta": {
"needs_registration": true,
"is_available": true,
"total_count": 98
}
}
],
"included": [
{
"id": "9438cb3c-8e82-4d48-8b66-ec995dc13132",
"type": "stock_keeping_units",
"attributes": {
"setup_price": "5.0",
"monthly_price": "0.4",
"channels_included_count": 0
}
},
{
"id": "fedaec98-af1e-4441-bd7e-1c6668312ad5",
"type": "stock_keeping_units",
"attributes": {
"setup_price": "5.0",
"monthly_price": "2.1",
"channels_included_count": 2
}
},
{
"id": "c6f606d8-106a-43d6-997e-17c7da5ae5d7",
"type": "requirements",
"attributes": {
"identity_type": "Any",
"personal_area_level": "WorldWide",
"business_area_level": "WorldWide",
"address_area_level": "Area",
"personal_proof_qty": 1,
"business_proof_qty": 1,
"address_proof_qty": 0,
"personal_mandatory_fields": ["id_number"],
"business_mandatory_fields": ["vat_id"],
"service_description_required": false,
"restriction_message": "Germany Local DID End User registration requirements:\n\nFor personal identity verification:\n* Name, last name\n* Contact phone number\n* German passport or ID copy\n\nFor business identity verification:\n* Name, last name\n* Contact phone number\n* Company name\n* German company incorporation certificate copy\n\nFor address verification:\n* Address matching the DID area code\n* Utility bill (less than 6 months old)\n"
}
}
]
}
Use this approach when your UI begins with a country selection and presents available DID options, such as on a Buy Numbers page with filters by DID Group type and features.
By including country, region, DID Group type, SKUs, and requirement-related resources, your application can show registration conditions before purchase when applicable.
http
GET /v3/did_groups?filter%5Bcountry.id%5D=dfd1a0a0-bd53-4f7a-9c8e-d2fc5dd1bf7e&sort=area_name&include=country%2Cregion%2Cstock_keeping_units%2Cdid_group_type%2Crequirement%2Crequirement.personal_onetime_document%2Crequirement.business_onetime_document%2Crequirement.personal_permanent_document%2Crequirement.business_permanent_document HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/did_groups?filter%5Bcountry.id%5D=dfd1a0a0-bd53-4f7a-9c8e-d2fc5dd1bf7e&sort=area_name&include=country%2Cregion%2Cstock_keeping_units%2Cdid_group_type%2Crequirement%2Crequirement.personal_onetime_document%2Crequirement.business_onetime_document%2Crequirement.personal_permanent_document%2Crequirement.business_permanent_document' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "2187c36d-28fb-436f-8861-5a0f5b5a3ee1",
"type": "did_groups",
"attributes": {
"prefix": "241",
"features": [
"voice_in",
"t38"
],
"is_metered": false,
"area_name": "Aachen",
"allow_additional_channels": true
},
"relationships": {
"country": {
"data": {
"type": "countries",
"id": "dfd1a0a0-bd53-4f7a-9c8e-d2fc5dd1bf7e"
}
},
"did_group_type": {
"data": {
"type": "did_group_types",
"id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
}
},
"region": {
"data": null
},
"stock_keeping_units": {
"data": [
{
"type": "stock_keeping_units",
"id": "b98e368b-20d4-45e1-a7c3-319351b084fd"
},
{
"type": "stock_keeping_units",
"id": "63bab5b4-c65f-4412-bca1-5085f5318317"
}
]
},
"requirement": {
"data": {
"type": "requirements",
"id": "69903d6b-edf5-4dfb-8294-d39bf40e12b6"
}
}
},
"meta": {
"available_dids_enabled": false,
"needs_registration": true,
"is_available": true,
"total_count": 8
}
},
{
"id": "0b8e8c19-f3a8-4d90-a18f-657393703379",
"type": "did_groups",
"attributes": {
"prefix": "821",
"features": [
"voice_in",
"t38"
],
"is_metered": false,
"area_name": "Augsburg",
"allow_additional_channels": true
},
"relationships": {
"country": {
"data": {
"type": "countries",
"id": "dfd1a0a0-bd53-4f7a-9c8e-d2fc5dd1bf7e"
}
},
"did_group_type": {
"data": {
"type": "did_group_types",
"id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
}
},
"region": {
"data": null
},
"stock_keeping_units": {
"data": [
{
"type": "stock_keeping_units",
"id": "1a9c4d79-1306-455d-99c1-c5fd48abeae2"
},
{
"type": "stock_keeping_units",
"id": "b31df3bb-bd5d-4315-b7c0-08a4f865c029"
}
]
},
"requirement": {
"data": {
"type": "requirements",
"id": "69903d6b-edf5-4dfb-8294-d39bf40e12b6"
}
}
},
"meta": {
"available_dids_enabled": false,
"needs_registration": false,
"is_available": true,
"total_count": 11
}
}
],
"included": [
{
"id": "dfd1a0a0-bd53-4f7a-9c8e-d2fc5dd1bf7e",
"type": "countries",
"attributes": {
"name": "Germany",
"prefix": "49",
"iso": "DE"
}
},
{
"id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3",
"type": "did_group_types",
"attributes": {
"name": "Local"
}
},
{
"id": "2c165e9d-c6f5-4fe1-ad0e-bacf5bab3d86",
"type": "did_group_types",
"attributes": {
"name": "National"
}
},
{
"id": "b98e368b-20d4-45e1-a7c3-319351b084fd",
"type": "stock_keeping_units",
"attributes": {
"setup_price": "0.0",
"monthly_price": "0.8",
"channels_included_count": 0
}
},
{
"id": "63bab5b4-c65f-4412-bca1-5085f5318317",
"type": "stock_keeping_units",
"attributes": {
"setup_price": "0.0",
"monthly_price": "4.8",
"channels_included_count": 2
}
},
{
"id": "69903d6b-edf5-4dfb-8294-d39bf40e12b6",
"type": "requirements",
"attributes": {
"identity_type": "Any",
"personal_area_level": "Country",
"business_area_level": "Country",
"address_area_level": "City",
"personal_proof_qty": 2,
"business_proof_qty": 1,
"address_proof_qty": 1,
"personal_mandatory_fields": [
"country"
],
"business_mandatory_fields": [
"country"
],
"service_description_required": true,
"restriction_message": "German Local DID End User registration requirements:\r\n\r\nFor personal identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n* German passport or ID copy\r\n\r\nFor business identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name\r\n* German company incorporation certificate copy\r\n\r\nFor address verification:\r\n* Address matching: the DID area code, address in the certificate/ID (street, building number, postal code, city and country)\r\n* A copy of a utility bill (less than 6 months old)\r\n\r\n ."
}
},
{
"id": "94be4d74-c968-4d81-91c5-2d11b4e45328",
"type": "supporting_document_templates",
"attributes": {
"name": "LOI Example",
"permanent": false,
"url": "https://api.didww.com/storage/public/xptvgb8derrz0ru95wr9oi68g9tg?response-content-disposition=attachment%3B+filename%3D%22LOI+Example.pdf%22"
}
},
{
"id": "206ccec2-1166-461f-9f58-3a56823db548",
"type": "supporting_document_templates",
"attributes": {
"name": "Generic LOI",
"permanent": false,
"url": "https://api.didww.com/storage/public/w7f2irbo819la7vd7up7u67pkmkn?response-content-disposition=attachment%3B+filename%3D%22Generic+LOI.pdf%22"
}
}
],
"meta": {
"total_records": 38,
"api_version": "2022-05-10"
}
}
Important
If
needs_registrationistrue, the DID remains inactive until end-user details are assigned and the verification process is created, completed, and approved.If
needs_registrationisfalse, no registration requirements apply (requirement.dataisnull), and the DID can be activated without registration.
Step 4: Create the DID Order
Create the DID order using the selected stock_keeping_units.id.
From the order response, save the order.id, which is required in the next step to retrieve the DID created by the order.
For more information, see the /v3/orders endpoint documentation.
Note
A positive prepaid balance is required to successfully create a DID order.
For simplicity, detailed item attributes are not included in this response example.
http
POST /v3/orders HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "orders",
"attributes": {
"allow_back_ordering": true,
"items": [
{
"type": "did_order_items",
"attributes": {
"sku_id": "fedaec98-af1e-4441-bd7e-1c6668312ad5",
"qty": 1
}
}
]
}
}
}
curl
curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"attributes": {"allow_back_ordering": true, "items": [{"type": "did_order_items", "attributes": {"sku_id": "fedaec98-af1e-4441-bd7e-1c6668312ad5", "qty": 1}}]}, "type": "orders"}}'
response
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"id": "38ba6528-7460-410c-8fcc-262afb005ab3",
"type": "orders",
"attributes": {
"amount": "2.1",
"status": "Pending",
"created_at": "2026-01-08T09:10:20.270Z",
"description": "DID",
"reference": "YOY-267643"
}
},
"meta": {
"api_version": "2022-05-10"
}
}
Step 5: Retrieve the DID ID Created by the DID Order
Note
You may retrieve the DID ID immediately after the order is created, as shown in this step, or retrieve it later depending on your application flow and user interface design.
Retrieving the DID ID at this stage is optional. The DID ID is not required to retrieve registration requirements or to create identity and address resources. However, it is required later when assigning end-user details and starting DID verification (see Step 13: Assign End-User Details and Start DID Verification).
Retrieve the DID resource created by the order using the saved order.id.
From the response, save the did.id for future reference.
For more information, see the /v3/dids resource documentation.
http
GET /v3/dids?filter%5Border.id%5D=38ba6528-7460-410c-8fcc-262afb005ab3 HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/dids?filter%5Border.id%5D=38ba6528-7460-410c-8fcc-262afb005ab3' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "ad74ee84-aac8-4006-8c91-c08c59a32200",
"type": "dids",
"attributes": {
"blocked": true,
"capacity_limit": null,
"description": null,
"terminated": false,
"awaiting_registration": true,
"created_at": "2026-01-16T07:38:42.000Z",
"billing_cycles_count": null,
"number": "4924111111112",
"expires_at": "2026-02-16T07:38:42.508Z",
"channels_included_count": 2,
"dedicated_channels_count": 0
}
}
],
"meta": {
"total_records": 1,
"api_version": "2022-05-10"
}
}
Step 6: Retrieve and Review Registration Requirements
Depending on your application flow, registration requirements may already be
known. For example, they may be displayed together with a DID Group while
displaying number availability or coverage information, or they may be retrieved
dynamically based on user selections such as country and DID Group type. If the
requirement is already known, use the saved requirement.id from Step 3
(Get the SKU ID and Registration Requirement) to retrieve the full registration
requirement details.
In all cases, the retrieved requirement defines the identity, address, proofs, and supporting documents that must be created in the next steps and serves as the authoritative source for validation and verification.
The registration requirement specifies:
which identity types (Personal or Business) are allowed
which identity fields are mandatory
how many identity and address proofs must be provided
which proof types are accepted
whether address proofs are required
whether permanent and/or one-time supporting documents are required
whether a service description must be provided
any country, area, or city restrictions that apply
Before continuing to the next steps, review the accepted proof types defined in the registration requirement. These proof types determine which document categories the end user is allowed to submit for identity or address verification.
Your application should use this information to display valid document options to the user (for example, Passport or Utility Bill) and to ensure that each uploaded and encrypted document is linked to an accepted proof type when creating proofs in Step 10.
Accepted proof types are provided in the requirement response under the following relationships:
Business identity proofs
relationships.business_proof_types.data[].idPersonal identity proofs
relationships.personal_proof_types.data[].idAddress proofs (if required)
relationships.address_proof_types.data[].id
Each proof created later must reference one of these accepted proof types, together with an encrypted document and the corresponding identity or address.
For more information, see the Requirements resource documentation.
Use this approach when you already have the requirement.id (for example,
it was returned in Step 3 together with the selected SKU/DID Group). This
request returns the full requirement details, including accepted proof types
and supporting document templates.
http
GET /v3/requirements?filter%5Bid%5D=c6f606d8-106a-43d6-997e-17c7da5ae5d7&include=personal_proof_types%2Cbusiness_proof_types%2Caddress_proof_types%2Cpersonal_permanent_document%2Cbusiness_permanent_document%2Cpersonal_onetime_document%2Cbusiness_onetime_document HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/requirements?filter%5Bid%5D=c6f606d8-106a-43d6-997e-17c7da5ae5d7&include=personal_proof_types%2Cbusiness_proof_types%2Caddress_proof_types%2Cpersonal_permanent_document%2Cbusiness_permanent_document%2Cpersonal_onetime_document%2Cbusiness_onetime_document' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "c6f606d8-106a-43d6-997e-17c7da5ae5d7",
"type": "requirements",
"attributes": {
"identity_type": "Any",
"personal_area_level": "WorldWide",
"business_area_level": "WorldWide",
"address_area_level": "Area",
"personal_proof_qty": 1,
"business_proof_qty": 1,
"address_proof_qty": 0,
"personal_mandatory_fields": ["id_number"],
"business_mandatory_fields": ["vat_id"],
"service_description_required": false,
"restriction_message": "German Local DID End User registration requirements: ..."
},
"relationships": {
"personal_permanent_document": {
"data": {
"type": "supporting_document_templates",
"id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107"
}
},
"business_permanent_document": {
"data": {
"type": "supporting_document_templates",
"id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107"
}
},
"personal_onetime_document": {
"data": null
},
"business_onetime_document": {
"data": null
},
"personal_proof_types": {
"data": [
{
"type": "proof_types",
"id": "108b1fcf-686e-4017-a6c7-cf38c175f76a"
}
]
},
"business_proof_types": {
"data": [
{
"type": "proof_types",
"id": "80253913-cd8b-4ce2-91a9-9299587ac409"
}
]
},
"address_proof_types": {
"data": []
}
}
}
],
"included": [
{
"id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107",
"type": "supporting_document_templates",
"attributes": {
"name": "Belgium Registration Form",
"permanent": true,
"url": "https://api.didww.com/storage/public/e8lziulj68xetfa5ed6na3g7q7ra?response-content-disposition=attachment%3B+filename%3D%22Belgium+Registration+Form.pdf%22"
}
},
{
"id": "108b1fcf-686e-4017-a6c7-cf38c175f76a",
"type": "proof_types",
"attributes": {
"name": "Passport",
"entity_type": "Personal"
}
},
{
"id": "80253913-cd8b-4ce2-91a9-9299587ac409",
"type": "proof_types",
"attributes": {
"name": "Passport",
"entity_type": "Business"
}
}
]
}
Use this approach when the registration requirement.id is not known in advance and
your application allows the user to check requirements based on their selection.
After the user selects a country and a DID Group type, retrieve the
matching requirements (including country and did_group_type) and display:
the
restriction_messageany available supporting document template download links (when present)
http
GET /v3/requirements?include=country%2Cdid_group_type%2Cpersonal_permanent_document%2Cbusiness_permanent_document HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/requirements?include=country%2Cdid_group_type%2Cpersonal_permanent_document%2Cbusiness_permanent_document' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "6f71cc7b-8c13-4958-8623-60f750b8bcca",
"type": "requirements",
"attributes": {
"identity_type": "Any",
"personal_area_level": "WorldWide",
"business_area_level": "WorldWide",
"address_area_level": "Area",
"personal_proof_qty": 1,
"business_proof_qty": 0,
"address_proof_qty": 0,
"personal_mandatory_fields": null,
"business_mandatory_fields": null,
"service_description_required": false,
"restriction_message": "French Local DID End User registration requirements:\r\n\r\nFor personal identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n\r\nFor business identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name\r\n\r\nFor address verification:\r\n* Address matching the DID area code (street, building number, postal code, city and country)\r\n* A copy of a utility bill (less than 6 months old)\r\n\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.\r\n\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process."
},
"relationships": {
"country": {
"links": {
"self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/country",
"related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/country"
},
"data": {
"type": "countries",
"id": "7d9f8011-40a4-4fd7-a970-c3b679a75daf"
}
},
"did_group_type": {
"links": {
"self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/did_group_type",
"related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/did_group_type"
},
"data": {
"type": "did_group_types",
"id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
}
},
"personal_permanent_document": {
"links": {
"self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/personal_permanent_document",
"related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/personal_permanent_document"
},
"data": {
"type": "supporting_document_templates",
"id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107"
}
},
"business_permanent_document": {
"links": {
"self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/business_permanent_document",
"related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/business_permanent_document"
},
"data": null
},
"personal_onetime_document": {
"links": {
"self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/personal_onetime_document",
"related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/personal_onetime_document"
}
},
"business_onetime_document": {
"links": {
"self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/business_onetime_document",
"related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/business_onetime_document"
}
},
"personal_proof_types": {
"links": {
"self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/personal_proof_types",
"related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/personal_proof_types"
},
"data": [
{
"type": "proof_types",
"id": "19cd7b22-559b-41d4-99c9-7ad7ad63d5d1"
}
]
},
"business_proof_types": {
"links": {
"self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/business_proof_types",
"related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/business_proof_types"
}
},
"address_proof_types": {
"links": {
"self": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/address_proof_types",
"related": "https://api.didww.com/v3/requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/address_proof_types"
}
}
}
},
{
"id": "273d3bec-9a13-45b0-8fb4-c06bf46c1b34",
"type": "requirements",
"attributes": {
"identity_type": "Any",
"personal_area_level": "WorldWide",
"business_area_level": "WorldWide",
"address_area_level": "WorldWide",
"personal_proof_qty": 0,
"business_proof_qty": 0,
"address_proof_qty": 2,
"personal_mandatory_fields": null,
"business_mandatory_fields": null,
"service_description_required": true,
"restriction_message": "Japanese Local DID End User registration requirements:\r\n\r\n* For personal identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Passport or ID copy\r\n\r\nFor business identity verification:\r\n* Name, last name\r\n* Contact phone number\r\n* Company name\r\n* Company incorporation certificate copy\r\n\r\nFor address verification:\r\n* Address matching the DID area code (street, building number, postal code, city and country)\r\n* A copy of a utility bill (less than 6 months old)\r\n\r\nTo activate the DID number(s) please create an identity and address bundle matching the requirements and assign it to the DID number(s) for approval.\r\n\r\nWe reserve the right in our sole discretion to request additional information at any stage of the registration process."
},
"relationships": {
"country": {
"links": {
"self": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/country",
"related": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/country"
},
"data": {
"type": "countries",
"id": "eb89ebf7-2c8c-4e7d-9aea-89cddeced3c8"
}
},
"did_group_type": {
"links": {
"self": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/did_group_type",
"related": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/did_group_type"
},
"data": {
"type": "did_group_types",
"id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3"
}
},
"personal_permanent_document": {
"links": {
"self": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/personal_permanent_document",
"related": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/personal_permanent_document"
},
"data": null
},
"business_permanent_document": {
"links": {
"self": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/business_permanent_document",
"related": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/business_permanent_document"
},
"data": null
},
"personal_onetime_document": {
"links": {
"self": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/personal_onetime_document",
"related": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/personal_onetime_document"
}
},
"business_onetime_document": {
"links": {
"self": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/business_onetime_document",
"related": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/business_onetime_document"
}
},
"personal_proof_types": {
"links": {
"self": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/personal_proof_types",
"related": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/personal_proof_types"
},
"data": []
},
"business_proof_types": {
"links": {
"self": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/business_proof_types",
"related": "https://api.didww.com/v3/requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/business_proof_types"
}
},
}
}
],
"included": [
{
"id": "7549be3c-1077-433d-9a77-25416373660d",
"type": "countries",
"attributes": {
"name": "Sweden",
"prefix": "46",
"iso": "SE"
},
},
{
"id": "24eb6e85-f628-4765-bbb2-420e48de76f2",
"type": "countries",
"attributes": {
"name": "Canada",
"prefix": "1",
"iso": "CA"
},
},
{
"id": "fccd5be9-41dc-4daf-8894-234ecc916731",
"type": "countries",
"attributes": {
"name": "China",
"prefix": "86",
"iso": "CN"
},
},
{
"id": "6bba60f1-e724-4d12-9ea4-a3a64705800f",
"type": "did_group_types",
"attributes": { "name": "Mobile" }
},
{
"id": "994ea201-4a4d-4b27-ac4b-b5916ac969a3",
"type": "did_group_types",
"attributes": { "name": "Local" }
},
{
"id": "2c165e9d-c6f5-4fe1-ad0e-bacf5bab3d86",
"type": "did_group_types",
"attributes": { "name": "National" }
},
{
"id": "d6530a8c-924c-469a-98c0-9525602e6192",
"type": "did_group_types",
"attributes": { "name": "Global" }
},
{
"id": "ec95e831-fc36-489a-a531-0fd1984ab6e8",
"type": "did_group_types",
"attributes": { "name": "Toll-free" }
},
{
"id": "eb810289-8620-44e1-982d-13e6cee70404",
"type": "supporting_document_templates",
"attributes": {
"name": "Document Template 1",
"permanent": true,
"url": "https://api.didww.com/storage/public/owwqi77007ks4qx198b7su3eukg6?response-content-disposition=attachment%3B+filename%3D%22TestPermanDoc.png%22"
}
},
{
"id": "f65149c1-b551-4444-97d7-22939445c42a",
"type": "supporting_document_templates",
"attributes": {
"name": "Document Template 2",
"permanent": true,
"url": "https://api.didww.com/storage/public/txm3ftmuhyhypm6553b2874iuljg?response-content-disposition=attachment%3B+filename%3D%22TestDoc4.pdf%22"
}
},
{
"id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107",
"type": "supporting_document_templates",
"attributes": {
"name": "Belgium Registration Form",
"permanent": true,
"url": "https://api.didww.com/storage/public/e8lziulj68xetfa5ed6na3g7q7ra?response-content-disposition=attachment%3B+filename%3D%22Belgium+Registration+Form.pdf%22"
}
},
{
"id": "4199435f-646e-4e9d-a143-8f3b972b10c5",
"type": "supporting_document_templates",
"attributes": {
"name": "Germany Special Registration Form",
"permanent": true,
"url": "https://api.didww.com/storage/public/4rghqnqtba0fa7mbdgig086xej1e?response-content-disposition=attachment%3B+filename%3D%22Germany+Special+Registration+Form.pdf%22"
}
}
],
"meta": {
"total_records": 52,
"api_version": "2022-05-10"
}
}
Tip
In the UI, filter the returned requirements by the selected
country.id and did_group_type.id. Once a match is found, display
its restriction_message and provide download links for any included
supporting document templates.
Registration requirement field reference
Use the requirement attributes and relationships to decide what to create in the next steps.
Category |
API fields |
How to interpret and apply them |
|---|---|---|
Identity type |
|
Defines which identity types are allowed:
The identity you create must match this value. |
Identity restrictions |
|
Defines geographic restrictions for the identity:
When |
Address restrictions |
|
Defines where the address must be located:
Address relationships and attributes (such as |
Mandatory identity fields |
|
Lists identity fields that must be provided when creating the identity. |
Proof quantity requirements |
|
Specifies how many proofs must be submitted:
|
Accepted proof types |
|
Defines which proof types are accepted for each entity. Save the corresponding |
Supporting documents |
|
Defines whether permanent or one-time supporting documents are required.
|
Service description |
|
Indicates whether a service description must be provided during verification. |
Restriction message |
|
Provides a human-readable summary of regulatory requirements for the DID area. |
Supporting document templates |
|
Defines required supporting documents when
Each template includes:
Example: |
Proof type definitions |
|
Describes the proof types accepted for identity or address verification. Each proof type includes:
Use these entries together with the corresponding
|
Note
Registration requirements vary by DID Group, country, and identity type. Retrieve and follow the requirement linked to your DID Group.
Step 7: Create an Identity
Collect the required information from the end user purchasing the DID. This includes selecting the identity type (personal or business) and providing all mandatory fields defined by the applicable regulatory requirements, such as name, contact details, and country information.
Create an identity that will later be assigned to the DID when creating the
verification task in
Step 13. From the response,
save the identity.id, which is required to create an address for the identity
in the next step.
Ensure the identity complies with the regulatory requirements retrieved in Step 6, including the allowed identity type (personal or business), mandatory fields, applicable country restrictions, and the number and type of proofs required for the DID number.
For more information, see the Identity resource documentation.
Note
Identity attributes depend on the registration requirement and the selected identity type. Always include any fields listed under
personal_mandatory_fieldsorbusiness_mandatory_fieldsfrom Step 6.If the requirement restricts the identity to a specific country (
personal_area_level = Countryorbusiness_area_level = Country), set the identity country using therelationships.countryrelationship.For business identities,
first_nameandlast_nametypically represent the authorized contact person.Identities may be reused for multiple DID verifications, provided they continue to meet the applicable requirements.
http
POST /v3/identities HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "identities",
"attributes": {
"identity_type": "Business",
"company_name": "Example Company Ltd",
"first_name": "John",
"last_name": "Smith",
"phone_number": "3233461111",
"vat_id": "BE0123456789"
},
"relationships": {
"country": {
"data": {
"type": "countries",
"id": "f711b8ee-7576-4d40-9dd4-f51a69cee8a7"
}
}
}
}
}
curl
curl -i -X POST https://api.didww.com/v3/identities -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"attributes": {"company_name": "Example Company Ltd", "first_name": "John", "identity_type": "Business", "last_name": "Smith", "phone_number": "3233461111", "vat_id": "BE0123456789"}, "relationships": {"country": {"data": {"id": "f711b8ee-7576-4d40-9dd4-f51a69cee8a7", "type": "countries"}}}, "type": "identities"}}'
response
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"id": "beca16fb-0385-462f-9e2c-0d1918f6c8af",
"type": "identities",
"attributes": {
"first_name": "John",
"last_name": "Smith",
"phone_number": "3233461111",
"company_name": "Example Company Ltd",
"vat_id": "BE0123456789",
"identity_type": "Business",
"verified": false
}
},
"meta": {
"api_version": "2022-05-10"
}
}
Tip
Before continuing, you can validate whether the created identity meets the
regulatory requirements by validating it against the requirement.id
(see Step 12).
This allows you to detect issues (such as an invalid identity type or missing mandatory fields) early, before assigning the identity to the DID. If the identity complies with the requirement, the validation request succeeds without errors.
Step 8: Create an Address
Collect the required address information from the end user purchasing the DID. This typically includes street address, city, postal code, and country, based on the applicable regulatory requirements.
Create an address that will later be assigned to the DID in Step 13, and link it to the identity created in Step 7.
Ensure it complies with the regulatory requirements retrieved in
Step 6, including the
acceptable geographic scope (for example, address_area_level = Country) and
any other applicable requirements.
From the response, save the address.id. This value is required only if the
registration requirement specifies an address proof (address_proof_qty > 0).
Address proofs are linked to the address (not the identity), and the proof type must be one of the accepted proof types listed under
relationships.address_proof_types in the requirement response (Step 6).
For more information, see the Addresses resource documentation.
http
POST /v3/addresses HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "addresses",
"attributes": {
"address": "10 Example Street",
"city_name": "Antwerp",
"postal_code": "2000",
"description": "Business registration address"
},
"relationships": {
"identity": {
"data": {
"type": "identities",
"id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
}
},
"country": {
"data": {
"type": "countries",
"id": "f711b8ee-7576-4d40-9dd4-f51a69cee8a7"
}
}
}
}
}
curl
curl -i -X POST https://api.didww.com/v3/addresses -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"attributes": {"address": "10 Example Street", "city_name": "Antwerp", "description": "Business registration address", "postal_code": "2000"}, "relationships": {"country": {"data": {"id": "f711b8ee-7576-4d40-9dd4-f51a69cee8a7", "type": "countries"}}, "identity": {"data": {"id": "beca16fb-0385-462f-9e2c-0d1918f6c8af", "type": "identities"}}}, "type": "addresses"}}'
response
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"id": "04072428-07e4-4026-9d11-b49a770a95a8",
"type": "addresses",
"attributes": {
"address": "10 Example Street",
"city_name": "Antwerp",
"postal_code": "2000",
"description": "Business registration address",
"verified": false,
"created_at": "2026-01-09T09:22:23.066Z"
},
"relationships": {
"identity": {
"data": {
"type": "identities",
"id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
}
},
"country": {
"data": {
"type": "countries",
"id": "f711b8ee-7576-4d40-9dd4-f51a69cee8a7"
}
}
}
},
"meta": {
"api_version": "2022-05-10"
}
}
Tip
Before continuing, you can validate the address or both the identity
and address together against the requirement.id to ensure they meet
the regulatory requirements (see
Step 12).
This helps detect issues early—such as an invalid identity type or missing mandatory fields—before assigning the identity or address to the DID. If the submitted data complies with the requirement, the validation request completes successfully without errors.
Step 9: Encrypt and Upload Documents
After reviewing the registration requirements in Step 6 and collecting the required identity and address information, your application may need to request supporting documents from the end user.
Depending on the requirement, this can include identity proofs (for example, a passport or national ID) and/or address proofs (such as a utility bill). These documents are provided by the user based on the accepted proof types and supporting document rules defined in the registration requirement.
If a registration requirement specifies identity proofs or supporting documents, those documents must be encrypted before upload. All documents submitted to the DIDWW API require encryption to ensure secure handling.
Document encryption protects sensitive personal and business information during transmission and storage. It ensures that identity and address documents remain confidential.
Encryption always produces a file with the .enc suffix. Only encrypted files
are accepted by the /v3/encrypted_files endpoint.
Encrypt the document
Encrypt the document in the browser using the DIDWW encryption library. This approach is commonly used in web applications.
- Encryption library:
- Encryption steps:
Select the original document (for example,
passport.pdf).Encrypt the file using the library.
Save the encrypted output with the
.encsuffix (for example,passport.pdf.enc).
The result of this process is a ready-to-use encrypted file that can be uploaded to the API in the next step.
Encrypt the document on the server using one of the supported SDKs. This approach is commonly used in backend services.
- Supported libraries:
- Encryption steps:
Load the original document on the server.
Encrypt the file using one of the supported libraries.
Save the encrypted output with the
.encsuffix.
The result of this process is a ready-to-use encrypted file.
Upload the encrypted file
Note
Uploaded encrypted files expire after 24 hours
Accepted file formats: .pdf, .jpg, .png
Up to 5 encrypted files may be uploaded in a single request
Each file must not exceed 20 MB
Upload the encrypted .enc files using the /v3/encrypted_files endpoint. This endpoint uses Content-Type: multipart/form-data and does not accept
JSON request bodies.
Each uploaded encrypted file is stored securely and results in a unique encrypted file ID. Returned IDs are provided in the ids array, where each
value represents an encrypted_file.id.
Save these encrypted_file.id values, as they are required in later steps when:
creating identity or address proofs (see Step 10: Create Identity and Address Proofs)
attaching permanent supporting documents, if required (see Step 11: Create a Permanent Supporting Document)
attaching one-time supporting documents, if required (see Step 13: Assign End-User Details and Start DID Verification)
For more details, see the Encrypted Files resource documentation.
Use this approach when uploading one document (for example, a passport used as an identity proof).
curl --location 'https://api.didww.com/v3/encrypted_files' \
--header 'Accept: application/vnd.api+json' \
--header 'Content-Type: multipart/form-data' \
--header 'Api-Key: [API token]' \
--form 'encrypted_files[encryption_fingerprint]={{encryption_fingerprint}}' \
--form 'encrypted_files[items][][description]=passport' \
--form 'encrypted_files[items][][file]=@"/path/to/passport.pdf.enc"'
{
"ids": [
"66df7731-fcf9-4bf3-a03f-2881bd44fe9c"
]
}
Use this approach when uploading multiple documents at once, such as an identity proof and a permanent supporting document.
curl --location 'https://api.didww.com/v3/encrypted_files' \
--header 'Accept: application/vnd.api+json' \
--header 'Content-Type: multipart/form-data' \
--header 'Api-Key: [API token]' \
--form 'encrypted_files[encryption_fingerprint]={{encryption_fingerprint}}' \
--form 'encrypted_files[items][][description]=passport' \
--form 'encrypted_files[items][][file]=@"/path/to/passport.pdf.enc"' \
--form 'encrypted_files[items][][description]=belgium-registration-form' \
--form 'encrypted_files[items][][file]=@"/path/to/belgium_registration_form.pdf.enc"'
{
"ids": [
"66df7731-fcf9-4bf3-a03f-2881bd44fe9c",
"e5686c72-76fd-461e-bcfa-66c19be680f5"
]
}
Note
To upload additional encrypted files in the same request, repeat the following form field pair for each additional file:
encrypted_files[items][][description]encrypted_files[items][][file]
The order of IDs in the response corresponds to the order of files provided in the multipart form fields.
Step 10: Create Identity and Address Proofs
After the required documents have been encrypted and uploaded (Step 9), they must be associated with the appropriate identity or address as proofs.
Proof records represent the relationship between an uploaded document and the entity it validates. Depending on the registration requirement, proofs may be required for an identity (personal or business), an address, or both.
If the registration requirement specifies that proofs are required, create proof records and link them to the corresponding entities involved in the verification process. Each proof references an encrypted document, an accepted proof type, and the entity it applies to.
These proof records are evaluated later in Step 12, where the identity and address are validated against the registration requirement
Note
Proofs are required only when the corresponding quantity
(business_proof_qty, personal_proof_qty, or address_proof_qty)
is greater than 0 in the registration requirement.
Each proof requires:
an
encrypted_file.idobtained in Step 9 where the user uploads a document, the application encrypts it, and the encrypted file is submitted to the APIa
proof_type.idaccepted by the registration requirement retrieved in Step 6an
entitythe proof applies to (useidentities.idfor identity proofs oraddresses.idfor address proofs)
Use this approach when the registration requirement specifies
business_proof_qty or personal_proof_qty greater than 0.
Note
The proof_type.id must be selected from the accepted proof types
defined in the registration requirement retrieved in
Step 6:
use
relationships.personal_proof_types.data[].idfor personal identitiesuse
relationships.business_proof_types.data[].idfor business identities
http
POST /v3/proofs HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "proofs",
"relationships": {
"files": {
"data": [
{
"type": "encrypted_files",
"id": "66df7731-fcf9-4bf3-a03f-2881bd44fe9c"
}
]
},
"proof_type": {
"data": {
"type": "proof_types",
"id": "80253913-cd8b-4ce2-91a9-9299587ac409"
}
},
"entity": {
"data": {
"type": "identities",
"id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
}
}
}
}
}
curl
curl -i -X POST https://api.didww.com/v3/proofs -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"relationships": {"entity": {"data": {"id": "beca16fb-0385-462f-9e2c-0d1918f6c8af", "type": "identities"}}, "files": {"data": [{"type": "encrypted_files", "id": "66df7731-fcf9-4bf3-a03f-2881bd44fe9c"}]}, "proof_type": {"data": {"id": "80253913-cd8b-4ce2-91a9-9299587ac409", "type": "proof_types"}}}, "type": "proofs"}}'
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"id": "f03ec8b2-535e-46a4-a951-60922203a48c",
"type": "proofs",
"attributes": {
"created_at": "2026-01-09T13:20:09.232Z",
"expires_at": null
}
},
"meta": {
"api_version": "2022-05-10"
}
}
Use this approach only if the registration requirement specifies
address_proof_qty greater than 0.
Note
The proof type must be one of the accepted proof types listed under
address_proof_types in the registration requirement retrieved in
Step 6.
Link the proof to the address by setting entity.type to addresses and
entity.id to your address.id.
http
POST /v3/proofs HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "proofs",
"relationships": {
"files": {
"data": [
{
"type": "encrypted_files",
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
}
]
},
"proof_type": {
"data": {
"type": "proof_types",
"id": "ffffffff-1111-2222-3333-444444444444"
}
},
"entity": {
"data": {
"type": "addresses",
"id": "04072428-07e4-4026-9d11-b49a770a95a8"
}
}
}
}
}
curl
curl -i -X POST https://api.didww.com/v3/proofs -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"relationships": {"entity": {"data": {"id": "04072428-07e4-4026-9d11-b49a770a95a8", "type": "addresses"}}, "files": {"data": [{"type": "encrypted_files", "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"}]}, "proof_type": {"data": {"id": "ffffffff-1111-2222-3333-444444444444", "type": "proof_types"}}}, "type": "proofs"}}'
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"id": "f03ec8b2-535e-46a4-a951-60922203a48d",
"type": "proofs",
"attributes": {
"created_at": "2026-01-09T13:20:09.232Z",
"expires_at": null
}
},
"meta": {
"api_version": "2022-05-10"
}
}
Step 11: Create a Permanent Supporting Document (If Required)
Some registration requirements mandate a permanent supporting document (template-based document) to be submitted together with the identity.
A permanent supporting document is required when the registration requirement contains one of the following:
business_permanent_document(for business identities)personal_permanent_document(for personal identities)
Note
If both business_permanent_document and personal_permanent_document are
null in the requirement response, no permanent supporting document is
required and this step can be skipped.
Each permanent supporting document requires:
an
encrypted_file.idobtained in Step 9 after the user uploads the completed document and it is encrypted by the applicationa
supporting_document_template.iddefined by the registration requirement retrieved in Step 6an
identity.idcorresponding to the personal or business identity created in Step 7
For additional details, see the Permanent Supporting Documents resource documentation.
http
POST /v3/permanent_supporting_documents HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "permanent_supporting_documents",
"relationships": {
"files": {
"data": [
{
"type": "encrypted_files",
"id": "e5686c72-76fd-461e-bcfa-66c19be680f5"
}
]
},
"template": {
"data": {
"type": "supporting_document_templates",
"id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107"
}
},
"identity": {
"data": {
"type": "identities",
"id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
}
}
}
}
}
curl
curl -i -X POST https://api.didww.com/v3/permanent_supporting_documents -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"relationships": {"files": {"data": [{"type": "encrypted_files", "id": "e5686c72-76fd-461e-bcfa-66c19be680f5"}]}, "identity": {"data": {"id": "beca16fb-0385-462f-9e2c-0d1918f6c8af", "type": "identities"}}, "template": {"data": {"id": "fd38c86d-b69b-4ca8-b73c-286a3b93d107", "type": "supporting_document_templates"}}}, "type": "permanent_supporting_documents"}}'
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"id": "363abdd4-2286-4b53-ab42-9726d61adc77",
"type": "permanent_supporting_documents",
"attributes": {
"created_at": "2026-01-12T08:55:57.553Z"
}
},
"meta": {
"api_version": "2022-05-10"
}
}
Step 12: Validate Identity and Address Against Requirements
Validate the identity, address, and all submitted proofs against the registration requirement before starting the DID verification task.
This validation confirms that all regulatory conditions have been met and allows you to detect missing or invalid data early, such as incomplete identity fields, missing proofs, unsupported proof types, or address scope mismatches.
Note
Validation is required only when the DID Group has a registration requirement
(needs_registration = true).
The validation checks that:
all mandatory identity fields are present
the required number and type of proofs and supporting documents have been submitted
the address meets the geographic restrictions defined by the requirement
If the validation succeeds, the identity and address are considered compliant and can be safely assigned to the DID in the next step to start verification.
For additional details about requirement validation, see Validate.
http
POST /v3/requirement_validations HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "requirement_validations",
"relationships": {
"requirement": {
"data": {
"type": "requirements",
"id": "c6f606d8-106a-43d6-997e-17c7da5ae5d7"
}
},
"identity": {
"data": {
"type": "identities",
"id": "beca16fb-0385-462f-9e2c-0d1918f6c8af"
}
},
"address": {
"data": {
"type": "addresses",
"id": "04072428-07e4-4026-9d11-b49a770a95a8"
}
}
}
}
}
curl
curl -i -X POST https://api.didww.com/v3/requirement_validations -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"relationships": {"address": {"data": {"id": "04072428-07e4-4026-9d11-b49a770a95a8", "type": "addresses"}}, "identity": {"data": {"id": "beca16fb-0385-462f-9e2c-0d1918f6c8af", "type": "identities"}}, "requirement": {"data": {"id": "c6f606d8-106a-43d6-997e-17c7da5ae5d7", "type": "requirements"}}}, "type": "requirement_validations"}}'
response
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"id": "e67bc7f0-71c1-451b-978e-d9188bcd39fa",
"type": "requirement_validations"
},
"meta": {
"api_version": "2022-05-10"
}
}
Note
If the validation request is rejected, review the error details and adjust the identity, address, proofs, or supporting documents accordingly.
Step 13: Assign End-User Details and Start DID Verification
Create the verification task that assigns the validated identity and address to the DID and initiates the regulatory verification process.
Note
This step should be performed only after the identity, address, proofs, and documents have been successfully validated in Step 12.
The verification task evaluates all previously submitted data, including:
the identity
the address
identity and address proofs (if required)
permanent supporting documents (if required)
one-time supporting documents (if required)
For more information, see Address Verifications.
Use this structure when the registration requirement does not specify a one-time supporting document.
http
POST /v3/address_verifications HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "address_verifications",
"attributes": {
"callback_url": "https://example.com/callback",
"callback_method": "POST"
},
"relationships": {
"dids": {
"data": [
{
"type": "dids",
"id": "ad74ee84-aac8-4006-8c91-c08c59a32200"
}
]
},
"address": {
"data": {
"type": "addresses",
"id": "04072428-07e4-4026-9d11-b49a770a95a8"
}
}
}
}
}
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": "POST", "callback_url": "https://example.com/callback"}, "relationships": {"address": {"data": {"id": "04072428-07e4-4026-9d11-b49a770a95a8", "type": "addresses"}}, "dids": {"data": [{"type": "dids", "id": "ad74ee84-aac8-4006-8c91-c08c59a32200"}]}}, "type": "address_verifications"}}'
response
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"id": "066395a4-7904-4a68-97d2-a2fc007d0634",
"type": "address_verifications",
"attributes": {
"service_description": null,
"callback_url": "https://example.com/callback",
"callback_method": "POST",
"status": "Pending",
"reject_reasons": null,
"reference": "SVA-822866",
"created_at": "2026-01-12T09:46:19.214Z"
}
},
"meta": {
"api_version": "2022-05-10"
}
}
Use this structure only when the registration requirement retrieved in Step 6 defines a
one-time supporting document under personal_onetime_document or business_onetime_document.
http
POST /v3/address_verifications HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "address_verifications",
"attributes": {
"callback_url": "https://example.com/callback",
"callback_method": "POST"
},
"relationships": {
"onetime_files": {
"data": [
{
"type": "encrypted_files",
"id": "11111111-2222-3333-4444-555555555555"
}
]
},
"dids": {
"data": [
{
"type": "dids",
"id": "ad74ee84-aac8-4006-8c91-c08c59a32200"
}
]
},
"address": {
"data": {
"type": "addresses",
"id": "04072428-07e4-4026-9d11-b49a770a95a8"
}
}
}
}
}
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": "POST", "callback_url": "https://example.com/callback"}, "relationships": {"address": {"data": {"id": "04072428-07e4-4026-9d11-b49a770a95a8", "type": "addresses"}}, "dids": {"data": [{"type": "dids", "id": "ad74ee84-aac8-4006-8c91-c08c59a32200"}]}, "onetime_files": {"data": [{"type": "encrypted_files", "id": "11111111-2222-3333-4444-555555555555"}]}}, "type": "address_verifications"}}'
response
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"id": "066395a4-7904-4a68-97d2-a2fc007d0634",
"type": "address_verifications",
"attributes": {
"service_description": null,
"callback_url": "https://example.com/callback",
"callback_method": "POST",
"status": "Pending",
"reject_reasons": null,
"reference": "SVA-822866",
"created_at": "2026-01-12T09:46:19.214Z"
}
},
"meta": {
"api_version": "2022-05-10"
}
}
Use this structure when the registration requirement retrieved in
Step 6 allows or requires
providing a service description (service_description_required = true).
The service description explains the intended use of the DID number (for example, customer support, outbound sales, or application notifications) and is evaluated as part of the regulatory verification process.
http
POST /v3/address_verifications HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "address_verifications",
"attributes": {
"callback_url": "https://example.com/callback",
"callback_method": "POST",
"service_description": "Inbound customer support calls for a SaaS platform"
},
"relationships": {
"dids": {
"data": [
{
"type": "dids",
"id": "ad74ee84-aac8-4006-8c91-c08c59a32200"
}
]
},
"address": {
"data": {
"type": "addresses",
"id": "04072428-07e4-4026-9d11-b49a770a95a8"
}
}
}
}
}
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": "POST", "callback_url": "https://example.com/callback", "service_description": "Inbound customer support calls for a SaaS platform"}, "relationships": {"address": {"data": {"id": "04072428-07e4-4026-9d11-b49a770a95a8", "type": "addresses"}}, "dids": {"data": [{"type": "dids", "id": "ad74ee84-aac8-4006-8c91-c08c59a32200"}]}}, "type": "address_verifications"}}'
response
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"id": "066395a4-7904-4a68-97d2-a2fc007d0634",
"type": "address_verifications",
"attributes": {
"service_description": "Inbound customer support calls for a SaaS platform",
"callback_url": "https://example.com/callback",
"callback_method": "POST",
"status": "Pending",
"reject_reasons": null,
"reference": "SVA-822866",
"created_at": "2026-01-12T09:46:19.214Z"
}
},
"meta": {
"api_version": "2022-05-10"
}
}
Monitor the verification process until it becomes Approved or
Rejected by retrieving the verification status from the
GET /v3/address_verifications endpoint.
The verification status indicates whether the submitted identity, address, proofs, and supporting documents have been approved or rejected. If the verification is rejected, the response includes a rejection reason that explains what must be corrected before resubmitting.
Note
A callback_url and callback_method can be configured for address
verifications to receive HTTP callbacks when the verification status
changes.
Callback events are sent when the verification is approved or
rejected. The payload includes the verification ID, resource type
(address_verifications), the current status, and a rejection reason when
applicable.
See Callback configuration for more information.