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

New Calling ServiceExisting Calling ServiceVerification ErrorDID Validation Error

http

POST /v3/emergency_verifications HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Api-Key: [API token]

{
    "data": {
        "type": "emergency_verifications",
        "attributes": {
            "callback_url": "https://example.com/callbacks/emergency",
            "callback_method": "post"
        },
        "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"
                    }
                ]
            }
        }
    }
}

curl

curl -i -X POST https://api.didww.com/v3/emergency_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/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

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
    "data": {
        "id": "89c0164e-752f-4995-a0fa-0ced21e60e4a",
        "type": "emergency_verifications",
        "attributes": {
            "reference": "SHB-485120",
            "status": "pending",
            "reject_reasons": [],
            "reject_comment": null,
            "callback_url": "https://example.com/callbacks/emergency",
            "callback_method": "post",
            "created_at": "2026-03-20T12:20:04.584Z",
            "external_reference_id": "test"
        },
        "relationships": {
            "address": {
                "data": {
                    "id": "49f09b7f-c5bf-4c90-bac1-a8b335d2c3f0",
                    "type": "addresses"
                }
            },
            "emergency_calling_service": {
                "data": {
                    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                    "type": "emergency_calling_services"
                }
            },
            "dids": {
                "data": [
                    {
                        "id": "f10d40c7-fd0b-4d63-bb9b-27810a1a8f5c",
                        "type": "dids"
                    },
                    {
                        "id": "a2b3c4d5-e6f7-8901-abcd-ef1234567890",
                        "type": "dids"
                    }
                ]
            }
        }
    },
    "meta": {
        "api_version": "2026-04-16"
    }
}

Other Responses

Code	Success	Description
400	No	Invalid resource for earlier API versions.
401	No	Unauthorized
403	No	Forbidden. Example detail: Emergency plan is not assigned to the customer.