Create a phone number lookup

POST

/v1/lookup/phone-number

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"
    ]
  }'

Antwort200

{
  "phone_number": "+441904123456",
  "country_code": "GB",
  "network_info": {
    "carrier_name": "BT",
    "mcc": "234",
    "mnc": "00"
  },
  "original_network_info": null,
  "flags": [],
  "line_type": "service",
  "classification": {
    "status": "ok",
    "value": "premium_rate"
  },
  "score": {
    "status": "ok",
    "value": 48
  },
  "presence": {
    "status": "ok",
    "reachable": true
  },
  "roaming": {
    "status": "unavailable"
  }
}

Returns the number's serving and issuing networks, porting state, country, and line type. The baseline fields are included in each lookup. Request additional type blocks for classification, presence, roaming, SIM-swap, porting-history, or credibility data. Each block reports its own status; only blocks with an ok status incur an additional charge.

This form keeps the number out of the URL. The URL form performs the same lookup but cannot use an idempotency key. With this form, reuse an Idempotency-Key to return the stored result without another lookup or charge.

Anfrage-Nutzlast

phone_number

string

erforderlich

The phone number to look up, in international format: the country calling code, then the national number. The leading + is optional, and 00 works in its place, so +31612345678, 31612345678 and 0031612345678 are all the same number. A number written for dialling inside one country, with no country code, is rejected rather than guessed at.

type

array of string

Properties to add to the base lookup. Omit this field or send an empty array to request only the base lookup.

Each delivered property is billed in addition to the base lookup. A property that could not be answered is returned with its status and is not billed.

Antwort-Payload

phone_number

string

erforderlich

The number that was looked up, in E.164 format.

country_code

nullable string

The ISO 3166-1 alpha-2 country of the number. Absent when the number belongs to no single country, as a non-geographic range does.

network_info

nullable object

The network that serves the number today. Absent when no network could be identified.

Untergeordnete Attribute anzeigen

original_network_info

nullable object

The network that issued the number's range. It differs from network_info when the number has been ported. Absent when the issuing network could not be identified.

Untergeordnete Attribute anzeigen

flags

array of string

erforderlich

Notable characteristics of the number. Empty when none apply.

line_type

string

erforderlich

What kind of line the number is, as reported by the carrier platform.

This is included in every base lookup, regardless of which properties you request.

unknown: the carrier platform holds no classification for the range.
other: it holds a classification with no equivalent here.
m2m: a range reserved for machine-to-machine traffic, belonging to no individual subscriber.

For the allocated service of the range at finer precision, request the classification property. That answers from a different source, with its own wider vocabulary, and is reported separately so you can always tell the two apart.

Possible values: mobile, fixed_line, voip, toll_free, premium_rate, satellite, pager, payphone, m2m, service, other, unknown

classification

object

The allocated service of the number's range. Absent unless you requested the classification property.

Untergeordnete Attribute anzeigen

presence

object

Whether the number is live on its network. Absent unless you requested the presence property.

Untergeordnete Attribute anzeigen

roaming

object

Whether the number is roaming. Absent unless you requested the roaming property.

Untergeordnete Attribute anzeigen

sim_swap

object

When the number's SIM last changed. Absent unless you requested the sim_swap property.

Untergeordnete Attribute anzeigen

porting

object

The number's porting record. Absent unless you requested the porting property.

Untergeordnete Attribute anzeigen

porting.status

string

erforderlich

How a requested property resolved.

ok: the property was answered and its value is in the response.
unavailable: no answer arrived, so the property adds nothing: its block is null, or for classification, line_type retains the value from the base lookup. The property is not billed.
inconclusive: an answer arrived but does not resolve the property, either because the number is outside the coverage of the data behind it or because the source returned a value this property does not report. It is a real answer rather than a missing one, and it is not billed either.

Open enum: further statuses may be added over time, so treat an unrecognized value as a future one rather than an error. Only ok carries a value and only ok is billed, so branching on ok and treating everything else as "not answered" stays correct however the vocabulary grows.

Possible values (may grow over time): ok, unavailable, inconclusive

porting.ported

boolean

Whether the number has ever moved network. false is a positive finding rather than a lack of one: the registry was consulted and holds no move for this number. Present only when status is ok.

porting.last_ported_at

nullable string

When the number last moved network. Absent when it has never ported or when no date is on record.

porting.last_ported_at_is_approximate

boolean

Whether last_ported_at is an approximation. Some registries record the period of a move without its exact day.

porting.history

array of object

Every move on record, oldest first. Absent when the number has never ported or when its registry publishes no history.

Untergeordnete Attribute anzeigen

score

object

The number's credibility score. Absent unless you requested the score property.

Untergeordnete Attribute anzeigen

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.

Implementierungs-Briefing erhalten

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"
    ]
  }'

Antwort200

{
  "phone_number": "+441904123456",
  "country_code": "GB",
  "network_info": {
    "carrier_name": "BT",
    "mcc": "234",
    "mnc": "00"
  },
  "original_network_info": null,
  "flags": [],
  "line_type": "service",
  "classification": {
    "status": "ok",
    "value": "premium_rate"
  },
  "score": {
    "status": "ok",
    "value": 48
  },
  "presence": {
    "status": "ok",
    "reachable": true
  },
  "roaming": {
    "status": "unavailable"
  }
}

Create a phone number lookup

Anfrage-Nutzlast

Antwort-Payload

Verwandte Ressourcen