API reference

Authentication

Create an API key in your account and copy the value shown once. Configure NOCALL_API_KEY as a secret on your server. Use HTTPS; never include the key in browser code, repositories, screenshots or logs.

Send the full key in Authorization: Bearer, with one space after Bearer. Do not use X-API-Key or put the key in the URL.

On /v1/data/* + /v2/*, a valid key replaces browser ByteGuard proof. Expiry, revocation, subscription, credits and rate limits still apply. It does not authorize other routes. openapi.json and products are public.

Authorization: Bearer <NOCALL_API_KEY>

• Create API key ↗

Your first lookup

All 44 tools are available through the API: call POST /v2/<tool-id>, or POST /v2/tools with the tool field in the body. Each tool has its own JSON body, documented in its guide. data.result contains the tool result. Use the identifiers in the table.

Generate a fresh Idempotency-Key for each new operation. Keep that key only to retry the same operation with the same input.

REQUEST_ID="$(uuidgen)" && [ -n "$REQUEST_ID" ] &&
curl --request POST 'https://api.nocall.io/v2/tools' \
  --header "Authorization: Bearer $NOCALL_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $REQUEST_ID" \
  --data '{"tool":"who-calls","phone":"+12025550123","country":"US"}'

import json
import os
import urllib.request
import uuid

api_key = os.environ.get('NOCALL_API_KEY')
if not api_key:
    raise SystemExit('Set NOCALL_API_KEY')

request = urllib.request.Request(
    'https://api.nocall.io/v2/tools',
    method='POST',
    data=json.dumps({'tool': 'who-calls', 'phone': '+12025550123', 'country': 'US'}).encode(),
    headers={
        'Authorization': 'Bearer ' + api_key,
        'Content-Type': 'application/json',
        'Idempotency-Key': str(uuid.uuid4()),
    },
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)
print(result['data']['result'], result['meta']['unitsCharged'])

import { randomUUID } from 'node:crypto';

const requestId = randomUUID();
const apiKey = process.env.NOCALL_API_KEY;
if (!apiKey) throw new Error('Set NOCALL_API_KEY');

const response = await fetch('https://api.nocall.io/v2/tools', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiKey,
    'Content-Type': 'application/json',
    'Idempotency-Key': requestId,
  },
  body: JSON.stringify({ tool: 'who-calls', phone: '+12025550123', country: 'US' }),
});
const result = await response.json();
if (!response.ok) throw new Error(result.error?.code ?? 'request_failed');
console.log(result.data.result, result.meta.unitsCharged);

API v2 · tools

All 44 tools are available through the API: call POST /v2/<tool-id>, or POST /v2/tools with the tool field in the body. Each tool has its own JSON body, documented in its guide. data.result contains the tool result. Use the identifiers in the table.

• OpenAPI v2 ↗

Available endpoints

Only reviewed or public technical facts are shown. Private identities and protection signals stay hidden.

API v1 · phone is required: a string of up to 64 characters, preferably in E.164 format. country is a supported two-letter country code; it is optional and defaults to ES. Content-Type must be application/json.

• OpenAPI 3.1 ↗

Responses

data contains the result; meta includes requestId, unitsCharged and usage where applicable. The synthetic excerpt shows the balance after one lookup. A valid not-found result also costs 1 credit; validation and provider errors and reading the balance are free. Missing data does not prove a number is safe. See OpenAPI for complete schemas.

{
  "data": {
    "tool": "who-calls",
    "result": {
      "phoneNumber": "+12025550123",
      "found": true,
      "updatedAt": "2026-10-01T09:30:00.000Z",
      "risk": {
        "score": 72,
        "level": "high"
      },
      "reportCount": 14,
      "categories": [
        "TELEMARKETING"
      ],
      "verified": false,
      "carrier": null,
      "verifiedBusiness": null
    }
  },
  "meta": {
    "requestId": "req_example",
    "unitsCharged": 1,
    "usage": {
      "periodStart": "2026-10-01",
      "unitLimit": 20,
      "unitsUsed": 3,
      "unitsRemaining": 17
    }
  }
}

• OpenAPI v2 ↗

Credits and limits

Each API call costs 1 credit. Monthly credits are used first.

Regenerating disables your previous keys. Your credit balance stays the same.

curl 'https://api.nocall.io/v1/data/account' \
  --header "Authorization: Bearer $NOCALL_API_KEY"

• API key and credits ↗

Retries and bulk lookups

Generate a fresh Idempotency-Key for each new operation. Keep that key only to retry the same operation with the same input.

Idempotency-Key is optional for single lookups and required for bulk: 8–128 characters (letters, digits, dots, hyphens, underscores or colons). When retrying, keep the same key, path, API key and body. A replay is not charged again. Check the balance before retrying an ambiguous response.

A batch accepts up to 50 inputs. product selects one of the operations listed in the example. There must be enough credits for all valid inputs before starting; only completed valid results are charged. Concurrent requests share the balance: if it runs out before the final debit, the request returns 429 without charging it.

8–128 ASCII: A–Z a–z 0–9 . _ : -
TTL: 24 h

phone-lookup
phone-risk
carrier-lookup
reverse-phone-lookup
phone-exposure

REQUEST_ID="$(uuidgen)" && [ -n "$REQUEST_ID" ] &&
curl --request POST 'https://api.nocall.io/v1/data/bulk-lookups' \
  --header "Authorization: Bearer $NOCALL_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $REQUEST_ID" \
  --data '{"product":"phone-risk","inputs":[{"phone":"+12025550123","country":"US"}]}'

Troubleshooting

Related guides

• Phone intelligence
• Phone risk
• Carrier lookup
• Has my number been leaked?
• Verified business reverse lookup