# Consultar un número de teléfono

Una sola llamada responde qué es un número. Todo lo que aparece aquí necesita una clave API con el alcance `lookup`.

## Ejecutar una consulta base

Envía el número y nada más. La consulta base siempre se factura una vez, y siempre responde con el país, la red que sirve el número, la red que emitió el rango y un tipo de línea general.

**TypeScript**

```typescript
const answer = await bird.lookup.phoneNumber({
  phone_number: "+31612345678",
  type: ["classification", "score"],
});
console.log(answer.country_code, answer.line_type);
// Only a block whose status is ok carries a value, and only that one is billed.
if (answer.score?.status === "ok") console.log(answer.score.value);
```

Examples: [TypeScript](/es-es/documentacion/guides/lookup/phone-numbers.ts.md) · [Python](/es-es/documentacion/guides/lookup/phone-numbers.py.md) · [Go](/es-es/documentacion/guides/lookup/phone-numbers.go.md) · [PHP](/es-es/documentacion/guides/lookup/phone-numbers.php.md) · [CLI](/es-es/documentacion/guides/lookup/phone-numbers.cli.md) · [MCP](/es-es/documentacion/guides/lookup/phone-numbers.mcp.md) · [cURL](/es-es/documentacion/guides/lookup/phone-numbers.curl.md)

## Cómo escribir el número

Envía el código de llamada del país y luego el número nacional. El `+` inicial es opcional y `00` funciona en su lugar, así que `+31612345678`, `31612345678` y `0031612345678` son todos el mismo número.

Un número escrito para marcar dentro de un país, sin código de país, se rechaza en lugar de adivinarse. `0612345678` devuelve [`E22000`](/docs/api/errors/E22000), porque anteponer un código de país designaría un número real en otro lugar y se te cobraría por consultarlo.

## Qué responde la consulta base

`country_code` es el país del número; está ausente cuando el número no pertenece a un solo país, como ocurre con un rango no geográfico.

`network_info` es la red que sirve el número actualmente, y `original_network_info` es la red que emitió su rango. Ambas difieren cuando el número ha sido portado, y en ese caso `flags` contiene `ported`.

`line_type` indica qué tipo de línea es el número: `mobile`, `fixed_line`, `voip`, `toll_free`, `premium_rate`, `satellite`, `pager`, `payphone`, `m2m`, `service`, `other` o `unknown`. `unknown` significa que la plataforma del operador no tiene clasificación para el rango; `other` significa que tiene una sin equivalente aquí. Para el servicio asignado con mayor precisión, solicita la propiedad `classification`. Responde desde una fuente diferente con un vocabulario más amplio, y se reporta por separado para que siempre puedas distinguir ambas.

## Añadir propiedades

Indica las propiedades que quieres en `type`. Cada una se factura por separado y solo cuando se entrega.

| Propiedad        | Qué responde                                                                             |
| ---------------- | ---------------------------------------------------------------------------------------- |
| `classification` | El servicio asignado preciso del rango: tarifa premium, satélite, M2M, teléfono público. |
| `porting`        | Cuándo el número cambió de red por última vez, y cada cambio registrado.                 |
| `presence`       | Si el número está activo en la red en este momento.                                      |
| `roaming`        | Si está en roaming, y en qué red.                                                        |
| `sim_swap`       | Cuándo se cambió su SIM por última vez.                                                  |
| `score`          | Una puntuación de credibilidad de 0 a 100.                                               |

`classification`, `porting` y `score` leen datos almacenados y responden rápido. `presence`, `roaming` y `sim_swap` consultan la red en vivo, así que son más lentas y su cobertura varía según el operador. Espera `unavailable` o `inconclusive` con más frecuencia para estas que para las almacenadas.

Dos propiedades responden preguntas que la consulta base ya aborda, con mayor resolución. `porting` te da la fecha y el historial completo, mientras que el indicador `ported` de la consulta base solo dice si alguna vez hubo un cambio. `classification` resuelve `line_type` al servicio asignado exacto.

## Lee el estado antes del valor

Cada bloque de propiedad lleva un `status`, y solo `ok` incluye un valor.

```json
{
  "phone_number": "+441904123456",
  "country_code": "GB",
  "line_type": "service",
  "classification": {
    "status": "ok",
    "value": "premium_rate"
  },
  "score": {
    "status": "unavailable"
  }
}
```

En esa respuesta se te cobró la consulta base y `classification`. No se te cobró `score`.

Lee `status` primero y trata cualquier valor distinto de `ok` como "not answered". Es un vocabulario abierto, así que un valor que no reconozcas es un estado futuro, no un error.

Dos bloques reportan un límite en lugar de una cifra exacta cuando la red no proporciona una. `sim_swap` devuelve `min_days` y `max_days` en lugar de `last_swapped_at` cuando solo se conoce una banda de recencia. `porting` establece `last_ported_at_is_approximate` cuando un registro recoge el período de un cambio pero no su día.

Un campo se lee como negativo pero es un hallazgo positivo: `porting.ported` con valor `false` significa que se consultó el registro y no tiene ningún cambio para este número, no que no se pudo verificar nada. Para eso sirve `status`.

## Reintentar sin pagar dos veces

Una consulta se factura, así que una solicitud reintentada no debe comprar una segunda respuesta. Envía un `Idempotency-Key` y una repetición de la misma solicitud reproduce la respuesta almacenada en lugar de ejecutar una nueva consulta. Consulta [Idempotency](/docs/guides/idempotency).

La forma `GET` de esta operación, que coloca el número en la URL, no puede llevar una clave de idempotencia. Usa la forma `POST` para cualquier proceso automatizado.

## Errores

| Código                              | Qué ocurrió                                                                                |
| ----------------------------------- | ------------------------------------------------------------------------------------------ |
| [`E22000`](/docs/api/errors/E22000) | El número no es un número de teléfono válido en formato internacional. No se cobró nada.   |
| [`E22001`](/docs/api/errors/E22001) | El saldo de la organización no cubre la consulta. Recárgalo y reintenta. No se cobró nada. |
| [`E22002`](/docs/api/errors/E22002) | La consulta no está disponible temporalmente. Reintenta con retroceso. No se cobró nada.   |

Una propiedad que falla no es un error. Se devuelve como un estado en su bloque, junto con la consulta base.

## Próximos pasos

- [Consultar una dirección de correo electrónico](/docs/guides/lookup/email-addresses) es la otra mitad de Lookup.
- [Referencia API de Lookup](/docs/api/reference/create-phone-number-lookup) documenta cada campo y cada bloque de propiedad.
- [Rate limits](/docs/guides/rate-limits) cubre el bucket `lookup` del que consumen estas llamadas.
- [Consulta de número de teléfono: verifica un número antes de enviar](/learn/lookup/phone-number-lookup-check-a-number-before-you-send) es un video que ejecuta una consulta y añade las verificaciones de red en vivo.

## Related resources

- [Phone number lookup](/lookup-api) (product)

[Get an implementation brief](/learn/workspace?topic=lookup-phone)