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.

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);

answer = client.lookup.phone_number(
    phone_number="+31612345678", type=["classification", "score"]
)
print(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 is not None and answer.score.status == "ok":
    print(answer.score.value)

answer, err := client.Lookup.PhoneNumber(context.Background(), bird.LookupPhoneNumberParams{
	PhoneNumber: "+31612345678",
	Type:        []bird.LookupProperty{"classification", "score"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(*answer.CountryCode, *answer.LineType)
// Only a block whose status is ok carries a value, and only that one is billed.
if answer.Score != nil && *answer.Score.Status == "ok" {
	fmt.Println(*answer.Score.Value)
}

$answer = $bird->lookup->phoneNumber(
    (new PhoneNumberLookupRequest())
        ->setPhoneNumber('+31612345678')
        ->setType(['classification', 'score']),
);
echo $answer->getCountryCode(), ' ', $answer->getLineType();
// Only a block whose status is ok carries a value, and only that one is billed.
if ($answer->getScore()?->getStatus() === 'ok') {
    echo $answer->getScore()->getValue();
}

bird lookup phone-number \
  --phone-number +31612345678 \
  --type classification \
  --type presence

curl -X POST "https://us1.platform.bird.com/v1/lookup/phone-number" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+31612345678",
    "type": [
      "classification",
      "presence"
    ]
  }'

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, 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.

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.

{
  "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.

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

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 es la otra mitad de Lookup.
• Referencia API de Lookup documenta cada campo y cada bloque de propiedad.
• 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 es un video que ejecuta una consulta y añade las verificaciones de red en vivo.