---
title: "Phone Validation"
method: POST
path: "/v1/phones/verify"
tags: ["Suprsonic"]
---

# Phone Validation

`POST /v1/phones/verify`

## Request

- Base URL: `https://suprsonic.ai`
- URL: `https://suprsonic.ai/v1/phones/verify`
- Auth: HTTP bearer

Check whether a phone number is valid and in service, its line type and carrier. Returns the status (valid when a carrier holds the number, invalid when it is malformed, outside its country's numbering plan, held by no carrier or not in service, unknown when its carrier data is withheld) with a sub-status, the number in international and national form, its country, line type (mobile, landline, fixed_voip, non_fixed_voip, toll_free and others), carrier, the network's line status and whether the handset is reachable now (null where the network does not say). A number its country's numbering plan rules out is answered free. Use before calling or texting a number you were given or found, or to sort a list of numbers into mobiles, landlines and VoIP. To find a person's number use phones. Pass number in international form (+ and its country code), or a national number with country. Cost: 3 credits, charged only when a call succeeds.

## Request body

- PhoneVerifyRequest
  - `number` string, required
  - `country` string, nullable

## Response `200`

The call's envelope: success, data (the capability's result), metadata, and credits_used (0 when the call did not succeed).

- UnifiedResponse: Standard envelope for all unified API responses.
  - `success` boolean, required
  - `data` union
    - object
    - unknown[]
      - unknown
  - `error` UnifiedError: RFC 7807 problem detail for machine-actionable errors.
    - `type` string, required
    - `title` string, required
    - `status` integer, required
    - `detail` string, nullable
    - `is_retriable` boolean
    - `retry_after_seconds` integer, nullable
    - `alternative_action` string, nullable
    - `error_category` string
    - `caller_error` string, nullable
  - `metadata` UnifiedMetadata: Metadata included in every unified API response.
    - `provider_used` string, nullable
    - `providers_tried` string[]
    - `mode_used` string, nullable
    - `response_time_ms` integer
    - `request_id` string
    - `capability` string, nullable
    - `params` object, nullable
  - `credits_used` integer

## Other responses

- `401`: No API key, or one that was not found or is revoked.
- `402`: Not enough credits for this call. The error's alternative_action says where to add them.
- `403`: The account is restricted by a billing issue.
- `422`: Validation Error
- `429`: The key's rate limit is reached. The error's retry_after_seconds says when to try again.

## Changes

- **2026-11-16** `35e02ceb4f3d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/suprsonic/apis/suprsonic-unified-agent-api/changes/v1/phones/verify/post.md)

---

[API](https://skmtc.dev/suprsonic/apis/suprsonic-unified-agent-api.md) - [All operations](https://skmtc.dev/suprsonic/apis/suprsonic-unified-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/suprsonic/apis/suprsonic-unified-agent-api/revisions/35e02ceb4f3d?raw)
