Create Emergency Verification#

Creates a new emergency verification, either for a new Emergency Calling Service or for resubmitting a rejected or updating an existing one.

Request#

HTTP Method: POST

URI Path: /v3/emergency_verifications

Request Body Object Attributes#

Name

Type

Is Required?

Description

callback_url

string

No

The HTTP or HTTPS endpoint to where events related to the verification will be delivered.

callback_method

string

No

The callback method used for verification events. Supported methods: post, get. Required when callback_url is provided.

external_reference_id

string

No

Optional identifier for the emergency verification in the customer’s external system. Maximum length is 100 characters.

See Emergency Verification callback details for information about callback_url, callback_method, and the callback payload.

Request Body Object Relationships#

Title

Type

Description

address

Addresses

Specifies the emergency address ID.

dids

DID

Specifies the DID IDs for a new Emergency Calling Service. At least one DID is required when emergency_calling_service is not provided.

emergency_calling_service

Emergency Calling Service

Specifies the existing Emergency Calling Service ID when resubmitting or updating the address of an existing service.

Note

  • New Calling Service mode uses address and dids relationships and does not send emergency_calling_service.

  • Existing Calling Service mode uses emergency_calling_service and address relationships and does not send dids.

  • Address updates are allowed only when the Emergency Calling Service status is new, changes_required, or active.

  • Requests return 422 when the Emergency Calling Service is in pending_update, in_process, or canceled status.

Examples#

http

 1POST /v3/emergency_verifications HTTP/1.1
 2Host: api.didww.com
 3Content-Type: application/vnd.api+json
 4Accept: application/vnd.api+json
 5Authorization: Bearer [access token]
 6
 7{
 8    "data": {
 9        "type": "emergency_verifications",
10        "attributes": {
11            "callback_url": "https://example.com/callbacks/emergency",
12            "callback_method": "post"
13        },
14        "relationships": {
15            "address": {
16                "data": {
17                    "id": "49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0",
18                    "type": "addresses"
19                }
20            },
21            "dids": {
22                "data": [
23                    {
24                        "id": "f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c",
25                        "type": "dids"
26                    },
27                    {
28                        "id": "a2b3c4d5-e6f7-8901-abcd-ef1234567890",
29                        "type": "dids"
30                    }
31                ]
32            }
33        }
34    }
35}

curl

1curl -i -X POST https://api.didww.com/v3/emergency_verifications -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"callback_method": "post", "callback_url": "https://example.com/callbacks/emergency"}, "relationships": {"address": {"data": {"id": "49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0", "type": "addresses"}}, "dids": {"data": [{"id": "f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c", "type": "dids"}, {"id": "a2b3c4d5-e6f7-8901-abcd-ef1234567890", "type": "dids"}]}}, "type": "emergency_verifications"}}'

response

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

Other Responses#

Code

Success

Description

400

No

Bad Request

401

No

Unauthorized

403

No

Forbidden. Emergency calling is not enabled for the account. Also returned when the access token carries the read scope, which does not cover this method (title Insufficient scope, WWW-Authenticate: Bearer error="insufficient_scope"). See Scopes.

422

No

Validation Error Object. The submission was rejected.

429

No

The request budget of the account for the current window is spent (too_many_requests). Retry-After gives the number of seconds to wait.