Referencia

CarrierLookup Referencia de la API

Todos los endpoints comparten una clave API y un saldo.

Elemento	Valor
URL base	https://carrierlookup.online
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 síncronas

POST/api/v1/checkPOST/api/v1/batch-check

Envíe un número de teléfono, o hasta 100 en una sola solicitud, y lea el resultado en la misma respuesta. Sin sondeo ni callbacks. Un resultado indeterminado devuelve 422 con el código 42200 y no se cobra. Una solicitud múltiple conserva el orden de entrada, factura cada identificador de forma independiente y dispone de 300 segundos para finalizar; si no lo consigue, toda la solicitud falla y se reembolsan todos los cargos.

Parámetros

Campo	Tipo	Descripción
`service_type`	string	Código de producto, uno de los productos indicados a continuación.
`identifier`	string	Verificación individual: un número de teléfono. El servidor lo normaliza.
`identifiers`	string[]	Verificación múltiple: de 1 a 100 números de teléfono. La respuesta conserva este orden.

Productos de este grupo

Consulta del operador originalcarrierAverigüe el operador al que se asignó originalmente un número, con el tipo de línea y la ubicación.Página del producto

Consulta del operador original

carrierteléfono

Averigüe el operador al que se asignó originalmente un número, con el tipo de línea y la ubicación.

Verificación individual

POST/api/v1/check

Solicitud

curl -X POST "https://carrierlookup.online/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "carrier", "identifier": "+17253100591" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "identifier": "+17253100591",
    "carrier": "T-Mobile",
    "underlying_carrier": "",
    "number_type": "Fixed Line or Mobile",
    "country_code": "US",
    "region": "NV",
    "city": "LAS VEGAS"
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`carrier`	string	Operador al que se asignó originalmente el número. No es el operador actual tras una portabilidad.
`underlying_carrier`	string	Operador subyacente indicado por el proveedor cuando difiere del asignado; cadena vacía cuando el proveedor no lo facilita.
`number_type`	string	Tipo de línea indicado por el proveedor; vacío cuando no está disponible.
`country_code`	string	Código ISO del país al que pertenece el número.
`region`	string	Región de asignación; vacío cuando el proveedor no la facilita.
`city`	string	Ciudad de asignación; vacío cuando el proveedor no la facilita.

Verificación múltiple

POST/api/v1/batch-check

Solicitud

curl -X POST "https://carrierlookup.online/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "carrier", "identifiers": ["+17253100591", "12345"] }'

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "total": 2,
    "succeeded": 1,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "carrier": "T-Mobile",
        "underlying_carrier": "",
        "number_type": "Fixed Line or Mobile",
        "country_code": "US",
        "region": "NV",
        "city": "LAS VEGAS"
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`exists`	boolean	Si este número produjo un resultado. false significa que el formato no era válido, que el resultado fue indeterminado o que la verificación falló; cuando es false, no aparece ninguno de los campos siguientes.
`carrier`	string	Operador al que se asignó originalmente el número. No es el operador actual tras una portabilidad.
`underlying_carrier`	string	Operador subyacente indicado por el proveedor cuando difiere del asignado; cadena vacía cuando el proveedor no lo facilita.
`number_type`	string	Tipo de línea indicado por el proveedor; vacío cuando no está disponible.
`country_code`	string	Código ISO del país al que pertenece el número.
`region`	string	Región de asignación; vacío cuando el proveedor no la facilita.
`city`	string	Ciudad de asignación; vacío cuando el proveedor no la facilita.

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

Consulta de operador globalcarrier_batchSuba un archivo completo de números: operador, operador subyacente, tipo de línea, país, región y ciudad de cada uno, los mismos campos que la consulta de operador en tiempo real.Página del producto

Consulta de operador global

carrier_batchteléfono1000–500.000 por tarea

Suba un archivo completo de números: operador, operador subyacente, tipo de línea, país, región y ciudad de cada uno, los mismos campos que la consulta de operador en tiempo real.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://carrierlookup.online/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": 1015,
    "total": 1015,
    "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://carrierlookup.online/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": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "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 como dígitos sin formato con el código de país, sin signo más ni espacios (p. ej., 17253100591).
`carrier`	T-Mobile	Operador al que se asignó originalmente el número. No es el operador actual tras una portabilidad.
`underlying_carrier`		Operador subyacente indicado por el proveedor cuando difiere del asignado; vacío cuando el proveedor no lo facilita.
`number_type`	Fixed Line or Mobile	Tipo de línea indicado por el proveedor, como Fixed Line or Mobile; vacío cuando no está disponible.
`country_code`	US	Código ISO del país al que pertenece el número.
`region`	CA	Región de asignación; vacío cuando el proveedor no la facilita.
`city`	LOS ANGELES	Ciudad de asignación; vacío cuando el proveedor no la facilita.

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://carrierlookup.online/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

Las consultas de operador son síncronas. Use el código devuelto para decidir si acepta el resultado o reintenta más tarde.

Campo	Descripción
`5 solicitudes simultáneas por usuario`	Las verificaciones individuales y múltiples comparten este límite, y una solicitud múltiple cuenta como una sola solicitud, independientemente de cuántos números incluya. Además, solo se ejecuta una verificación múltiple por cuenta a la vez; una segunda se rechaza hasta que termine la primera. Alcanzar cualquiera de los dos límites devuelve de inmediato el código 42901 sin cargo, junto con una cabecera Retry-After: vuelva a enviar la solicitud cuando termine una solicitud en curso.
`60 s individual, 300 s múltiple`	Superar el tiempo límite devuelve el código 50400 sin cargo. Una verificación múltiple que supera el tiempo de espera falla en su totalidad: no hay resultados parciales y se reembolsa el importe completo.
`Una verificación múltiple admite hasta 100 números`	Los resultados conservan el orden y la longitud del envío. Solo se ejecuta una verificación múltiple por cuenta a la vez; envíe el siguiente lote cuando el anterior haya devuelto sus resultados.

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`	No se ha podido determinar el número en este momento. No se devuelven datos y la solicitud no se cobra
`42900`	Se ha agotado una cuota de uso o hay demasiados pedidos sin finalizar
`42901`	Las cinco plazas de solicitudes simultáneas están ocupadas o ya hay una verificación múltiple en ejecución en esta cuenta; envíe la solicitud 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 verificación no finalizó dentro de su tiempo de espera y no se cobra; reinténtela. Si se agota el tiempo de un lote, falla el lote completo y se reembolsa el importe total
`50300`	Mantenimiento del servicio de consulta