GET/api/v6/numberinsight/{number}

Consulta de un número

País, tipo de línea, operador actual y área de un número telefónico.

Alcance

Cualquier API key válida

Límite de uso

60 solicitudes por minuto

Idempotencia

Admite Idempotency-Key

Resuelve un número telefónico: país, tipo de línea, operador (en Colombia siguiendo portabilidad), área y, para Colombia, el NRN de enrutamiento.

La respuesta tiene la misma estructura para Colombia y para el resto del mundo: los campos que no aplican vienen en null. Así tu cliente no necesita dos ramas de parseo.

Parámetros de ruta

number

stringobligatorio

Número en E.164 (+5491123456789), E.164 sin + (5491123456789) o formato nacional colombiano (10 dígitos).

Cabeceras

Idempotency-Key

stringopcional

Llave de idempotencia opcional (1 a 255 caracteres de A-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.

Respuestas

200

Número resuelto. Los campos no aplicables vienen en null.

{
  "success": true,
  "data": {
    "phoneNumber": {
      "e164": "+573001234567",
      "national": "3001234567",
      "raw": "3001234567"
    },
    "valid": true,
    "country": { "iso2": "CO", "callingCode": "57", "name": "Colombia", "mcc": "732" },
    "lineType": "mobile",
    "numberType": "mobile",
    "ported": true,
    "operator": { "name": "Tigo", "brand": "Tigo", "mnc": "103", "nrn": "103" },
    "area": null,
    "timezone": null,
    "portability": {
      "donorOperator": { "name": "Claro", "brand": "Claro" },
      "initialOperator": { "name": "Claro", "brand": "Claro" },
      "activatedAt": "2024-08-12",
      "processedAt": "2024-08-11T14:32:00Z",
      "sourceDate": "2024-08-11"
    },
    "zone": { "id": "103", "name": "Tigo" }
  },
  "meta": {
    "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6",
    "timestamp": "2026-06-18T09:00:00+00:00",
    "responseTimeMs": 2.1
  }
}

400

Llave de idempotencia inválida.

401

Credenciales inválidas o faltantes.

403

La cuenta no puede ejecutar esta consulta.

409

Una petición con la misma llave de idempotencia sigue en proceso.

422

La llave de idempotencia se reusó con un cuerpo distinto.

429

Se excedió el límite de solicitudes.

503

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.

401AUTH_REQUIREDNo se envió un token Bearer y cada llamada lo requiere.401AUTH_INVALID_KEYLa API key no se reconoce: formato equivocado, revocada o vencida.403ACCOUNT_NOT_ACTIVETu organización está suspendida o cerrada.403ACCOUNT_BLOCKEDHay un bloqueo total activo: cada llamada se rechaza.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.

Ver el catálogo completo

Alcance y límites

Parámetros de ruta

Cabeceras

Respuestas

Errores posibles