Referencia

NumDetect Referencia de la API

Todos los endpoints comparten una clave API y un saldo.

Elemento	Valor
URL base	https://numdetect.com
Cabecera de autenticación	X-API-Key: sk_your_api_key
Estructura de la respuesta	{ code, msg, data }

Los precios no se indican aquí; cada producto se factura por verificación correcta. Ver precios

Autenticación

Use una clave API creada en Configuración y envíela con cada solicitud.

Cabecera de autenticación

X-API-Key: sk_your_api_key

Mantenga su clave API en secretoLlame siempre a este endpoint desde su servidor. Cualquiera que tenga la clave puede gastar su saldo.

Verificaciones asíncronas

POST/api/v1/bulk-tasksGET/api/v1/bulk-tasks/{id}

Suba un archivo y obtenga al instante un ID de tarea; después, consulte ese ID hasta que se complete correctamente. La respuesta correcta incluye result_url, el enlace de descarga del resultado. Solo existen dos acciones: enviar y consultar. No sondee más de una vez cada 30 segundos.

Parámetros

Campo	Tipo	Descripción
`service_type`	string	Código de producto masivo, uno de los productos indicados a continuación.
`country`	string	Código ISO 3166-1, como `US`. Obligatorio para las tareas de números: cada número debe incluir su código de país y pertenecer a este país (los que no lo cumplan se excluyen y no se cobran); también selecciona el enrutamiento. En multipart debe ir antes de `file`.
`file`	file	Un archivo `.txt` o `.csv` con un identificador por línea, de hasta `max_file_bytes` (20MB por defecto).
`Idempotency-Key`	header	Opcional, hasta 128 caracteres. Repetir la misma clave devuelve la tarea original en lugar de crear una segunda.

Productos de este grupo

Validación de números de teléfononumber_validation_batchUna lista limpia es el punto de partida de la próxima campaña. Compruebe las señales de validez y activación para encontrar los registros que merecen revisión y, después, incorpore el resultado estructurado a la depuración de listas, las actualizaciones del CRM y las comprobaciones previas al contacto, para que cada acción parta de datos más claros.Página del producto
Actividad del númeronumber_activity_batchHaga que el próximo seguimiento parta de una señal de actividad. Detecte la actividad reciente en toda una lista de números, separe los registros inactivos de los números que merecen revisión y use el resultado para planificar la reactivación, la segmentación y las prioridades de contacto.Página del producto
Usuarios de alto valornumber_high_value_batchEncuentre los registros que conviene revisar primero. Combine características de dispositivos de gama alta con actividad de red reciente para obtener una señal true/false de posible usuario de alto valor que ayude a priorizar servicio, membresía y campañas; es una señal de detección, no prueba de ingresos ni de compras.Página del producto
E-commerce activonumber_ecommerce_batchEmpiece la próxima campaña comercial con una audiencia más enfocada. Encuentre señales disponibles de actividad en comercio electrónico, defina segmentos de audiencia y remarketing en torno a los registros que merecen revisión y mantenga claro el límite: el resultado no es un pedido, una intención de compra ni un registro de actividad en una plataforma.Página del producto
Consulta global de operadorescarrier_batchConvierta una lista de teléfonos en contexto listo para el enrutamiento. Añada operador, operador subyacente, tipo de línea, país, región y ciudad a los registros internacionales y use el resultado enriquecido para enrutamiento, análisis regional, segmentación y actualizaciones del CRM.Página del producto

Validación de números de teléfono

number_validation_batchteléfono500–500.000 por tarea

Una lista limpia es el punto de partida de la próxima campaña. Compruebe las señales de validez y activación para encontrar los registros que merecen revisión y, después, incorpore el resultado estructurado a la depuración de listas, las actualizaciones del CRM y las comprobaciones previas al contacto, para que cada acción parta de datos más claros.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_validation_batch \
  -F country=US \
  -F file=@numbers.txt

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_validation_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_validation_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`identifier`	17253100591	El número enviado en dígitos sin formato con el código de país, sin signo más ni espacios (p. ej., 17253100591), y la clave estable para asociar los resultados a un cliente, lead o registro del CRM. Consérvelo para rastrear la lista de origen y volver a escribir los resultados de forma masiva; el campo por sí solo no establece que se pueda contactar con el número.
`activated`	true	La señal de activación que devuelve esta verificación. Úsela para encontrar registros que merecen revisión antes de contactar, organizar colas de depuración y respaldar la segmentación del CRM; combínela con datos de consentimiento, origen e interacción en lugar de tratarla como garantía de conexión o de entrega. Los valores son true o false.

Actividad del número

number_activity_batchteléfono500–500.000 por tarea

Haga que el próximo seguimiento parta de una señal de actividad. Detecte la actividad reciente en toda una lista de números, separe los registros inactivos de los números que merecen revisión y use el resultado para planificar la reactivación, la segmentación y las prioridades de contacto.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_activity_batch \
  -F country=US \
  -F file=@numbers.txt

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_activity_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_activity_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`identifier`	17253100591	El número enviado en dígitos sin formato con el código de país, sin signo más ni espacios (p. ej., 17253100591), que se usa para volver a escribir el resultado de actividad en una lista, un cliente o un registro de lead. Solo sirve para asociar y rastrear; no incluye hora de actividad, frecuencia ni detalles de interacción.
`activated`	true	Una señal de actividad disponible que puede ayudar a los equipos a priorizar la revisión, crear etiquetas de audiencia y planificar la cadencia de reactivación. No es un recuento de días de actividad, una frecuencia ni un momento de observación concreto; una señal ausente no significa que alguien nunca vaya a responder. Los valores son true o false.

Usuarios de alto valor

number_high_value_batchteléfono500–500.000 por tarea

Encuentre los registros que conviene revisar primero. Combine características de dispositivos de gama alta con actividad de red reciente para obtener una señal true/false de posible usuario de alto valor que ayude a priorizar servicio, membresía y campañas; es una señal de detección, no prueba de ingresos ni de compras.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_high_value_batch \
  -F country=US \
  -F file=@numbers.txt

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_high_value_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_high_value_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`identifier`	17253100591	El número enviado en dígitos sin formato con el código de país (p. ej., 12017200001), que se usa para asociar la señal de alto valor al registro subido y seguirla en un CRM o una cola de revisión. No proporciona identidad, modelo de dispositivo ni otros datos de perfil personal.
`activated`	true	Una señal de apoyo true/false derivada de características de dispositivos de gama alta y de actividad de red reciente. Puede ayudar a los equipos de membresía, servicio y marketing a fijar prioridades de revisión, pero no confirma ingresos, patrimonio, capacidad de compra ni gasto real.

E-commerce activo

number_ecommerce_batchteléfono500–500.000 por tarea

Empiece la próxima campaña comercial con una audiencia más enfocada. Encuentre señales disponibles de actividad en comercio electrónico, defina segmentos de audiencia y remarketing en torno a los registros que merecen revisión y mantenga claro el límite: el resultado no es un pedido, una intención de compra ni un registro de actividad en una plataforma.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_ecommerce_batch \
  -F country=US \
  -F file=@numbers.txt

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_ecommerce_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_ecommerce_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`identifier`	17253100591	El número enviado en dígitos sin formato con el código de país, sin signo más ni espacios (p. ej., 17253100591), que se usa para vincular la señal de actividad comercial con registros de clientes, leads o audiencias. Permite a los equipos de marketing cruzar el resultado con sus propios datos de consentimiento, navegación, pedidos y membresía; no contiene información de pedidos ni de productos.
`activated`	true	Una señal disponible de actividad comercial que puede enfocar la revisión de audiencias, la preparación de listas de remarketing y la planificación de pruebas de contenido. No representa un pedido, un importe de transacción, una intención de compra ni una actividad concreta en una plataforma. Los valores son true o false.

Consulta global de operadores

carrier_batchteléfono500–500.000 por tarea

Convierta una lista de teléfonos en contexto listo para el enrutamiento. Añada operador, operador subyacente, tipo de línea, país, región y ciudad a los registros internacionales y use el resultado enriquecido para enrutamiento, análisis regional, segmentación y actualizaciones del CRM.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=carrier_batch \
  -F country=US \
  -F file=@numbers.txt

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`identifier`	17253100591	El número enviado en dígitos sin formato con el código de país, sin signo más ni espacios (p. ej., 17253100591), y la clave de asociación para volver a escribir el contexto de operador, línea y geografía en la lista de origen. Conserve junto a él sus propias columnas de origen para que los equipos de enrutamiento, servicio y CRM puedan rastrear la verificación, gestionar duplicados y actualizar el cliente o lead correcto. Identifica un registro; no demuestra que se pueda contactar con el número.
`carrier`	T-Mobile	El nombre comercial del operador, cuando es identificable. Puede enriquecer los registros del CRM, respaldar el enrutamiento del servicio, ayudar a revisar la composición de los números y mostrar cómo se distribuye una lista entre operadores. Úselo como contexto operativo, no como prueba de accesibilidad ni de uso actual. Un valor vacío significa que esta verificación no devolvió ningún nombre utilizable; no demuestra que no exista un operador.
`underlying_carrier`		El operador de red subyacente, cuando es identificable, útil para entender contextos de revendedores, operadores virtuales y números portados. Puede diferir del operador comercial, y esa diferencia puede ayudar a los equipos a investigar cuestiones de enrutamiento o de titularidad. No es un estado de la red celular en tiempo real ni una señal de conexión en directo.
`number_type`	Fixed Line or Mobile	El tipo de línea devuelto, como mobile, fixed line u otra categoría identificable. Úselo para separar registros móviles y fijos, planificar el enrutamiento del servicio, comprobar la idoneidad del canal y añadir un segmento útil al CRM. No es un resultado de conexión; conserve un valor vacío o desconocido para revisión en lugar de tratarlo como un fallo.
`country_code`	US	El código de país o territorio devuelto, para agrupar listas internacionales, aplicar reglas de enrutamiento y de negocio por país y elaborar informes regionales. Describe el contexto de numeración, no el país actual, la ubicación física ni la nacionalidad de una persona. Los casos de uso transfronterizo y de números virtuales deben contrastarse con sus propios datos de clientes.
`region`	CA	El contexto de región, estado o provincia, cuando está disponible. Puede respaldar el análisis de cobertura de mercado, la agrupación regional de listas, la asignación del servicio y los informes de operaciones. Procede del contexto del número y de la red, no de una ubicación en tiempo real, por lo que no debe interpretarse como la zona actual del usuario; los valores ausentes o de otra región requieren una revisión de negocio habitual.
`city`	LOS ANGELES	El contexto a nivel de ciudad, cuando está disponible. Puede mejorar los informes regionales, revelar la composición de la lista, respaldar operaciones localizadas y completar un campo ausente del CRM. La asignación de numeración, la portabilidad, los números virtuales y las diferencias entre fuentes pueden afectar a la precisión a nivel de ciudad, por lo que las decisiones importantes deben contrastarse con los datos facilitados por el usuario o con los registros de negocio existentes.

Saldo

GET/api/v1/balance

Consulte el saldo actual de la cuenta en micros de USD. Solo lectura: no crea ningún registro de verificación ni cobra nada.

Saldo

GET/api/v1/balance

Solicitud

curl "https://numdetect.com/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

Concurrencia, tiempos de espera y comportamiento de reintento

Los envíos de tareas masivas se aceptan antes de que empiece el trabajo. Use el estado de tarea devuelto para decidir si sigue consultando o gestiona un fallo.

Campo	Descripción
`5 solicitudes simultáneas por usuario`	El envío de una tarea ocupa una plaza de solicitud. Si la cuenta no tiene ninguna plaza disponible, la API devuelve 42901 con Retry-After; espere y vuelva a enviar el archivo.
`Consulte en lugar de esperar`	El envío de una tarea responde de inmediato. Consulte su estado como máximo una vez cada 30 segundos mientras se procesa.
`El tamaño de la tarea depende del producto`	Cada producto tiene su propio tamaño mínimo y máximo de archivo, indicado en la sección de tareas.

Códigos de error

Código	Descripción
`40000`	Tipo de servicio no compatible o campos de la solicitud en conflicto
`40001`	Cuerpo JSON no válido
`40002`	Número no válido
`40100`	Clave API ausente o no válida
`40200`	Saldo insuficiente
`42200`	La tarea enviada no se pudo aceptar en su forma actual
`42900`	Se ha agotado una cuota de uso o hay demasiados pedidos sin finalizar
`42901`	Todas las plazas de solicitud están ocupadas; envíe cuando termine una solicitud en curso. La solicitud rechazada no se cobra e incluye una cabecera Retry-After
`50303`	El servicio está a plena capacidad en este momento; no se cobra. Espere los segundos indicados en Retry-After y vuelva a enviar la misma solicitud
`50400`	La solicitud no finalizó dentro de su tiempo límite y no se cobra; vuelva a intentarlo
`50300`	Mantenimiento del servicio de validación