---
title: "Phone Finder"
method: POST
path: "/v1/phones/find"
tags: ["Suprsonic"]
---

# Phone Finder

`POST /v1/phones/find`

## Request

- Base URL: `https://suprsonic.ai`
- URL: `https://suprsonic.ai/v1/phones/find`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/suprsonic/apis/suprsonic-unified-agent-api/docs/v1/phones/find/post.ts> (a function with typed inputs; its response is checked against the schema)

Find a person's direct phone numbers. Returns the number to call first (the mobile when one is found) in international form, its line type and country, and every other usable number found. Charged only for a number found: the full price for a mobile, 1 credit when only an office or VoIP line turns up. Use to reach a named person by phone. A search takes 30 to 90 seconds; one still running answers is_retriable, and calling again with the same input collects it without a second search. For their work email use emails; for who they are use profiles. Calling the number is the caller's own outreach, under the rules for unsolicited calls of the person's country. Pass linkedin_url (finds the most), or first_name and last_name with domain or company. Cost: 87 credits, charged only when a call succeeds.

## Request body

- PhoneFindRequest
  - `linkedin_url` string, nullable
  - `first_name` string, nullable
  - `last_name` string, nullable
  - `domain` string, nullable
  - `company` 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-09** `72d14d8e0a1b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/suprsonic/apis/suprsonic-unified-agent-api/changes/v1/phones/find/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/72d14d8e0a1b?raw)