Get verification status by number#

Retrieve the latest verification associated with a phone number. Use this endpoint when your application has the destination number but did not store the verification id returned by the start request.

The lookup only reads the verification. It does not create a new verification, change its state, or consume a report attempt. To retrieve a specific verification by its id, use Get verification status.

Request#

HTTP method: GET

Path: /api/v1/verifications/by_number/{number}

Path parameters#

Name	Type	Description
`number`	`string`	Destination phone number in E.164 format. The leading `+` is optional. When the leading `+` is included in the URL path, percent-encode it as `%2B`.

Response#

When a verification is found, the endpoint returns 200 OK with the verification object under a top-level data key. Authentication and lookup errors return an errors array.

The following table lists the HTTP status codes returned by this endpoint:

Status	Meaning
`200 OK`	A verification was found for the specified number. Inspect `status`, `error_code`, and `error_detail` to determine its current state and outcome.
`401 Unauthorized`	Authentication failed, credentials are missing or invalid, or the authentication mode is below the minimum configured for the OTP application.
`404 Not Found`	No verification exists for the specified number under the OTP application, either because none was started or because the records passed the retention period.

See Errors and status codes for the error response structure and available error codes. See Get verification status for status meanings and terminal-state guidance.

Which verification is returned#

The lookup is scoped to the authenticated OTP application and returns the most recently created verification for the number, whatever its status. It resolves by recency alone and does not search for an active verification.

A finished verification is therefore returned whenever it is the newest record for the number, and remains available for the retention period. Starting another verification for the same number makes later by-number lookups resolve to the newer record.

A newer record can also be a verification that was denied at start. A denied start does not supersede anything, so it becomes the newest record while an earlier verification for the same number is still pending, and the by-number lookup returns the denied one. Read status and id from the response rather than assuming the returned verification is the live one.

Note

Use the by-id endpoint when you must retrieve one specific verification. A by-number lookup can resolve to a different record after another verification is started for the same application and phone number.

Examples#

The REST API example uses HTTP Basic authentication. See REST API authentication for credential and header requirements.

The SDK examples assume that the corresponding SDK is installed and initialized. See the Ruby SDK, iOS SDK, and Android SDK.

The identifier, expiration time, and fee shown in the examples are illustrative.

REST API#

Send a GET request with the destination number in the path. The following example omits the leading + so no path encoding is required:

http

GET /api/v1/verifications/by_number/4915112345678 HTTP/1.1
Host: verification.didww.com
Accept: application/json
Authorization: Basic eW91cl9hcHBfa2V5OnlvdXJfYXBwX3NlY3JldA==

curl

curl -i -X GET https://verification.didww.com/api/v1/verifications/by_number/4915112345678 -H "Accept: application/json" --user your_app_key:your_app_secret

response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21",
    "destination": "4915112345678",
    "delivery_method": "sms",
    "fee": "0.06",
    "status": "pending",
    "error_code": null,
    "error_detail": null,
    "expires_at": "2026-07-15T10:02:00.000Z",
    "sms": {
      "template": "Your code is {{CODE}}",
      "language": "en-US",
      "interception_timeout": 120
    }
  }
}

The request is the same for every delivery method. Phone call responses do not include an sms object.

Ruby SDK#

The Ruby SDK sends the by-number GET request when get_verification_by_number(...) is called. It handles path encoding and returns a verification object containing the current state.

verification = client.get_verification_by_number(
  "+4915112345678"
)

verification.id        # => "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21"
verification.status    # => "pending"
verification.pending?  # => true
verification.finished? # => false

Use finished? to determine whether the returned verification has reached a final status.

iOS SDK#

The iOS SDK sends the by-number GET request when status(number:) is called and returns a VerificationResult. It normalizes the supplied number to digits before building the request path.

let current = try await client.status(
    number: "+49 151 1234 5678"
)

current.id                // "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21"
current.status            // .pending
current.status.isTerminal // false

If the supplied value contains no digits, the SDK throws VerificationError.invalidNumber before sending a request.

Android SDK#

Use resume(...) to look up the verification associated with a number and return a new VerificationHandle for it. Calling resume(...) does not send the request. The SDK sends the by-number GET request when handle.states is first collected.

SMS

val handle = didww.resume(
    destination = "+4915112345678",
    method = DeliveryMethod.SMS,
)

Phone call

val handle = didww.resume(
    destination = "+4915112345678",
    method = DeliveryMethod.CALLOUT,
)

Collect the returned handle exactly once:

viewModelScope.launch {
    handle.states.collect { state ->
        when (state) {
            is VerificationState.AwaitingInput ->
                println("pending: ${state.verificationId}")
            is VerificationState.Verified ->
                println("verified: ${state.verificationId}")
            is VerificationState.Failed ->
                println("lookup or verification failed: ${state.reason}")
            VerificationState.Expired ->
                println("expired")
            is VerificationState.Denied ->
                println("denied")
            is VerificationState.SetupError ->
                println("configuration error: ${state.code}")
            else -> Unit
        }
    }
}

For an unfinished verification, the flow emits VerificationState.AwaitingInput and the handle can continue accepting submitted values. If the resolved verification has already finished, the flow emits its terminal state. If no verification exists for the number, it emits VerificationState.Failed with ApiErrorCode.NOT_FOUND.

The method argument selects the channel-specific client behavior, including automatic SMS capture. The delivery method returned by the API remains authoritative and is exposed through VerificationState.AwaitingInput.deliveryMethod.