> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Telefonnummern-Validierungs-API

> Schnelle RESTful JSON-API von Cleariflow für strukturelle Telefonvalidierung, E.164-Normalisierung und optionale Carrier-, Standort-, Zeitzonen- und Erreichbarkeitsdaten.

Die Nutzung ist sehr einfach: Übermitteln Sie Ihren API-Schlüssel und eine Telefonnummer. Die API gibt zurück, ob die Nummer **strukturell gültig** ist, und bei gültigen Nummern normalisierte E.164-Formate sowie optionale Angaben wie Leitungstyp, Standorthinweise, Carrier-Daten, Zeitzonen und Erreichbarkeit, sofern verfügbar.

<Note>
  `valid: true` bedeutet, dass die Nummer den regionalen Formatregeln entspricht (Länge, Präfix, Syntax). Es bestätigt **nicht**, dass die Leitung aktiv ist, einem Teilnehmer zugewiesen oder erreichbar ist. Für den Live-Leitungsstatus benötigen Sie carrier lookup, was außerhalb dieses API liegt.
</Note>

## Erste Schritte

### REST

Die Telefonnummern-Validierungs-API ist wie alle Cleariflow-APIs um REST herum aufgebaut. Sie verwendet vorhersehbare, ressourcenorientierte URLs und HTTP-Statuscodes zur Fehleranzeige.

### HTTPS

Die Telefonnummern-Validierungs-API erfordert, dass alle Kommunikation mit TLS 1.2 oder höher gesichert ist.

### API-Versionen

Alle Cleariflow-APIs sind versioniert. Die Telefonnummern-Validierungs-API befindet sich derzeit in Version 1.

### Ihr API-Schlüssel

Ihr API-Schlüssel ist Ihr eindeutiger Authentifizierungsschlüssel für die Cleariflow Telefonnummern-Validierungs-API. Beachten Sie, dass jede Cleariflow-API einen eigenen API-Schlüssel hat — Sie benötigen also unterschiedliche Schlüssel für die Telefonnummern-Validierung und die E-Mail-Validierung. Zur Authentifizierung Ihrer Anfragen hängen Sie Ihren API-Schlüssel an die Basis-URL an.

### Basis-URL

```
https://phonevalidation.cleariflow.com/v1/
```

### Was `valid` bedeutet

| `valid` | Bedeutung                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `true`  | Die Nummer ist für ihre erkannte Region strukturell gültig.                                                                                                                                                                                                                                                                                                                                                 |
| `false` | Die Nummer konnte nicht geparst werden oder entspricht nicht den regionalen Formatregeln. `format`, `country`, `location`, `type`, `carrier`, `carrier_display`, `timezones`, `geographical` und `internationally_dialable` sind immer leer oder false; `possible` und `invalid_reason` werden weiterhin befüllt, wenn die Eingabe analysiert werden konnte. `phone` enthält nur Ziffern aus Ihrer Eingabe. |

Fiktive US-555-Nummern und andere strukturell gültige, aber nicht zugewiesene Nummernbereiche können weiterhin `valid: true` zurückgeben. `carrier` und `location` werden hauptsächlich für US/CA-Nummern befüllt und sind anderswo oft leer.

### Validierungs-Endpunkt

Die API benötigt Ihren eindeutigen API-Schlüssel und die zu prüfende Telefonnummer:

```
https://phonevalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& phone = 14155552671
& country = US
```

**Gültige Antwort** (`phone=14155552671`, `country=US`):

<ResponseExample>
  ```json theme={"system"}
  {
    "phone": "14155552671",
    "valid": true,
    "possible": true,
    "format": {
      "international": "+14155552671",
      "local": "(415) 555-2671"
    },
    "country": {
      "code": "US",
      "name": "United States",
      "prefix": "+1"
    },
    "location": "San Francisco, CA",
    "type": "Landline_or_Mobile",
    "carrier": "",
    "carrier_display": "",
    "timezones": ["America/Los_Angeles"],
    "geographical": true,
    "internationally_dialable": true
  }
  ```
</ResponseExample>

**Ungültige Antwort** (`phone=123`, `country=US`):

```json theme={"system"}
{
  "phone": "123",
  "valid": false,
  "possible": false,
  "invalid_reason": "too_short",
  "format": {
    "international": "",
    "local": ""
  },
  "country": {
    "code": "",
    "name": "",
    "prefix": ""
  },
  "location": "",
  "type": "Unknown",
  "carrier": "",
  "carrier_display": "",
  "timezones": null,
  "geographical": false,
  "internationally_dialable": false
}
```

### Anfrageparameter

<ParamField query="api_key" type="String" required>
  Ihr eindeutiger API-Schlüssel. Beachten Sie, dass jeder Benutzer eindeutige API-Schlüssel *für jede der Cleariflow-APIs* hat — Ihr Phone Validation API-Schlüssel funktioniert beispielsweise nicht für die IP-Geolocation-API.
</ParamField>

<ParamField query="phone" type="String" required>
  Die zu validierende Telefonnummer (strukturelle Prüfung gemäß ).
</ParamField>

<ParamField query="country" type="String">
  Optionaler ISO 3166-1 alpha-2-Hinweis für nationale Nummern ohne führendes `+`. Beispielsweise hilft `country=US` beim Parsen von `4155552671`. Nummern mit internationalem Präfix werden anhand ihrer Ländervorwahl geparst; der erkannte `country.code` in der Antwort kann von diesem Hinweis abweichen (z. B. `GG` für einige `+44`-Mobilbereiche).
</ParamField>

### Antwortparameter

Die API-Antwort wird in einem universellen und leichten [JSON-Format](https://www.json.org/json-en.html) zurückgegeben.

<ResponseField name="phone" type="String">
  Normalisierte E.164-Ziffern (ohne `+`), wenn `valid` true ist. Wenn `valid` false ist, nur Ziffern aus Ihrer Eingabe.
</ResponseField>

<ResponseField name="valid" type="Boolean">
  `true`, wenn die Nummer gemäß  strukturell gültig ist. Dies ist **keine** Leitungsstatus- oder Teilnehmerverifizierung.
</ResponseField>

<ResponseField name="possible" type="Boolean">
  Nachsichtige Längenprüfung (). `true`, wenn Ziffern und Länge zu einer echten Nummer gehören könnten, auch wenn `valid` false ist.
</ResponseField>

<ResponseField name="invalid_reason" type="String">
  Vorhanden, wenn `valid` false ist. Einer von: `not_a_number`, `possible`, `possible_local_only`, `invalid_country_code`, `too_short`, `invalid_length`, `too_long`, `unknown`. Wird bei `valid` true weggelassen.
</ResponseField>

<ResponseField name="format" type="Object">
  `international`- und `local`-Formate. Leere Zeichenketten, wenn `valid` false ist.
</ResponseField>

<ResponseField name="format.international" type="String">
  E.164-Format mit führendem `+`. Leer, wenn `valid` false ist.
</ResponseField>

<ResponseField name="format.local" type="String">
  Nationales Format für die erkannte Region. Leer, wenn `valid` false ist.
</ResponseField>

<ResponseField name="country" type="Object">
  Erkanntes Land/Gebiet. Leere Felder, wenn `valid` false ist.
</ResponseField>

<ResponseField name="country.code" type="String">
  Zweistelliger [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)-Code für die erkannte Region.
</ResponseField>

<ResponseField name="country.name" type="String">
  Englischer Anzeigename für `country.code`.
</ResponseField>

<ResponseField name="country.prefix" type="String">
  Internationale [Ländervorwahl](https://en.wikipedia.org/wiki/List_of_country_calling_codes) (z. B. `+1`).
</ResponseField>

<ResponseField name="location" type="String">
  Geocoding-Hinweis (Region, Bundesland/Provinz oder Stadt). Außerhalb von US/CA oft leer. Leer, wenn `valid` false ist.
</ResponseField>

<ResponseField name="type" type="String">
  Leitungstyp, wenn `valid` true ist: `Landline`, `Mobile`, `Landline_or_Mobile`, `Toll_Free`, `Premium`, `Paging`, `Special` oder `Unknown`. Immer `Unknown`, wenn `valid` false ist.
</ResponseField>

<ResponseField name="carrier" type="String">
  Betreibername, sofern verfügbar (meist US/CA). Andernfalls leere Zeichenkette, auch wenn `valid` false ist.
</ResponseField>

<ResponseField name="carrier_display" type="String">
  Sicherer Carrier-Name für die Anzeige an Endnutzer (wenn gültig und die Region keine Mobile Number Portability nutzt). Leer bei `valid` false oder wenn der Carrier nicht sicher angezeigt werden kann.
</ResponseField>

<ResponseField name="timezones" type="Array">
  Zeitzonen-IDs für die Nummer (z. B. `America/New_York`). Leeres Array bei `valid` true ohne Zuordnung; `null` bei `valid` false.
</ResponseField>

<ResponseField name="geographical" type="Boolean">
  Ob die Nummer einer geografischen Region zugeordnet ist. Immer `false`, wenn `valid` false ist.
</ResponseField>

<ResponseField name="internationally_dialable" type="Boolean">
  Ob die Nummer von außerhalb der Heimatregion gewählt werden kann. Immer `false`, wenn `valid` false ist.
</ResponseField>

## Massen-Upload (CSV)

Best Practices beim Massen-Upload einer CSV-Datei:

* Stellen Sie sicher, dass die erste Spalte die zu analysierenden Telefonnummern enthält.
* Entfernen Sie leere Zeilen aus der Datei.
* Fügen Sie nur eine Telefonnummer pro Zeile ein.
* Die maximal zulässige Dateigröße beträgt 50.000 Zeilen.

## Antwort- und Fehlercodes

Wenn eine Anfrage aus irgendeinem Grund fehlschlägt, wird ebenfalls ein Fehler im JSON-Format zurückgegeben. Die Fehler enthalten einen Fehlercode und eine Beschreibung — Details finden Sie unten.

| Code | Type                  | Details                                                                                                                                                               |
| ---- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200  | OK                    | Alles hat wie erwartet funktioniert.                                                                                                                                  |
| 400  | Bad request           | Ungültige Anfrage.                                                                                                                                                    |
| 401  | Unauthorized          | Die Anfrage war nicht akzeptabel. Typischerweise wegen fehlendem oder falschem API-Schlüssel.                                                                         |
| 422  | Quota reached         | Die Anfrage wurde wegen unzureichender API-Credits abgebrochen. (Kostenlose Tarife)                                                                                   |
| 429  | Too many requests     | Die Anfrage wurde abgebrochen, weil die zulässige Anzahl an Anfragen pro Sekunde erreicht wurde. Bei kostenlosen Tarifen ist dies auf 1 Anfrage pro Sekunde begrenzt. |
| 500  | Internal server error | Die Anfrage konnte wegen eines Serverfehlers nicht abgeschlossen werden.                                                                                              |
| 503  | Service unavailable   | Der Server war nicht verfügbar.                                                                                                                                       |

## Sonstige Hinweise

Hinweis zur nutzungsbasierten Abrechnung: Jede einzelne übermittelte Telefonnummer zählt als ein verwendeter Credit. Credits werden pro Anfrage gezählt, nicht pro erfolgreicher Antwort. Eine Anfrage mit der (ungültigen) Telefonnummer „kasj8929hs“ verbraucht also trotzdem 1 Credit.