# 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: - [Step 1: Find the Country ID](#user-panel-api-examples-verification-step1) - [Step 2: Find the City ID](#user-panel-api-examples-verification-step2) - [Step 3: Retrieve DID Availability, Pricing, and Registration Requirements](#user-panel-api-examples-verification-step3) - [Step 4: Create the DID Order](#user-panel-api-examples-verification-step4) - [Step 5: Retrieve the DID ID Created by the DID Order](#user-panel-api-examples-verification-step5) - [Step 6: Retrieve and Review Registration Requirements](#user-panel-api-examples-verification-step6) - [Step 7: Create an Identity](#user-panel-api-examples-verification-step7) - [Step 8: Create an Address](#user-panel-api-examples-verification-step8) - [Step 9: Encrypt and Upload Documents](#user-panel-api-examples-verification-step9) - [Step 10: Create Identity and Address Proofs](#user-panel-api-examples-verification-step10) - [Step 11: Create a Permanent Supporting Document (If Required)](#user-panel-api-examples-verification-step11) - [Step 12: Validate Identity and Address Against Requirements](#user-panel-api-examples-verification-step12) - [Step 13: Assign End-User Details and Start DID Verification](#user-panel-api-examples-verification-step13) 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](../2026-04-16/coverage-resources/countries/get-countries.html#countries-v34-get-countries) endpoint documentation. *Find a country by ISO code* 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`. [[DIDWW-API-EXAMPLE-START]] 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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] Note This example filters by country ISO code. Adjust filters as needed to match your use case. *List countries available for purchase* 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. [[DIDWW-API-EXAMPLE-START]] 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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] --- ## 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. Include `area` in the request to also retrieve the regulatory area the city belongs to. The related `area.id` is only needed later, when preparing an address for a requirement where `address_area_level` is `area` (see [Step 6](#user-panel-api-examples-verification-step6)); it is not required by the `/v3/did_groups` request in the next step. Not every city has an associated area - when none applies, `relationships.area.data` is `null`. For more information, see the [/v3/cities](../2026-04-16/coverage-resources/city/get-cities.html#cities-v34-get-cities) endpoint documentation. [[DIDWW-API-EXAMPLE-START]] http ``` GET /v3/cities?filter%5Bcountry.id%5D=f711b8ee-7576-4d40-9dd4-f51a69cee8a7&filter%5Bname%5D=Aachen&include=area 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&include=area' -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" }, "relationships": { "area": { "data": { "type": "areas", "id": "1a2c9c1e-7e3c-4a3a-9e42-3a7d2a6f9b31" } } } } ], "included": [ { "id": "1a2c9c1e-7e3c-4a3a-9e42-3a7d2a6f9b31", "type": "areas", "attributes": { "name": "North Rhine-Westphalia" } } ], "meta": { "total_records": 1, "api_version": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] 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 `address_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. - `address_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](#user-panel-api-examples-verification-step12)). For more information, see the [/v3/did\_groups](../2026-04-16/coverage-resources/did-group/get-did-groups.html#did-groups-v34-get-did-groups) endpoint documentation. *Filter by City* 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. [[DIDWW-API-EXAMPLE-START]] http ``` GET /v3/did_groups?include=stock_keeping_units%2Caddress_requirement&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%2Caddress_requirement&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", "voice_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" } ] }, "address_requirement": { "data": { "type": "address_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": "address_requirements", "attributes": { "identity_type": "any", "personal_area_level": "world_wide", "business_area_level": "world_wide", "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" } } ] } ``` [[DIDWW-API-EXAMPLE-END]] *Display Country Coverage* 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. [[DIDWW-API-EXAMPLE-START]] 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%2Caddress_requirement%2Caddress_requirement.personal_onetime_document%2Caddress_requirement.business_onetime_document%2Caddress_requirement.personal_permanent_document%2Caddress_requirement.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%2Caddress_requirement%2Caddress_requirement.personal_onetime_document%2Caddress_requirement.business_onetime_document%2Caddress_requirement.personal_permanent_document%2Caddress_requirement.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" } ] }, "address_requirement": { "data": { "type": "address_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" } ] }, "address_requirement": { "data": { "type": "address_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": "address_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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] Note `/v3/did_groups` also supports `filter[area_name]`, a case-insensitive match against the DID Group's `area_name` attribute (for example `Aachen` or `National`). Use it to narrow results by locality without first resolving a `city.id`. This filter is independent of the Areas resource used for `address_area_level: area` requirements - see [Step 6](#user-panel-api-examples-verification-step6). Important - If `needs_registration` is `true`, the DID remains inactive until end-user details are assigned and the verification process is created, completed, and approved. - If `needs_registration` is `false`, no registration requirements apply (`address_requirement.data` is `null`), 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](../2026-04-16/inventory-resources/order/create-order.html#orders-v34-create-order) 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. [[DIDWW-API-EXAMPLE-START]] 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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] --- ## 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](#user-panel-api-examples-verification-step13)). 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](../2026-04-16/inventory-resources/did/index.html#dids-v34) resource documentation. [[DIDWW-API-EXAMPLE-START]] 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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] --- ## 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 `address_requirement.id` from Step 3 ([Get the SKU ID and Registration Requirement](#user-panel-api-examples-sku-and-requirements)) 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](#user-panel-api-examples-verification-step10). Accepted proof types are provided in the requirement response under the following relationships: - **Business identity proofs** `relationships.business_proof_types.data[].id` - **Personal identity proofs** `relationships.personal_proof_types.data[].id` - **Address 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 [Address Requirements](../2026-04-16/regulation-resources/requirements/index.html#address-requirements-v34) resource documentation. *Retrieve by Requirement ID* Use this approach when you already have the `address_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. [[DIDWW-API-EXAMPLE-START]] http ``` GET /v3/address_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/address_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": "address_requirements", "attributes": { "identity_type": "any", "personal_area_level": "world_wide", "business_area_level": "world_wide", "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" } } ] } ``` [[DIDWW-API-EXAMPLE-END]] *Retrieve by Country and DID Group Type* Use this approach when the registration `address_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_message` > - any available supporting document template download links (when present) [[DIDWW-API-EXAMPLE-START]] http ``` GET /v3/address_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/address_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": "address_requirements", "attributes": { "identity_type": "any", "personal_area_level": "world_wide", "business_area_level": "world_wide", "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/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/country", "related": "https://api.didww.com/v3/address_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/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/did_group_type", "related": "https://api.didww.com/v3/address_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/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/personal_permanent_document", "related": "https://api.didww.com/v3/address_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/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/business_permanent_document", "related": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/business_permanent_document" }, "data": null }, "personal_onetime_document": { "links": { "self": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/personal_onetime_document", "related": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/personal_onetime_document" } }, "business_onetime_document": { "links": { "self": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/business_onetime_document", "related": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/business_onetime_document" } }, "personal_proof_types": { "links": { "self": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/personal_proof_types", "related": "https://api.didww.com/v3/address_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/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/business_proof_types", "related": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/business_proof_types" } }, "address_proof_types": { "links": { "self": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/relationships/address_proof_types", "related": "https://api.didww.com/v3/address_requirements/6f71cc7b-8c13-4958-8623-60f750b8bcca/address_proof_types" } } } }, { "id": "273d3bec-9a13-45b0-8fb4-c06bf46c1b34", "type": "address_requirements", "attributes": { "identity_type": "any", "personal_area_level": "world_wide", "business_area_level": "world_wide", "address_area_level": "world_wide", "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/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/country", "related": "https://api.didww.com/v3/address_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/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/did_group_type", "related": "https://api.didww.com/v3/address_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/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/personal_permanent_document", "related": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/personal_permanent_document" }, "data": null }, "business_permanent_document": { "links": { "self": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/business_permanent_document", "related": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/business_permanent_document" }, "data": null }, "personal_onetime_document": { "links": { "self": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/personal_onetime_document", "related": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/personal_onetime_document" } }, "business_onetime_document": { "links": { "self": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/business_onetime_document", "related": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/business_onetime_document" } }, "personal_proof_types": { "links": { "self": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/personal_proof_types", "related": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/personal_proof_types" }, "data": [] }, "business_proof_types": { "links": { "self": "https://api.didww.com/v3/address_requirements/273d3bec-9a13-45b0-8fb4-c06bf46c1b34/relationships/business_proof_types", "related": "https://api.didww.com/v3/address_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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] 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** | `identity_type` | Defines which identity types are allowed: - `any`: personal and business identities are allowed. - `personal`: only a personal identity is allowed. - `business`: only a business identity is allowed. The identity you create **must match** this value. | | **Identity restrictions** | `personal_area_level`, `business_area_level` | Defines geographic restrictions for the identity: - `world_wide`: the identity can belong to any country. - `country`: the identity country must match the DID country. When `country` is required, set the identity country using the `relationships.country` relationship when creating the identity. | | **Address restrictions** | `address_area_level` | Defines where the address must be located: - `world_wide`: any country is allowed. - `country`: address must match the DID country. - `area` or `city`: address must match the DID area or city. Address relationships and attributes (such as `country`, `city_name`) must comply with these restrictions. | | **Mandatory identity fields** | `personal_mandatory_fields`, `business_mandatory_fields` | Lists identity fields that must be provided when creating the identity. | | **Proof quantity requirements** | `personal_proof_qty`, `business_proof_qty`, `address_proof_qty` | Specifies how many proofs must be submitted: - `business_proof_qty = 1` means exactly one business proof is required. - `address_proof_qty = 0` means no address proof is required. | | **Accepted proof types** | `relationships.personal_proof_types`, `relationships.business_proof_types`, `relationships.address_proof_types` | Defines which proof types are accepted for each entity. Save the corresponding `proof_type.id` for use when creating proofs. | | **Supporting documents** | `personal_permanent_document`, `business_permanent_document`, `personal_onetime_document`, `business_onetime_document` | Defines whether permanent or one-time supporting documents are required. - Permanent documents can be reused for future verifications. - One-time documents must be submitted with the verification task. | | **Service description** | `service_description_required` | Indicates whether a service description must be provided during verification. | | **Restriction message** | `restriction_message` | Provides a human-readable summary of regulatory requirements for the DID area. | | **Supporting document templates** | `included[].type = supporting_document_templates` | Defines required supporting documents when `personal_permanent_document` or `business_permanent_document` is present. Each template includes: - `name` - the document name displayed to the end user - `permanent` - whether the document can be reused for future verifications - `url` - a downloadable template that must be completed, encrypted, and uploaded Example: `Belgium Registration Form` is a permanent document. | | **Proof type definitions** | `included[].type = proof_types` | Describes the proof types accepted for identity or address verification. Each proof type includes: - `name` - the document type (e.g. Passport) - `entity_type` - whether it applies to `personal` or `business` identities Use these entries together with the corresponding `relationships.proof_types` to select the correct proof when creating identity or address proofs. | 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](#user-panel-api-examples-verification-step13). 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](#user-panel-api-examples-verification-step6), 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](../2026-04-16/regulation-resources/identities/index.html#identities-v34) resource documentation. Note - Identity attributes depend on the registration requirement and the selected identity type. Always include any fields listed under `personal_mandatory_fields` or `business_mandatory_fields` from [Step 6](#user-panel-api-examples-verification-step6). - If the requirement restricts the identity to a specific country (`personal_area_level = Country` or `business_area_level = Country`), set the identity country using the `relationships.country` relationship. - For business identities, `first_name` and `last_name` typically represent the authorized contact person. - Identities may be reused for multiple DID verifications, provided they continue to meet the applicable requirements. [[DIDWW-API-EXAMPLE-START]] 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": "3233461122", "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": "3233461122", "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": "3233461122", "company_name": "Example Company Ltd", "vat_id": "BE0123456789", "identity_type": "business", "verified": false } }, "meta": { "api_version": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] Tip Before continuing, you can validate whether the created **identity** meets the regulatory requirements by validating it against the `address_requirement.id` (see [Step 12](#user-panel-api-examples-verification-step12)). 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](#user-panel-api-examples-verification-step13), and link it to the identity created in [Step 7](#user-panel-api-examples-verification-step7). Ensure it complies with the regulatory requirements retrieved in [Step 6](#user-panel-api-examples-verification-step6), 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](#user-panel-api-examples-verification-step6)). For more information, see the [Addresses](../2026-04-16/regulation-resources/addresses/index.html#addresses-v34) resource documentation. [[DIDWW-API-EXAMPLE-START]] 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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] Tip Before continuing, you can validate the **address** or both the **identity** and **address** together against the `address_requirement.id` to ensure they meet the regulatory requirements (see [Step 12](#user-panel-api-examples-verification-step12)). 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](#user-panel-api-examples-verification-step6) 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 *Browser-based encryption* Encrypt the document in the browser using the DIDWW encryption library. This approach is commonly used in web applications. Encryption library: : - [@didww/encrypt](https://github.com/didww/didww-encrypt) Encryption steps: : 1. Select the original document (for example, `passport.pdf`). 2. Encrypt the file using the library. 3. Save the encrypted output with the `.enc` suffix (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. *Server-side encryption* Encrypt the document on the server using one of the supported SDKs. This approach is commonly used in backend services. **Ruby Gem** Use the APIv3 Ruby gem to perform file encryption on the server side. **PHP SDK** Use the official PHP SDK to implement server-side encryption. **Java SDK** Use the official Java SDK to implement server-side encryption. **Python SDK** Use the official Python SDK to implement server-side encryption. **TypeScript SDK** Use the official TypeScript SDK to implement server-side encryption. **Go Encryption Sample** > Use the Go sample project to implement server-side file encryption compatible with DIDWW API v3. **.NET Encryption Sample** Use the .NET sample implementation to add server-side file encryption compatible with DIDWW API v3. Encryption steps: : 1. Load the original document on the server. 2. Encrypt the file using one of the supported libraries. 3. Save the encrypted output with the `.enc` suffix. 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** - Each request uploads **one encrypted file** - Each file must not exceed **20 MB** Upload the encrypted `.enc` file 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 as `data.id` in the response. Save this `encrypted_file.id` value, as it is required in later steps when: - creating identity or address proofs (see [Step 10: Create Identity and Address Proofs](#user-panel-api-examples-verification-step10)) - attaching permanent supporting documents, if required (see [Step 11: Create a Permanent Supporting Document](#user-panel-api-examples-verification-step11)) - attaching one-time supporting documents, if required (see [Step 13: Assign End-User Details and Start DID Verification](#user-panel-api-examples-verification-step13)) For more details, see the [Encrypted Files](../2026-04-16/regulation-resources/encrypted-files/index.html#encrypted-files-v34) resource documentation. curl ``` 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[description]=passport' \ --form 'encrypted_files[file]=@"/path/to/passport.pdf.enc"' ``` Response ``` { "data": { "id": "66df7731-fcf9-4bf3-a03f-2881bd44fe9c", "type": "encrypted_files", "attributes": { "description": "passport", "expires_at": "2026-01-17T07:38:42.508Z" } }, "meta": { "api_version": "2026-04-16" } } ``` Note Legacy batch parameters such as `encrypted_files[items][][file]` are not supported in version `2026-04-16` and return `400 Bad Request`. To upload multiple documents (for example, an identity proof and a permanent supporting document), send a separate request for each file and save the `encrypted_file.id` returned by each response. --- ## Step 10: Create Identity and Address Proofs After the required documents have been encrypted and uploaded ([Step 9](#user-panel-api-examples-verification-step9)), 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](#user-panel-api-examples-verification-step12), 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.id` obtained in [Step 9](#user-panel-api-examples-verification-step9) where the user uploads a document, the application encrypts it, and the encrypted file is submitted to the API > - a `proof_type.id` accepted by the registration requirement retrieved in [Step 6](#user-panel-api-examples-verification-step6) > - an `entity` the proof applies to (use `identities.id` for identity proofs or `addresses.id` for address proofs) *Create an identity proof* 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](#user-panel-api-examples-verification-step6): - use `relationships.personal_proof_types.data[].id` for **personal** identities - use `relationships.business_proof_types.data[].id` for **business** identities [[DIDWW-API-EXAMPLE-START]] 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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] *Create an address proof* 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](#user-panel-api-examples-verification-step6). Link the proof to the address by setting `entity.type` to `addresses` and `entity.id` to your `address.id`. [[DIDWW-API-EXAMPLE-START]] 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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] --- ## 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.id` obtained in [Step 9](#user-panel-api-examples-verification-step9) after the user uploads the completed document and it is encrypted by the application - a `supporting_document_template.id` defined by the registration requirement retrieved in [Step 6](#user-panel-api-examples-verification-step6) - an `identity.id` corresponding to the personal or business identity created in [Step 7](#user-panel-api-examples-verification-step7) For additional details, see the [Permanent Supporting Documents](../2026-04-16/regulation-resources/permanent-documents/create-permanent-document.html#create-permanent-supporting-document-v34) resource documentation. [[DIDWW-API-EXAMPLE-START]] 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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] --- ## 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 [Address Requirement Validations](../2026-04-16/regulation-resources/requirements/address-requirement-validations.html#address-requirement-validations-v34). [[DIDWW-API-EXAMPLE-START]] http ``` POST /v3/address_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": "address_requirement_validations", "relationships": { "address_requirement": { "data": { "type": "address_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/address_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"}}, "address_requirement": {"data": {"id": "c6f606d8-106a-43d6-997e-17c7da5ae5d7", "type": "address_requirements"}}, "identity": {"data": {"id": "beca16fb-0385-462f-9e2c-0d1918f6c8af", "type": "identities"}}}, "type": "address_requirement_validations"}}' ``` response ``` HTTP/1.1 201 Created Content-Type: application/vnd.api+json { "data": { "id": "e67bc7f0-71c1-451b-978e-d9188bcd39fa", "type": "address_requirement_validations" }, "meta": { "api_version": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] 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](#user-panel-api-examples-verification-step12). 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](../2026-04-16/regulation-resources/address-verifications/index.html#address-verifications-v34). *Basic verification* Use this structure when the registration requirement does **not** specify a one-time supporting document. [[DIDWW-API-EXAMPLE-START]] 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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] *Verification with one-time document* Use this structure **only** when the registration requirement retrieved in [Step 6](#user-panel-api-examples-verification-step6) defines a **one-time supporting document** under `personal_onetime_document` or `business_onetime_document`. [[DIDWW-API-EXAMPLE-START]] 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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] *Verification with service description* Use this structure when the registration requirement retrieved in [Step 6](#user-panel-api-examples-verification-step6) 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. [[DIDWW-API-EXAMPLE-START]] 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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] 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](../2026-04-16/callbacks-details.html#callbacks-details-v34) for more information. On this page