# 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](get-verification-status.html#otp-verification-api-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](index.html#otp-verification-object-reference) 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](get-verification-status.html#otp-verification-retention). |

See [Errors and status codes](errors.html#otp-verification-api-errors) for the error response
structure and available error codes. See
[Get verification status](get-verification-status.html#otp-verification-api-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](get-verification-status.html#otp-verification-retention).
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](../authentication.html#otp-verification-authentication) for credential and header
requirements.

The SDK examples assume that the corresponding SDK is installed and initialized. See the
[Ruby](../sdks/ruby.html#otp-verification-sdk-ruby),
[Python](../sdks/python.html#otp-verification-sdk-python),
[Node.js](../sdks/node.html#otp-verification-sdk-node),
[PHP](../sdks/php.html#otp-verification-sdk-php),
[iOS](../sdks/ios.html#otp-verification-sdk-ios),
[Android](../sdks/android.html#otp-verification-sdk-android),
[React Native](../sdks/react-native.html#otp-verification-sdk-react-native), and
[Dart](../sdks/dart.html#otp-verification-sdk-dart) SDK pages.

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:05:00.000Z",
    "sms": {
      "template": "Your code is {{CODE}}",
      "language": "en-US",
      "interception_timeout": 300,
      "code_length": 6
    }
  }
}
```

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.

### Python SDK

The Python SDK sends the by-number `GET` request when `get_verification_by_number(...)`
is called. It percent-encodes the number for the path and returns a `Verification`
containing the current state.

```
verification = client.get_verification_by_number("+4915112345678")

verification.id           # "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21"
verification.status       # "pending"
verification.is_finished  # False
```

The call resolves to the **newest** verification for the number, finished ones included. A
start that is itself denied does not supersede an earlier live verification, so this read can
return the denied record while the live one remains reachable only by its ID. Keep the ID
from the start response where you can.

### Node.js SDK

The Node.js SDK sends the by-number `GET` request when `getVerificationByNumber(...)` is
called and returns the decoded verification.

```
const current = await client.getVerificationByNumber('+4915112345678');

current.id;     // '0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21'
current.status; // 'pending'
```

It returns the newest verification for the number whatever its status, and rejects with a
`404` `ApiError` when none is within the
[retention period](get-verification-status.html#otp-verification-retention).

### PHP SDK

The PHP SDK sends the by-number `GET` request when `getVerificationByNumber(...)` is
called. It sends only the digits of the number in the path and returns a `Verification`
containing the current state.

```
$verification = $client->getVerificationByNumber('+4915112345678');

$verification->id;           // "0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21"
$verification->status;       // "pending"
$verification->isFinished(); // false
```

The call resolves to the **newest** verification for the number, finished ones included. A
start that is itself denied does not supersede an earlier live verification, so this read can
return the denied record while the live one remains reachable only by its ID. Keep the ID
from the start response where you can.

### 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`.

### Dart SDK

The Dart SDK sends the by-number `GET` request when `getVerificationByNumber(...)` is
called and returns a `Verification` containing the current state.

```
final current = await client.getVerificationByNumber('+4915112345678');

current.id;          // '0f9c8b7a-1e2d-4c3b-9a8f-7e6d5c4b3a21'
current.knownStatus; // VerificationStatus.pending
current.isFinished;  // false
```

`getVerificationByNumber` returns the newest verification for a number whatever its status.

With `VerificationSession`, call `session.resumeByNumber(destination)` instead: it
performs the same request and publishes the result as a state, so a screen does not have to
branch on the response itself.

### React Native SDK

The React Native SDK looks a number up through the `useVerification()` controller. The
result arrives as a state rather than a return value:

```
controller.resume({ destination: '+4915112345678', deliveryMethod: 'sms' });

// state.kind becomes 'awaitingInput' for a live verification, or the terminal
// state of the one that was found.
```

`controller.resumeById({ verificationId, deliveryMethod })` is the same flow addressed by
ID. The `deliveryMethod` argument selects channel-specific client behavior, including
automatic SMS capture on Android; the delivery method returned by the API remains
authoritative.

On this page