# Een telefoonnummer opzoeken

Eén aanroep beantwoordt wat een nummer is. Alles hier vereist een API-sleutel met het `lookup`-bereik.

## Een basiszoekopdracht uitvoeren

Stuur het nummer en niets anders. De basiszoekopdracht wordt altijd één keer gefactureerd en beantwoordt altijd het land, het bedienende netwerk, het uitgevende netwerk en een globaal lijntype.

**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](/nl-nl/documentatie/guides/lookup/phone-numbers.ts.md) · [Python](/nl-nl/documentatie/guides/lookup/phone-numbers.py.md) · [Go](/nl-nl/documentatie/guides/lookup/phone-numbers.go.md) · [PHP](/nl-nl/documentatie/guides/lookup/phone-numbers.php.md) · [CLI](/nl-nl/documentatie/guides/lookup/phone-numbers.cli.md) · [MCP](/nl-nl/documentatie/guides/lookup/phone-numbers.mcp.md) · [cURL](/nl-nl/documentatie/guides/lookup/phone-numbers.curl.md)

## Hoe je het nummer schrijft

Stuur de landcode en dan het nationale nummer. De voorloop-`+` is optioneel en `00` werkt ook, dus `+31612345678`, `31612345678` en `0031612345678` zijn allemaal hetzelfde nummer.

Een nummer dat is geschreven om binnen één land te bellen, zonder landcode, wordt geweigerd in plaats van geraden. `0612345678` retourneert [`E22000`](/docs/api/errors/E22000), omdat het toevoegen van een landcode een bestaand nummer ergens anders zou aanduiden en je gefactureerd zou worden voor het opzoeken ervan.

## Wat de basisopzoeking beantwoordt

`country_code` is het land van het nummer, afwezig wanneer het nummer niet tot één land behoort, zoals bij een niet-geografisch nummerbereik.

`network_info` is het netwerk dat het nummer nu bedient, en `original_network_info` is het netwerk dat het bereik heeft uitgegeven. De twee verschillen wanneer het nummer is geporteerd, en in dat geval bevat `flags` de waarde `ported`.

`line_type` is het type lijn van het nummer: `mobile`, `fixed_line`, `voip`, `toll_free`, `premium_rate`, `satellite`, `pager`, `payphone`, `m2m`, `service`, `other` of `unknown`. `unknown` betekent dat het carrierplatform geen classificatie heeft voor het bereik; `other` betekent dat het er wel een heeft zonder equivalent hier. Vraag voor de toegewezen dienst op fijnere precisie de property `classification` op. Die beantwoordt vanuit een andere bron met een bredere woordenschat en wordt apart gerapporteerd zodat je de twee altijd kunt onderscheiden.

## Properties toevoegen

Geef de gewenste properties op in `type`. Elke property wordt apart gefactureerd en alleen als deze geleverd is.

| Property         | Wat het beantwoordt                                                                          |
| ---------------- | -------------------------------------------------------------------------------------------- |
| `classification` | De precieze toegewezen dienst van het bereik: premium rate, satelliet, M2M, telefooncel.     |
| `porting`        | Wanneer het nummer voor het laatst van netwerk is gewisseld, en elke wissel in het register. |
| `presence`       | Of het nummer momenteel actief is op het netwerk.                                            |
| `roaming`        | Of het nummer roamt, en op welk netwerk.                                                     |
| `sim_swap`       | Wanneer de simkaart voor het laatst is gewisseld.                                            |
| `score`          | Een geloofwaardigheidsscore van 0 tot 100.                                                   |

`classification`, `porting` en `score` lezen opgeslagen data en antwoorden snel. `presence`, `roaming` en `sim_swap` benaderen het live netwerk, dus ze zijn trager en hun dekking verschilt per operator. Verwacht `unavailable` of `inconclusive` hierbij vaker dan bij de opgeslagen properties.

Twee properties beantwoorden vragen die de basisopzoeking al aanraakt, maar op hogere resolutie. `porting` geeft je de datum en de volledige geschiedenis, terwijl de `ported`-vlag van de basisopzoeking alleen aangeeft of er ooit een wissel heeft plaatsgevonden. `classification` vertaalt `line_type` naar de exacte toegewezen dienst.

## Lees de status vóór de waarde

Elk propertyblok bevat een `status`, en alleen `ok` bevat een waarde.

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

In dat antwoord is je de basisopzoeking en `classification` gefactureerd. `score` is je niet gefactureerd.

Lees `status` eerst en behandel alles anders dan `ok` als "not answered". Het is een open vocabulaire, dus een waarde die je niet herkent is een toekomstige status, geen fout.

Twee blokken rapporteren een grens in plaats van een exact getal wanneer het netwerk er geen vrijgeeft. `sim_swap` retourneert `min_days` en `max_days` in plaats van `last_swapped_at` wanneer alleen een recentheidsband bekend is. `porting` zet `last_ported_at_is_approximate` wanneer een register de periode van een wissel vastlegt maar niet de dag.

Eén veld leest als negatief maar is een positieve bevinding: `porting.ported` met waarde `false` betekent dat het register is geraadpleegd en geen wissel voor dit nummer bevat, niet dat er niets gecontroleerd kon worden. Dat onderscheid is waarvoor `status` dient.

## Opnieuw proberen zonder dubbel te betalen

Een opzoeking wordt gefactureerd, dus een herhaald verzoek mag geen tweede antwoord kopen. Stuur een `Idempotency-Key` mee en een herhaling van hetzelfde verzoek speelt het opgeslagen antwoord af in plaats van een nieuwe opzoeking uit te voeren. Zie [Idempotentie](/docs/guides/idempotency).

De `GET`-vorm van deze operatie, die het nummer in de URL plaatst, kan geen idempotentiesleutel meesturen. Gebruik de `POST`-vorm voor alles wat geautomatiseerd is.

## Fouten

| Code                                | Wat er gebeurde                                                                                                             |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| [`E22000`](/docs/api/errors/E22000) | Het nummer is geen geldig telefoonnummer in internationaal formaat. Er is niets in rekening gebracht.                       |
| [`E22001`](/docs/api/errors/E22001) | De wallet van de organisatie dekt de opzoeking niet. Laad deze op en probeer het opnieuw. Er is niets in rekening gebracht. |
| [`E22002`](/docs/api/errors/E22002) | Opzoeking is tijdelijk niet beschikbaar. Probeer opnieuw met backoff. Er is niets in rekening gebracht.                     |

Een falende property is geen fout. Deze komt terug als status op het blok, terwijl de basisopzoeking gewoon meegeleverd wordt.

## Volgende stappen

- [Een e-mailadres opzoeken](/docs/guides/lookup/email-addresses) is de andere helft van Lookup.
- [Lookup API-referentie](/docs/api/reference/create-phone-number-lookup) documenteert elk veld en elk propertyblok.
- [Rate limits](/docs/guides/rate-limits) beschrijft de `lookup`-bucket waaruit deze aanroepen putten.
- [Telefoonnummer opzoeken: controleer een nummer voordat je verzendt](/learn/lookup/phone-number-lookup-check-a-number-before-you-send) is een video die een opzoeking uitvoert en de live netwerkcontroles toevoegt.

## Related resources

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

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