> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seamless.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone → Profile

> Reverse-look up a phone number to find the person behind it, then enrich them to a full profile with emails and job history.

> [!NOTE]
>
> **Endpoint** `POST /v2/search/contacts` with `phoneNumber` · **Credits** charged per results returned · **Version** v2 only

## Introduction

Send up to 100 phone numbers in any format and get back the matching people: name, title, company, seniority, location, and LinkedIn URL. Use it to identify inbound callers, de-anonymize call-tracking numbers, and fill missing names in your CRM.

Each match carries a `searchResultId`. Send it to the [Contact Research API](/api-catalog/contact-enrichment) to unlock emails, more phone numbers, and job history.

## AI agent prompt

```text theme={null}
Read https://docs.seamless.ai/llms.txt and https://docs.seamless.ai/api-catalog/phone-to-profile.
Using my Seamless.AI API key from SEAMLESS_API_KEY, call
POST https://api.seamless.ai/api/client/v2/search/contacts with {"phoneNumber": [<numbers>]}.
For each match, print the phone, fullName, jobTitle, companyName, and searchResultId.
```

## Authentication

Send your API key in the `Token` header, or `Authorization: Bearer <token>` with [OAuth](/authentication/oauth). Create a key under [Settings → Public API](/authentication/api-keys).

## Example

```bash cURL theme={null}
curl -X POST https://api.seamless.ai/api/client/v2/search/contacts \
  -H "Token: $SEAMLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": ["+1 (555) 123-4567", "5125550100"] }'
```

```python Python theme={null}
import os, requests

resp = requests.post(
    "https://api.seamless.ai/api/client/v2/search/contacts",
    headers={"Token": os.environ["SEAMLESS_API_KEY"]},
    json={"phoneNumber": ["+1 (555) 123-4567"]},
)
for person in resp.json()["data"]:
    print(person["fullName"], person["jobTitle"], person["companyName"], person["searchResultId"])
```

```javascript Node.js theme={null}
const resp = await fetch("https://api.seamless.ai/api/client/v2/search/contacts", {
  method: "POST",
  headers: { Token: process.env.SEAMLESS_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ phoneNumber: ["+1 (555) 123-4567"] }),
});
const { data } = await resp.json();
```

```bash Then enrich theme={null}
curl -X POST https://api.seamless.ai/api/client/v2/contacts/research \
  -H "Token: $SEAMLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "searchResultIds": ["SEARCH_RESULT_ID"] }'
```

## Reference

| Parameter | Type | Required | Description |
| - | - | - | - |
| `phoneNumber` | string or string\[] | Yes | Up to 100 phone numbers in any format. Non-digit characters are stripped. |
| `limit` | integer | No | Results per page, up to 500. Default `50`. |
| `nextToken` | string | No | Cursor for the next page. |

You can combine `phoneNumber` with any [Contact Search filter](/api-catalog/contact-search), for example `companyDomain` to confirm the employer.

## Response

Each row in `data` is a contact preview: `searchResultId`, `fullName`, `jobTitle`, `seniority`, `department`, `companyName`, `domain`, `city`, `state`, `country`, `liUrl`, and company size and revenue. A number with no match returns no row and costs nothing.

## Errors

| Status | Meaning |
| - | - |
| `400` | Invalid request, such as more than 100 numbers |
| `401` | Missing or invalid API key |
| `422` | `insufficientCredits` or `missingLicense` |
| `429` | Rate limit reached |

## Related

* [Email → Profile](/api-catalog/email-to-profile)
* [LinkedIn URL → Profile](/api-catalog/linkedin-to-profile)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.