Riferimento API

Autenticazione

Crea una API key nel tuo account e copia il valore mostrato una sola volta. Configura NOCALL_API_KEY come segreto sul server. Usa HTTPS; non inserire mai la chiave nel codice del browser, repository, screenshot o log.

Invia la chiave completa in Authorization: Bearer, con uno spazio dopo Bearer. Non usare X-API-Key e non inserire la chiave nell’URL.

Su /v1/data/* + /v2/*, una chiave valida sostituisce la prova ByteGuard del browser. Scadenza, revoca, abbonamento, crediti e limiti vengono comunque verificati. Non autorizza altre rotte. openapi.json e products sono pubblici.

Authorization: Bearer <NOCALL_API_KEY>

• Crea chiave API ↗

La prima richiesta

Tutti i 44 tool sono disponibili tramite API: chiama POST /v2/<tool-id>, oppure POST /v2/tools con il campo tool nel corpo. Ogni tool ha il proprio corpo JSON, documentato nella sua guida. data.result contiene il risultato del tool. Usa gli identificatori riportati nella tabella.

Genera una nuova Idempotency-Key per ogni nuova operazione. Mantienila solo per ripetere la stessa operazione con gli stessi dati.

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

Tutti i 44 tool sono disponibili tramite API: chiama POST /v2/<tool-id>, oppure POST /v2/tools con il campo tool nel corpo. Ogni tool ha il proprio corpo JSON, documentato nella sua guida. data.result contiene il risultato del tool. Usa gli identificatori riportati nella tabella.

• OpenAPI v2 ↗

Endpoint disponibili

Mostriamo solo dati tecnici verificati o pubblici. Identità private e segnali di protezione restano nascosti.

API v1 · phone è obbligatorio: una stringa fino a 64 caratteri, preferibilmente in formato E.164. country è un codice paese supportato di due lettere, facoltativo con valore predefinito ES. Content-Type deve essere application/json.

• OpenAPI 3.1 ↗

Risposte

data contiene il risultato; meta include requestId, unitsCharged e l’utilizzo se pertinente. L’estratto fittizio mostra il saldo dopo una richiesta. Anche un risultato valido senza dati costa 1 credito; errori di convalida o del fornitore e lettura del saldo sono gratuiti. L’assenza di dati non prova che il numero sia sicuro. Consulta OpenAPI per gli schemi completi.

{
  "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 ↗

Crediti e limiti

Ogni chiamata all'API costa 1 credito. Si usano prima quelli mensili.

La rigenerazione disattiva le chiavi precedenti. Il saldo dei crediti resta invariato.

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

• Chiave API e crediti ↗

Tentativi successivi e richieste in blocco

Genera una nuova Idempotency-Key per ogni nuova operazione. Mantienila solo per ripetere la stessa operazione con gli stessi dati.

Idempotency-Key è facoltativo per richieste singole e obbligatorio per i blocchi: 8–128 caratteri (lettere, cifre, punti, trattini, underscore o due punti). Per riprovare, conserva la stessa chiave, rotta, API key e corpo. Una risposta ripetuta non viene addebitata di nuovo. Controlla il saldo dopo una risposta ambigua.

Un blocco accetta fino a 50 elementi. product seleziona una delle operazioni dell’esempio. Prima di iniziare serve saldo per tutti gli elementi validi; vengono addebitati solo i risultati validi completati. Le richieste simultanee condividono il saldo: se finisce prima dell’addebito finale, la richiesta restituisce 429 senza addebito.

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"}]}'

Risoluzione dei problemi

Guide correlate

• Intelligence telefonica
• Rischio telefonico
• Ricerca operatore
• Il mio numero è stato divulgato?
• Ricerca inversa azienda verificata