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

> [!NOTE]
>
> Public API v2 is in beta: v2 endpoints return `403` (`noFeatureAccess`) until Seamless enables v2 for your organization.

Each match carries a `searchResultId`. Send it to the [Contact Research API](https://docs.seamless.ai/api-catalog/contact-enrichment.md) 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](https://docs.seamless.ai/authentication/oauth.md). Create a key under [Settings → Public API](https://docs.seamless.ai/authentication/api-keys.md).

## Example

```bash Search 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"]}'
```

```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"]}'
```

For Python, JavaScript, and other languages, see [Search contacts (v2)](https://docs.seamless.ai/api-reference/v2/contact-search/search-contacts.md) in the API reference.

## Reference

| Parameter | Type | Required | Description |
| - | - | - | - |
| `phoneNumber` | string\[] | Yes | **Requires API v2.** Filter contacts by phone number. Accepts any format (e.g. "+1 (555) 123-4567"); non-digit characters are stripped automatically. Accepts a single phone number string or an array of phone numbers. |
| `limit` | integer | No | The maximum number of contacts to return per page. Must be a positive integer. A larger value is reduced to 500 rather than rejected. Default `50`. |
| `nextToken` | string | No | An opaque cursor token for retrieving the next page of results. Returned as `supplementalData.nextToken` in the previous response. |

Most list filters also have a per-account limit on how many values one request can send, which can be lower than any maximum above. A request over it returns `400` with `invalidArguments`, naming the filter and its limit.

You can combine `phoneNumber` with any [Contact Search filter](https://docs.seamless.ai/api-catalog/contact-search.md), 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 |
| `401` | Missing or invalid API key |
| `422` | `insufficientCredits` or `missingApiAccess` |
| `429` | Rate limit reached |

## Related

* [Email → Profile](https://docs.seamless.ai/api-catalog/email-to-profile.md)
* [LinkedIn URL → Profile](https://docs.seamless.ai/api-catalog/linkedin-to-profile.md)


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