Documentación de la API API v1

Autenticación

Cree una clave en la página de claves de API y luego sustituya el marcador de posición de abajo en su propio terminal. Los ejemplos son solo texto; copiarlos no envía nada.

# API origin: https://api.numdetect.com
export NUMDETECT_API_KEY='YOUR_API_KEY'

• Envíe Authorization: Bearer <key> con cada solicitud. Las solicitudes JSON también necesitan Content-Type: application/json. No se necesitan cookies, ni cabecera CSRF, ni cabecera Origin.
• Una clave puede leer productos, ejecutar verificaciones individuales y masivas, leer sus resultados y leer el historial de su saldo. Los ajustes de la cuenta, las claves y las recargas se gestionan únicamente en el panel con la sesión iniciada.
• Puede crear hasta 10 claves, por ejemplo una por sistema, y eliminar cualquiera de ellas al instante.

Guarde las claves en el entorno de su servidor. No ponga claves en URLs, capturas de pantalla, registros compartidos ni archivos de código fuente confirmados.

Productos

Lea el catálogo actual antes de elegir los ID de producto. La respuesta enumera todos los productos a la venta con su tipo de entrada, precios, mínimo para masivo y países compatibles.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/products" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

single y bulk indican si el producto está disponible ahora mismo para ese tipo de verificación. countries es ["*"] para todos los países, una lista de códigos de país, o vacío para los productos de email. Los precios son USD micros por verificación.

Verificación individual

POST /api/v1/checks recibe un número de teléfono o una dirección de email y una lista de ID de producto. La solicitud espera hasta que todos los productos hayan respondido (hasta unos 45 segundos) y devuelve la verificación terminada.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/checks" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+12025550147","products":["whatsapp","telegram"]}'

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/checks" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","products":["apple_email","spotify_email"]}'

Escriba los números de teléfono con su código de país +. Para un número sin él, añada "country": "GB" (un código de país ISO) a la solicitud.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/checks/$CHECK_ID" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/checks?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Verificación masiva

POST /api/v1/bulk-jobs sube un archivo como datos de formulario multipart. El archivo se divide en una lista por país, y cada país se verifica con cada producto que elija.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/bulk-jobs" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "[email protected]" \
  -F "products=whatsapp,telegram" \
  -F "input_kind=phone" \
  -F "max_cost=50000000" \
  -F "column=0" \
  -F "header=true"

• file: CSV UTF-8 o texto plano, de hasta 100 MB y 1.000.000 de filas. Las demás columnas se conservan y se devuelven en el archivo de resultados.
• input_kind es phone o email. column es la columna, a partir de 0, con los números (por defecto 0); header=true omite la primera fila.
• country (opcional) se usa para los números de teléfono escritos sin código de país. Los números que empiezan por + o 00 conservan su propio país.
• max_cost es lo máximo que acepta pagar, en USD micros. La tarea se rechaza, y no se cobra nada, si su costo fuera mayor o su saldo es insuficiente.

Estado y resultados de las tareas masivas

Lea la tarea hasta que status sea completed, failed o cancelled. Las listas grandes pueden tardar un tiempo, así que consulte cada uno o dos minutos, o use un webhook.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Descargar el archivo de resultados

Cuando result_ready es true, GET /result devuelve un enlace de descarga válido durante 10 minutos. El propio enlace no necesita clave. Pida un enlace nuevo cada vez que necesite descargar de nuevo.

url=$(curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID/result" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" | jq -r .url)
curl --fail --silent --show-error --output result.csv "$url"

result.csv conserva todas las filas originales en su orden original y añade numdetect_status (valid, duplicate o invalid), numdetect_country y una columna por producto con yes, no, unknown, unsupported, failed o cancelled.

Cancelar una tarea en curso

Los países que aún no se han verificado se detienen y su importe retenido vuelve a su saldo.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID/cancel" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Webhooks

Configure una URL de webhook en la página de ajustes de la cuenta para que se le avise cuando termine una tarea masiva. Enviamos un POST HTTPS por cada tarea terminada:

{
  "type": "bulk_job.finished",
  "data": {
    "id": "10000000-0000-4000-8000-000000000003",
    "status": "completed",
    "total_rows": 1000,
    "valid_rows": 982,
    "charged": 245500,
    "completed_at": "2026-11-11T08:30:00Z"
  }
}

Cada solicitud incluye las cabeceras webhook-id, webhook-timestamp y webhook-signature. La firma es v1, seguida del HMAC-SHA256 en Base64 de "<webhook-id>.<webhook-timestamp>.<body>", usando su secreto de firma (whsec_…, Base64 después del prefijo). Compárela antes de confiar en el cuerpo.

Responda con cualquier estado 2xx. Las entregas fallidas se reintentan unas cuantas veces, con unos minutos de diferencia. Trate webhook-id como único, ya que una entrega reintentada puede llegar dos veces.

Tarifas y saldo

Una verificación individual cobra su precio por cada producto con una respuesta definitiva. Las respuestas unknown y failed son gratis.

Una tarea masiva retiene su costo al enviarla: por cada país y producto, max(números válidos, el mínimo masivo del producto) × el precio por volumen. Una lista completada se cobra por completo, incluidas las filas desconocidas. Una lista que falla o se cancela se devuelve a su saldo. Las filas duplicadas y no válidas, y los países que un producto no admite, son gratis.

Los importes son USD micros enteros: 1 USD = 1.000.000 de micros.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/balance-logs?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

POST /checks y POST /bulk-jobs necesitan una cabecera Idempotency-Key (hasta 128 caracteres). Use una clave nueva para cada solicitud nueva. Si se pierde una respuesta, envíe de nuevo la misma solicitud con la misma clave: recibirá el primer resultado en lugar de un segundo cargo.

Errores

Los errores usan {error: {code, message, request_id}}. Guíese por el code estable y no por el mensaje, e incluya request_id cuando contacte con soporte.

Obtenga su clave de APIVerificaciones masivasAjustes de webhooksFacturación