Erforderliche Header

Body

* Mindestens ein unterscheidendes Kriterium neben first_name + last_name erforderlich: birth_date, email, mobile, landline, phone oder vollständige Adresse (address.street + address.city + address.postal_code). Sonst HTTP 400 insufficient_data.

Die Felder email, mobile, landline und phone akzeptieren den Klartextwert ODER seinen MD5- (32 Hex) / SHA256-Hash (64 Hex), automatisch erkannt. Der Hash wird auf der kanonischen Form berechnet (E-Mail in Kleinbuchstaben; französische nationale Rufnummer mit 10 Ziffern). Ein gehashtes Feld gibt nur match oder no_match zurück.

Antwort 200

Code

curl -X POST https://verify.zecible.fr/api/person \
  -H 'X-API-Key: vkey-...' \
  -H 'Content-Type: application/json' \
  -d '{
    "reference": "tx-001",
    "person": {
      "first_name": "Jean",
      "last_name": "Dupont",
      "birth_date": "1980-05-15"
    }
  }'

const r = await fetch('https://verify.zecible.fr/api/person', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.VERIFY_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reference: 'tx-001',
    person: { first_name: 'Jean', last_name: 'Dupont', birth_date: '1980-05-15' }
  })
});
const data = await r.json();
console.log(data.score, data.matches);

import requests, os
r = requests.post(
    'https://verify.zecible.fr/api/person',
    headers={'X-API-Key': os.environ['VERIFY_KEY']},
    json={
        'reference': 'tx-001',
        'person': {'first_name': 'Jean', 'last_name': 'Dupont', 'birth_date': '1980-05-15'}
    }
)
print(r.json()['score'])

<?php
$ch = curl_init('https://verify.zecible.fr/api/person');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-API-Key: ' . getenv('VERIFY_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'reference' => 'tx-001',
        'person'    => ['first_name' => 'Jean', 'last_name' => 'Dupont', 'birth_date' => '1980-05-15'],
    ]),
]);
$data = json_decode(curl_exec($ch), true);
echo $data['score'];

Erforderliche Header

Body

* Mindestens eines von: business.siret, business.siren oder business.name + (business.address.city ODER business.address.postal_code). executives[]: bis zu 10 Einträge pro Anfrage (sonst HTTP 400 too_many_executives). Unabhängiges Best-Match-Scoring für jeden Eintrag gegen alle Kontakte des SIRET des gematchten Unternehmens (max. 100 Kontakte/SIRET). Bei ambiguous=true bleibt der Pool auf Level 1 der Pipeline beschränkt.

Die Felder siren, email, mobile, landline und phone akzeptieren den Klartextwert ODER seinen MD5- (32 Hex) / SHA256-Hash (64 Hex), automatisch erkannt (siren: 9 reine Ziffern). Ein gehashtes Feld gibt nur match oder no_match zurück.

Antwort 200

Code

curl -X POST https://verify.zecible.fr/api/business \
  -H 'X-API-Key: vkey-...' \
  -H 'Content-Type: application/json' \
  -d '{
    "reference": "tx-biz-001",
    "business": {
      "siret": "00000000000000",
      "name": "ACME SAS",
      "legal_form": "SAS"
    },
    "executives": [
      { "first_name": "Jean", "last_name": "DUPONT", "role": "président" }
    ]
  }'

const r = await fetch('https://verify.zecible.fr/api/business', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.VERIFY_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reference: 'tx-biz-001',
    business: { siret: '00000000000000', name: 'ACME SAS' },
    executives: [{ first_name: 'Jean', last_name: 'DUPONT' }]
  })
});
console.log((await r.json()).score);

import requests, os
r = requests.post(
    'https://verify.zecible.fr/api/business',
    headers={'X-API-Key': os.environ['VERIFY_KEY']},
    json={
        'reference': 'tx-biz-001',
        'business': {'siret': '00000000000000', 'name': 'ACME SAS'},
        'executives': [{'first_name': 'Jean', 'last_name': 'DUPONT'}]
    }
)
print(r.json()['score'])

<?php
$ch = curl_init('https://verify.zecible.fr/api/business');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-API-Key: ' . getenv('VERIFY_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'reference'  => 'tx-biz-001',
        'business'   => ['siret' => '00000000000000', 'name' => 'ACME SAS'],
        'executives' => [['first_name' => 'Jean', 'last_name' => 'DUPONT']],
    ]),
]);
$data = json_decode(curl_exec($ch), true);
echo $data['score'];

Erforderliche Header

Query-Parameter

Antwort 200

Code

curl 'https://verify.zecible.fr/api/usage?start=2026-05-01&stop=2026-05-31' \
  -H 'X-API-Key: vkey-...'

Antwort-Header (alle Antworten)

HTTP-Antwort 429 (Kontingent überschritten)

Empfohlene Strategie

• X-RateLimit-Remaining bei jeder Antwort auslesen, um clientseitiges Throttling zu antizipieren.
• Bei HTTP 429 den Retry-After-Wert abwarten, bevor ein erneuter Versuch gestartet wird (exponentielles Backoff unnötig: das Fenster resettet zur genauen Minute).
• Für Volumen > 60 Anfragen/Min. ein erhöhtes Kontingent anfragen: Kontakt aufnehmen.
• Der Zähler startet mit der ersten Anfrage jeder UTC-Minute, unabhängig vom aufgerufenen Endpoint.

Beispiel einer 429-Antwort

# HTTP 429 Too Many Requests
# Headers
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1779994620
Retry-After: 42

# Body
{
  "error":      "rate_limit_exceeded",
  "message":    "Limite de 60 requetes par minute atteinte. Reessayer dans 42s.",
  "limit":      60,
  "reset_unix": 1779994620
}

Authentifizierung (401)

HTTP-Methode (405)

Body-Validierung (400)

Feldvalidierung (HTTP 200, Status invalid)

Diese Codes sind keine HTTP-Fehler: die Anfrage liefert 200. Das ungültige Feld wird ignoriert (von der Suche ausgeschlossen) und in matches.<Feld>.status = invalid gemeldet, der Code erscheint in error. Sonderfall: Lässt ein ungültiges siret/siren keine verwertbare Kennung übrig, wird die Anfrage stattdessen mit missing_required_fields / insufficient_data (400) abgelehnt.

Payload-Größe (413)

Kontingente (429)

Credits / Budget (402)

Antwortformat

# HTTP 4xx
# Content-Type: application/json; charset=UTF-8

{
  "error":   "invalid_birth_date",
  "message": "person.birth_date doit etre au format ISO 8601 (YYYY-MM-DD)."
}

Das Feld error ist stabil und für die programmatische Verarbeitung bestimmt. Das Feld message ist für die Anzeige vorgesehen und kann sich zwischen Versionen ändern.