Reverse Contact Reverse Contact
Sign Up

Find Phone

7 min read

Find a professional phone number from a LinkedIn URL or full name and company domain, then receive the result by webhook.

POST
Sign up to try

Introduction

The Find Phone endpoint discovers professional phone numbers for a person. You can identify the person with a LinkedIn profile URL, or with their full name and company domain. Processing is asynchronous: the API acknowledges the request with a webhookId, then you retrieve the result by polling (recommended, no public endpoint required) or through a webhook callback (advanced, push delivery).

Use this endpoint when you need a phone number for outreach or CRM enrichment. For push delivery, configure a workspace webhook URL in Settings > Webhooks, or provide webhookUrl in the request.

Note

Async, not real-time. We aim to deliver each result in under 15 seconds, but it can take tens of minutes depending on conditions. Built to update databases and feed async pipelines, not to back a synchronous request a user is waiting on. See Polling for delivery details.

Note

Lower coverage than email, billed only when found. Phone numbers are harder to source than email addresses, so expect fewer matches than with the Find Email endpoint. A lookup is billed 20 credits only when at least one phone number is found; a lookup that finds nothing costs 0 credits.

Authorization

apikey string required
Your API key from the developer dashboard. Pass it in the Authorization: Bearer YOUR_API_KEY header.

Request body

Choose one lookup strategy. Use either a LinkedIn profile URL, or a full name with a company domain. The split firstName + lastName form is also accepted.

url string conditional
Public LinkedIn profile URL, such as https://www.linkedin.com/in/janedoe. Use this for the URL strategy.
fullName string conditional
Person’s full name, such as Jane Doe. Use this with companyDomain.
firstName string conditional
Person’s first name. Use this with lastName and companyDomain instead of fullName.
lastName string conditional
Person’s last name. Use this with firstName and companyDomain instead of fullName.
companyDomain string conditional
Company domain, such as acme.com. Required for the name-based strategies.
webhookUrl string
HTTPS URL that receives the callback. Omit it to retrieve the result by polling instead.

Note

The request must contain url, or fullName + companyDomain, or firstName + lastName + companyDomain.

Response structure

This endpoint replies immediately with a webhookId. You then have two ways to retrieve the actual result:

  1. Polling (recommended). Call GET /v2/webhooks/:webhookId until the status is succeeded. No webhook URL needed. See the Polling guide.
  2. Webhook callback (advanced). If you provided a webhookUrl (or a workspace default is configured), the gateway POSTs the phone numbers to that URL once the lookup completes. See Webhook callback payload (advanced) below.
success boolean
true if the job was created successfully
dataobject
Initial job acknowledgement. Save the webhookId to retrieve the result via polling (GET /v2/webhooks/:webhookId) or to correlate an upcoming webhook callback (null on error responses).
Show child attributesHide child attributes
status string
Job status, always "created" for the initial response
webhookId string
Unique identifier (UUID). Save it. Use it to poll the result at GET /v2/webhooks/:webhookId, or to correlate an incoming webhook callback.
pollUrl string
Convenience hint pointing to the polling endpoint for this job (e.g. /v2/webhooks/{webhookId}).
error null
Always null on success
quotasobject
Credits and rate limit usage after this request
Show child attributesHide child attributes
creditsConsumed number
Credits consumed by this request
workspaceobject
Workspace-level limits
Show child attributesHide child attributes
id string
Your workspace identifier
hasUnlimitedCredits boolean
Whether workspace credits are unlimited
allowDailyOvercost boolean
Whether the workspace may exceed its daily cap
creditsobject
Credit balance
Show child attributesHide child attributes
total number
Total credits in your plan
used number
Credits consumed so far
left number
Remaining credits
dailyLimitobject
Daily request limit (null if not configured)
Show child attributesHide child attributes
limit number
Maximum requests per day
used number
Requests made today
left number
Remaining requests today
nextReset string
When the daily window resets (ISO 8601)
minuteRateLimitobject
Per-minute rate limit
Show child attributesHide child attributes
limit number
Maximum requests per minute
used number
Requests made in the current minute
left number
Remaining requests in the current minute
nextReset string
When the minute window resets (ISO 8601)
keyobject
API key-level limits (null when request is from dashboard)
Show child attributesHide child attributes
id string
API key identifier
dailyLimitobject
Daily limit for this key (null if not configured)
Show child attributesHide child attributes
limit number
Maximum requests per day
used number
Requests made today
left number
Remaining requests today
nextReset string
When the daily window resets (ISO 8601)
minuteRateLimitobject
Minute rate limit for this key
Show child attributesHide child attributes
limit number
Maximum requests per minute
used number
Requests made in the current minute
left number
Remaining requests in the current minute
nextReset string
When the minute window resets (ISO 8601)
metadataobject
Request tracking information
Show child attributesHide child attributes
requestId string
Unique identifier for this request
executionTimeMs number
Total execution time in milliseconds

Webhook callback payload (advanced)

When the lookup succeeds, ReverseContact sends a JSON POST request to your webhookUrl. The callback is not wrapped in the V2 response envelope. It always includes the webhookId from the initial acknowledgement and a data value.

Success payload
Webhook callback (success)
{
  "webhookId": "b8c9d0e1-f2a3-4b4c-5d6e-7f8091a2b3c4",
  "data": [
    {
      "value": "+33612345678",
      "type": "mobile"
    }
  ]
}
dataobject
One entry per phone number discovered for the person.
Show child attributesHide child attributes
value string
The discovered phone number, in the format reported by the provider (usually E.164)
type string | null
Phone kind reported by the provider, such as mobile; null when the provider gives no kind

Webhook callback errors (advanced)

When the lookup cannot return a phone number, data is not an array. Instead, it contains an errorCode identifying the failure reason:

Error payload
Webhook callback (error)
{
  "webhookId": "b8c9d0e1-f2a3-4b4c-5d6e-7f8091a2b3c4",
  "data": {
    "errorCode": "phone-not-found"
  }
}

data.errorCode will be one of the following values:

Code Billed Description
phone-not-found No No phone number was discovered for the person
person-not-found No No matching person was found for the supplied identifiers
invalid-request No The lookup input is malformed or does not match an accepted form
fetch-data-error No The lookup failed while fetching data; safe to retry
webhook-url-invalid Yes The callback URL returned a 4xx response
webhook-url-errored Yes The callback URL returned a 5xx response or a network error
webhook-url-timeout Yes The callback URL did not respond in time
webhook-url-unreachable Yes The callback URL could not be reached

Note

The lookup costs 20 credits only when at least one phone number is found. A lookup that returns phone-not-found, person-not-found, invalid-request, or fetch-data-error costs 0 credits. A delivery failure remains billed when a phone number was successfully found.

Previous

Find Email

Next

Usage