Emergency Verifications

Use the Emergency Verifications resource to submit emergency calling registration data for review and monitor the result.

An Emergency Verification links a validated Address either to one or more DIDs for a new Emergency Calling Service or to an existing service whose registered address must be replaced. The verification records its reference, review status, rejection details, callback settings, creation time, external reference ID, and related resources.

All Emergency Verifications are reviewed by the DIDWW Emergency Team. A newly created verification has a pending status and later becomes approved or rejected. You can retrieve the verification to monitor its status or configure a callback when creating it.

Note

For the complete registration and service-management workflow, see Emergency Resources. For complete examples, see Register Emergency Calling Service and Update Emergency Calling Service.

Before creating a verification

• Confirm that the account has an emergency calling plan. Creation returns 403 Forbidden when no plan is assigned.

• Use Retrieve All DIDs to select active DIDs whose DID Groups support the emergency feature.

• For a new service, confirm that the selected DIDs use the same country and DID Group Type and are not assigned to another Emergency Calling Service.

• Retrieve the applicable Emergency Requirement using the selected country ID and DID Group Type ID.

• Create or reuse an Identity and Address that satisfy the Emergency Requirement. If a DID already has approved end-user registration, use an Address linked to the same Identity.

• Use Emergency Requirement Validation to identify missing or invalid Identity and Address data before submission.

• Choose either New Calling Service or Existing Calling Service mode. Do not combine the relationships used by the two modes.

Endpoints

Action	Method	Endpoint
Retrieve all Emergency Verifications	GET	/v3/emergency_verifications
Retrieve Emergency Verification	GET	/v3/emergency_verifications/{id}
Create Emergency Verification	POST	/v3/emergency_verifications
Update Emergency Verification	PATCH	/v3/emergency_verifications/{id}

Retrieve all Emergency Verifications

Retrieves all Emergency Verifications associated with the account.

Use this endpoint to monitor multiple verification tasks. Results can be filtered by status, Emergency Calling Service ID, or external reference ID and sorted by creation time or external reference ID. The related Address, Emergency Calling Service, and DIDs can be included in the response.

See Retrieve All Emergency Verifications.

GET /v3/emergency_verifications

Retrieve Emergency Verification

Retrieves a specific Emergency Verification by its unique ID.

Use this endpoint to inspect the current status and reference. For a rejected verification, review reject_reasons and reject_comment to determine what must be corrected. The related Address, Emergency Calling Service, and DIDs can be included in the response.

See Retrieve Emergency Verification.

GET /v3/emergency_verifications/{id}

Create Emergency Verification

Creates an Emergency Verification and submits it for review. A successful request returns 201 Created with a verification whose initial status is pending.

Choose the creation mode from the action you need to perform:

Mode	Relationships to provide	Result
New Calling Service	Provide address and one or more dids. Do not provide emergency_calling_service.	Creates a new Emergency Calling Service automatically and submits its registration for review.
Existing Calling Service	Provide address and emergency_calling_service. Do not provide dids.	Resubmits a rejected service or submits a replacement address for an existing service.

You can also provide:

• external_reference_id to associate the verification with a record in an external system. Its maximum length is 100 characters.

• callback_url to receive the final review result.

• callback_method set to get or post. It is required when callback_url is provided.

See Create Emergency Verification.

POST /v3/emergency_verifications

Update Emergency Verification

Updates the external_reference_id of a specific Emergency Verification.

No other verification attributes or relationships can be changed with this endpoint. The external reference ID is optional and has a maximum length of 100 characters.

See Update Emergency Verification.

PATCH /v3/emergency_verifications/{id}

Creation modes and service effects

New Emergency Calling Service

Use this mode when the selected DIDs are not assigned to an Emergency Calling Service. Provide the validated Address and at least one DID. The service is created automatically and is linked in the successful verification response.

If the verification is approved, the Emergency Calling Service becomes active and emergency routing is enabled for its DIDs. If it is rejected, the service becomes changes_required. Correct the rejected data and create a new verification in Existing Calling Service mode.

Important

Do not create an Order to purchase emergency calling. When the Emergency Calling Service is activated, DIDWW creates its related Order automatically and triggers the related Order callback.

Existing Emergency Calling Service

Use this mode to resubmit a service in changes_required or to replace the registered address of a service whose status is new or active. Provide the replacement Address and existing Emergency Calling Service. Do not provide DIDs in this mode.

For an active service, its status becomes pending_update during review. Emergency routing remains enabled with the current address. The replacement address takes effect only if the verification is approved and the service returns to active.

The request returns 422 Unprocessable Entity if the service status is in_process, pending_update, or canceled.

Common creation errors

A 422 Unprocessable Entity response can identify one or more issues that must be fixed, including:

• No DIDs were supplied in New Calling Service mode.

• A matching emergency plan rate was not found.

• The selected DIDs do not share the same DID Group Type.

• A DID does not support the emergency feature.

• A DID that requires city-level data is not linked to a City ID.

• A DID is already assigned to another Emergency Calling Service.

• The Address or its Identity does not satisfy the applicable Emergency Requirement.

• A DID with approved end-user registration is submitted with an Address linked to a different Identity.

Use Emergency Requirement Validation before creation to detect Identity and Address problems early. DID-specific and rate checks are still applied when the Emergency Verification is created.

Verification statuses

Status	Meaning
pending	The verification has been submitted and is awaiting a decision from the DIDWW Emergency Team.
approved	The submitted emergency registration data has been approved.
rejected	The submitted data was not approved. Inspect reject_reasons and reject_comment for details.

Callbacks

When a callback is configured, DIDWW sends a notification after the verification becomes approved or rejected. The payload contains the verification ID, resource type, status, rejection information, and related Emergency Calling Service ID.

A get callback sends the payload as query parameters. A post callback sends it as application/x-www-form-urlencoded data. See Callbacks Details for all parameters and request-signature validation.

Data reference

See Emergency Verification Object for all attributes and relationships returned by the resource.

Common Emergency Verification use cases

Use case	Description
Create an emergency service	Submit a validated Address and compatible DIDs in New Calling Service mode.
Resubmit rejected data	Correct the reported problems and create a new verification for the service in changes_required.
Replace a registered address	Submit a validated replacement Address for an existing service and monitor its pending_update state.
Monitor review progress	Filter verifications by status or Emergency Calling Service ID, or retrieve a specific verification.
Resolve a rejection	Inspect reject_reasons and reject_comment to determine which data must be corrected before resubmission.
Receive status notifications	Configure a callback to receive the approved or rejected result without polling.
Reconcile external records	Create, filter, sort, or update verifications using external_reference_id.

Related resources

• Emergency Resources — Follow the complete emergency calling registration and service-management workflow.

• Emergency Requirements — Determine and validate the Identity and Address rules for the selected DIDs.

• Emergency Calling Services — Retrieve the service created or updated by the verification.

• Addresses — Create or retrieve the emergency location submitted for review.

• Identities — Manage the Identity linked through the submitted Address.

• DIDs — Select compatible phone numbers and manage their Emergency Calling Service assignments.

• Orders — Retrieve the Order created automatically when the Emergency Calling Service is activated.

• Callbacks Details — Process Emergency Verification and related Order status notifications.