Phone Carrier Bulk Lookup API: Comprobación masiva

Consulta el operador, el operador subyacente, el tipo de línea, el código de país, la región y la ciudad asociados a cada número móvil enviado. Simplifica la agrupación por operador y el filtrado de números virtuales. La tarea utiliza el flujo de trabajo estándar de procesamiento por lotes asíncrono.

Formato de entrada

Cargue un archivo de texto con un número de teléfono por línea. Normalice los valores antes de cargarlo; se recomienda el formato E.164 para teléfonos.

+14155552671
+13105551234

Envíe un país por tarea. Los números se normalizan según el país de la tarea (véase country_code más abajo); los números de otro país en el mismo archivo se reescriben a ese país y no darán resultados correctos.

Crear una tarea

POST https://api.checknumber.ai/v1/tasks

curl --location 'https://api.checknumber.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./input.txt"' \
--form 'task_type="globalCarrier"' \
--form 'country_code="US"'

Parámetros de la solicitud

Campo	Obligatorio	Descripción
file	sí	Archivo de texto, un número de teléfono por línea.
task_type	sí	globalCarrier. Los tipos de tarea por país anteriores (usaCarrier, deCarrier, gbCarrier, …) se siguen aceptando y apuntan a este mismo producto.
country_code	no	País ISO-3166 alfa-2 de los números del archivo (US, DE, OM, …). Se usa para normalizar números escritos sin código de país. Si se omite, se infiere del archivo.

La API devuelve un ID de tarea. Guárdelo y úselo para consultar el estado.

Respuesta de carga

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "pending",
  "total": 5000,
  "estimated_amount": {
    "amount": "0.500000",
    "currency": "USD"
  },
  "message": "Task created successfully"
}

Comprobar el estado de la tarea

POST https://api.checknumber.ai/v1/gettasks

curl --location 'https://api.checknumber.ai/v1/gettasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'task_id="d4g8o46p2jvh04o9uolg"'

Consulte hasta que status sea exported. No considere pending ni processing como resultados completos.

Respuesta en proceso

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "processing",
  "total": 5000,
  "success": 2500,
  "failure": 0
}

Respuesta exportada

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "exported",
  "total": 5000,
  "success": 5000,
  "failure": 0,
  "result_url": "https://example-link-to-results.zip",
  "actual_amount": {
    "amount": "2.000000",
    "currency": "USD"
  }
}

Campos del resultado

Campo	Descripción	Ejemplo
number	Número de teléfono de la entrada enviada.	+14155552671
number_type	Tipo de línea devuelto para el número.	mobile
country_code	country_code value returned for the input.	valor de ejemplo
carrier	Carrier value returned for the number.	Ejemplo Carrier
underlying_carrier	Carrier value returned for the number.	Ejemplo Carrier
region	region value returned for the input.	valor de ejemplo
city	Ciudad devuelta por el servicio para la entrada.	valor de ejemplo

Procesamiento del archivo de resultados

Descargue el archivo desde result_url solo después de exportar la tarea. Conserve los nombres de columna devueltos al procesar el archivo.

Campos de respuesta

Campo	Descripción
created_at	Marca de tiempo de creación de la tarea.
updated_at	Marca de tiempo de la última actualización.
task_id	Identificador único de la tarea.
status	pending, processing, exported o failed.
total	Total de valores de entrada procesados.
success	Valores procesados correctamente.
failure	Valores cuyo procesamiento falló.
result_url	URL de descarga cuando la tarea se exporta.
actual_amount	Importe final liquidado, si está disponible.
estimated_amount	Importe estimado devuelto al crear la tarea.

Códigos de estado

Status	Descripción
200	Solicitud correcta.
202	Tarea creada correctamente y cargo estimado aplicado.
400	Archivo no válido, tipo de tarea no compatible o muy pocas entradas válidas.
401	Falta la clave API o no es válida.
402	Saldo insuficiente.
403	Producto no disponible para su cuenta (descontinuado o solo para clientes en lista blanca); contacte con soporte.
404	Tarea no encontrada.
413	El archivo cargado es demasiado grande.
500	Error interno del servidor; inténtelo más tarde.
503	Producto temporalmente no disponible (pausado por mantenimiento); no se realiza ningún cargo, inténtelo más tarde.

Notas operativas

• La tarea es asíncrona; use el ID para consultar su estado.
• Compruebe los límites de entrada del producto antes de cargar el archivo.
• Las filas fallidas aparecen en el resultado exportado y se reflejan en los contadores.
• Los campos anteriores se basan en el sample actual y pueden cambiar si cambia el esquema de exportación.