Get started
API quickstart
Coverage: 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.
API key and creditsOn this page
Get your API key
You need credits: the 20 a month included with an active Pro account, or credits bought on your account page. An account with neither receives 403 pro_required.
This key is shown only once. Save it securely on your server.
The API requires an active Pro account. In your account, create an API key and copy it: it is shown only once. Store it as the NOCALL_API_KEY secret on your server, never in browser code.
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.
Your first request
Send POST /v2/tools with the Authorization: Bearer header and a JSON body with tool and phone, for example the who-calls tool. Use a fresh Idempotency-Key for each operation so you can retry it without a second charge.
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.
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);The response
Invented example, not a real lookup. Do not call or open its links.
data.result contains the tool result and meta includes requestId, unitsCharged and your period usage. The API reference lists the fields of each of the tools.
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.
Credits and errors
Each valid result uses 1 credit, even when it has no data; validation errors are free. 401 means the key is missing or invalid, 403 that there is no active Pro and 429 that credits ran out or the request-rate limit was reached.