post /v2/reveal/phones

Reveal phones

Get phones and phone statuses for people.

Webhook result: Documentation
Endpoint POST /v2/reveal/phones
Credit cost 10 credits / phone found (not charged when no number returned)
Response Asynchronous — results delivered to your webhook
Max per request 500 person IDs

Quickstart#

curl -X POST "https://api.ocean.io/v2/reveal/phones" \
  -H "X-Api-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "personIds": ["abc123", "def456"],
    "webhookUrl": "https://yourapp.com/webhooks/ocean-phones"
  }'
import requests

response = requests.post(
    'https://api.ocean.io/v2/reveal/phones',
    headers={'X-Api-Token': 'YOUR_API_TOKEN'},
    json={
        'personIds': ['abc123', 'def456'],
        'webhookUrl': 'https://yourapp.com/webhooks/ocean-phones',
    },
)
data = response.json()  # {"status": "in progress"} — results arrive at your webhook
const response = await fetch('https://api.ocean.io/v2/reveal/phones', {
  method: 'POST',
  headers: { 'X-Api-Token': 'YOUR_API_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    personIds: ['abc123', 'def456'],
    webhookUrl: 'https://yourapp.com/webhooks/ocean-phones',
  }),
});
const data = await response.json(); // {"status": "in progress"} — results arrive at your webhook

Immediate response:

{ "status": "in progress" }

Webhook payload:

{
  "results": [
    {
      "personId": "abc123",
      "phone": { "numbers": ["+4512345678", "+4587654321"], "status": "verified" }
    },
    {
      "personId": "def456",
      "phone": { "numbers": [], "status": "notFound" }
    }
  ]
}

Numbers are returned in E.164 international format (e.g., "+4512345678"), compatible with most telephony and CRM systems. A person may have multiple numbers — the numbers field is always an array.

Authorizations

apiToken string
x-api-token string

Body application/json

List of Ocean person ids to fetch the phone data for. One phone credit will be charged for every verified phone found.
Array of string
webhookUrl string Required
Url of the webhook the phone data should be sent to, when completed.

Responses

200 Successful Response
status enum Required
Status of the request. `"in progress"` if any phone has to be verified in the background. All the phone results are sent to the webhook once they are all done.
"in progress""webhook sent"
400 Bad Request
detail enum Required
"Conflicting API tokens provided in query parameters and headers"
402 Payment Required
detail enum Required
"Insufficient phone credits"
403 Forbidden
detail enum Required
"API token should be provided in headers or query parameters""Current API token is not registered in our database"
404 Not found
422 Validation Error
Array of ValidationError
Array of string | integer
string | integer
msg string Required
type string Required
input any
object

FAQs#

Am I charged if no phone is found?

No. You are only charged per number actually returned. Empty numbers = no charge.

Where do I get person IDs?

From the id field in Search People or Enrich Person responses.