/api/v6/numberinsight/batchConsulta por lote
Resuelve muchos números en una sola solicitud, en línea o como trabajo asíncrono.
Alcance y límites
Cualquier API key válida
10 solicitudes por minuto
Admite Idempotency-Key
- Modalidad síncrona: hasta 500 números por solicitud.
- Modalidad asíncrona: archivo de texto plano UTF-8, una línea por número, cada línea de máximo 64 caracteres.
- El resultado de un trabajo queda disponible durante unos 90 días desde su creación.
Procesa muchos números en una sola solicitud. Hay dos modalidades y se eligen con el Content-Type.
- Síncrona:
application/jsoncon{ "numbers": [...] }, hasta 500 números. Se resuelve en línea y responde200con{ "results": [...] }. - Asíncrona:
multipart/form-dataconfile(texto plano, un número por línea) ywebhookUrlopcional. Encola un trabajo y responde202conjobId.
Cuando el trabajo asíncrono termina se dispara el evento numberinsight.batch.completed y el resultado en NDJSON queda disponible en una URL de descarga temporal que entrega el endpoint de estado.
El contrato de los eventos que emite este servicio está en Webhooks de Number Insight.
Cabeceras
Idempotency-KeyA-Za-z0-9_-). Repetir la misma operación con la misma llave devuelve la respuesta original sin volver a ejecutarla. Ver la guía de idempotencia.Cuerpo de la petición
application/jsonModalidad síncrona.numbers{
"numbers": ["3001234567", "6017430000", "+5491123456789"]
}multipart/form-dataModalidad asíncrona.filewebhookUrlnumberinsight.batch.completed cuando el trabajo termine.Respuestas
Modalidad síncrona: resuelto en línea.
{
"success": true,
"data": {
"results": [
{
"phoneNumber": {
"e164": "+573001234567",
"national": "3001234567",
"raw": "3001234567"
},
"valid": true,
"country": { "iso2": "CO", "callingCode": "57", "name": "Colombia", "mcc": "732" },
"lineType": "mobile",
"numberType": "mobile",
"ported": false,
"operator": { "name": "Tigo", "brand": "Tigo", "mnc": "103", "nrn": "103" },
"area": null,
"timezone": null,
"portability": null,
"zone": { "id": "103", "name": "Tigo" }
}
]
},
"meta": {
"requestId": "b9b1704baffab21150213c02fd853975",
"timestamp": "2026-06-02T19:43:59+00:00",
"responseTimeMs": 4.1
}
}Modalidad asíncrona: trabajo aceptado y en cola.
{
"success": true,
"data": {
"jobId": "4e2c8b91-3f12-4ad6-9b91-09e8e9c5e7a1",
"status": "queued",
"count": 12450,
"expiresAt": "2026-09-15T14:00:00Z"
},
"meta": {
"requestId": "b9b1704baffab21150213c02fd853975",
"timestamp": "2026-06-02T19:43:59+00:00",
"responseTimeMs": 4.1
}
}Falta numbers en la modalidad síncrona, el cuerpo es inválido, o la llave de idempotencia no cumple el formato.
Credenciales inválidas o faltantes.
Una petición con la misma llave de idempotencia sigue en proceso.
El lote síncrono superó los 500 números: usa la modalidad asíncrona.
El archivo asíncrono es inválido (no es texto, tiene líneas de más de 64 caracteres o está vacío), o la llave de idempotencia se reusó con un cuerpo distinto.
Se excedió el límite de solicitudes.
El servicio de consulta se está actualizando. Reintenta en unos segundos.
Errores posibles
Códigos que este endpoint puede devolver en error.code. El detalle completo está en el catálogo.
AUTH_REQUIREDNo se envió un token Bearer y cada llamada lo requiere.401AUTH_INVALID_KEYLa API key no se reconoce: formato equivocado, revocada o vencida.400BAD_REQUESTNo pudimos interpretar tu petición.400IDEMPOTENCY_KEY_INVALIDLa llave de idempotencia no cumple el formato.409IDEMPOTENCY_IN_PROGRESSLa primera petición con esa llave sigue en proceso.422IDEMPOTENCY_KEY_REUSEDLa llave ya existe, pero con un cuerpo distinto.429RATE_TPS_EXCEEDEDExcediste el cupo de tu organización para este endpoint.503INFRA_CACHE_UNAVAILABLEUn componente interno está temporalmente no disponible.