Search Endpoint

POST /callerid/search

Searches for information about a phone number using multiple data sources.

Request

URL: /callerid/search

Method: POST

Content-Type: application/json

Body:

{
  "api_key": "your-jwt-token",
  "query": "34600000001"
}

Parameters

Parameter	Type	Required	Description
api_key	string	Yes	JWT authentication token
query	string	Yes	Phone number without the + symbol (e.g., 34600000001)

Response

Status Code: 200 OK

Body:

{
  "success": true,
  "data": {
    "phone_number": "34600000001",
    "callapp": {
      // Callapp results
    },
    "truecaller": {
      // Truecaller results
    },
    "combined": {
      "callapp_available": true,
      "truecaller_available": true
    }
  },
  "credits_remaining": 9
}

Error Codes

Code	Description
400	Invalid phone number (must contain only digits)
401	Invalid or missing token
403	No credits remaining
429	Rate limit exceeded (maximum 30 requests per minute)
500	Internal server error

Example with cURL

curl -X POST "https://api.callerosint.org/callerid/search" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your-jwt-token",
    "query": "34600000001"
  }'

Example with Python

import requests

url = "https://api.callerosint.org/callerid/search"
payload = {
    "api_key": "your-jwt-token",
    "query": "34600000001"
}

response = requests.post(url, json=payload)
data = response.json()

print(f"Credits remaining: {data['credits_remaining']}")
print(f"Results: {data['data']}")

Notes

• The phone number must be sent without the + symbol
• Expected format: country code + number (e.g., 34600000001)
• Each search consumes one credit from the token
• Results include information from multiple sources when available