---
title: "Get phone numbers"
method: POST
path: "/api/v1/people/phones"
tags: ["People"]
---

# Get phone numbers

`POST /api/v1/people/phones`

## Request

- Base URL: `https://app.argorant.com`
- URL: `https://app.argorant.com/api/v1/people/phones`
- Auth: HTTP bearer

Add the direct dial or mobile number of up to 100 people you already found with search, reveal or enrich. Phone numbers are never included unless you ask for them. Each number that comes back costs 10 credits. People without a number cost nothing, and numbers your account already unlocked are free, whether that was in the app, the API, the command line or an AI connector. Phone numbers come with the Pro plan and higher. Every result says whether a number was returned and what it cost.

phone_status is returned (charged), already_unlocked (free), none_found (free), not_found (free), not_in_plan, not_enough_credits or daily_limit_reached. When the credits run out part way, the call still returns the numbers it could pay for and says where it stopped (stopped). If not a single number could be paid for, the answer is 402 insufficient_credits.

| Cost | What it does | Key scopes |
| --- | --- | --- |
| 10 credits per phone number returned; no number, no charge; numbers you already unlocked are free | Spends credits | `argorant:unlock_contacts` |

## Headers

- `Idempotency-Key` string
- `X-Request-Id` string

## Request body

- object
  - `record_ids` string[], required: Up to 100 person ids (record_id from search, reveal or enrich).

## Response `200`

OK

- object
  - `results` PhoneResult[], required
    - `record_id` string: The person's record id.
    - `full_name` string, nullable: Full name.
    - `phone` string, nullable: The main number, when handed over.
    - `additional_phones` string[]: More numbers, when handed over.
    - `phone_status` 'returned' | 'already_unlocked' | 'none_found' | 'not_found' | 'not_in_plan' | 'not_enough_credits' | 'daily_limit_reached': What happened for this person.
    - `credits_charged` integer: Credits charged for this person (10 for a new number, else 0).

## Other responses

- `401`: 401 Unauthorized. `unauthorized` when the API key is missing, wrong or revoked.
- `402`: 402 Payment required. `phones_not_in_plan` when phone numbers come with the Pro plan; nothing was charged; `insufficient_credits` when not a single number could be paid for.
- `403`: 403 Forbidden. `scope_missing` when the key lacks argorant:unlock_contacts.
- `409`: 409 Conflict. `idempotency_conflict` when the Idempotency-Key was used with another body.
- `422`: 422 Validation error. `validation_error` when a field has the wrong type or is missing.
- `429`: 429 Too many requests. `daily_limit_reached` when the key's daily reveal limit is used up; `rate_limited` when too many requests this minute.

---

[API](https://skmtc.dev/argorant/apis/argorant-api.md) · [All operations](https://skmtc.dev/argorant/apis/argorant-api/llms.txt) · [OpenAPI document](https://skmtc.dev/argorant/apis/argorant-api/revisions/4bc28c0085b6?raw)