Klantgegevens verrijken
Bedrijfsgegevens aan je klantenlijst toevoegen.
Je hebt een lijst met bedrijfsnamen, plaatsen of registernummers en wilt er officiële bedrijfsgegevens aan toevoegen. Je hebt alleen fetch-organization nodig; eerst zoeken is niet nodig.
Bedrijven matchen
Stuur per klant één aanvraag met het beste gegeven dat je hebt. Registerrechtbank en registernummer zijn het beste, omdat ze eenduidig zijn. Heb je die niet, gebruik dan de bedrijfsnaam met rechtsvorm en plaats. Onze voorbeeldaanvraag zoekt Hetzner Online GmbH, Ansbach HRB 6089, op naam en plaats.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: JOUW_API_SLEUTEL" \ --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "JOUW_API_SLEUTEL"}, params={ "q": "Hetzner Online GmbH Gunzenhausen", }, ) data = response.json()
const url = new URL("https://handelsregister.ai/api/v1/fetch-organization"); url.searchParams.append("q", "Hetzner Online GmbH Gunzenhausen"); const response = await fetch(url, { headers: { "x-api-key": "JOUW_API_SLEUTEL" }, }); const data = await response.json();
1{2 "entity_id": "94eb910fef13f94585c48c263fa446d4",3 "name": "Hetzner Online GmbH",4 "status": "ACTIVE",5 "registration": {6 "court": "Ansbach",7 "register_type": "HRB",8 "register_number": "6089"9 },10 "address": {11 "house_number": "25",12 "street": "Industriestraße",13 "postal_code": "91710",14 "city": "Gunzenhausen",15 "county": "Weißenburg-Gunzenhausen",16 "state": "Bayern",17 "country": "DEU",18 "coordinates": {19 "latitude": 49.12483,20 "longitude": 10.7805221 }22 },23 "meta": {24 "request_credit_cost": 5,25 "credits_remaining": 14526 }27}
Controleer het antwoord tegen je gegevens, bijvoorbeeld de postcode of plaats in address. Bij veelvoorkomende namen kan anders een bedrijf met dezelfde naam terugkomen.
Sla de entity_id op bij je klant. Alle latere opvragingen, documenten, Signals en monitors lopen dan via deze identificatie.
ai_search=on-default) gericht voor vage vermeldingen; die kost 20 credits extra, ook zonder match.
Veel bedrijven ophalen
fetch-organization staat 60 aanvragen per minuut toe. Stuur de aanvragen gelijkmatig, na elkaar. Bij HTTP 429 wacht je het aantal seconden uit Retry-After. Heb je meer nodig, dan biedt Enterprise hogere limieten, zie Prijzen.
Geef elke aanvraag een Idempotency-Key, bijvoorbeeld het klantnummer. Herhaal je haar binnen 24 uur met dezelfde sleutel en dezelfde parameters, dan kost ze niets.
Bij HTTP 408 (de aanvraag duurde te lang) berekent de API niets, ook de AI-modus niet. Bij een fout met status 500 of hoger wordt alleen de AI-modus berekend, als je die hebt gekozen. Probeer het later opnieuw met dezelfde Idempotency-Key.
Het script leest klanten.csv met de kolommen id, name, city en register. De kolom register bevat het registernummer met rechtbank, zoals Ansbach HRB 6089, of niets. Het script schrijft een kopie met entity_id, registerrechtbank en registernummer en telt de verbruikte credits.
import csv import time import requests API = "https://handelsregister.ai/api/v1/fetch-organization" HEADERS = {"x-api-key": "JOUW_API_SLEUTEL", "Accept": "application/json"} PER_MINUTE = 60 # limiet van fetch-organization def lookup(row): # Registerrechtbank plus registernummer is uniek, anders naam en plaats q = row["register"] or f'{row["name"]} {row["city"]}' headers = {**HEADERS, "Idempotency-Key": f'klant-{row["id"]}'} for attempt in range(5): response = requests.get(API, params={"q": q}, headers=headers, timeout=120) if response.status_code == 429: time.sleep(int(response.headers.get("Retry-After", "10"))) elif response.status_code in (408, 500, 502, 503, 504): time.sleep(30 * (attempt + 1)) else: break return response spent = 0 with open("klanten.csv", newline="") as source, open("klanten_verrijkt.csv", "w", newline="") as target: reader = csv.DictReader(source) writer = csv.DictWriter(target, fieldnames=reader.fieldnames + ["entity_id", "registerrechtbank", "registernummer"]) writer.writeheader() for row in reader: response = lookup(row) if response.status_code == 402: print("Niet genoeg credits, run gestopt") break data = response.json() spent += data.get("meta", {}).get("request_credit_cost", 0) if response.status_code == 200: registration = data.get("registration") or {} row["entity_id"] = data["entity_id"] row["registerrechtbank"] = registration.get("court") row["registernummer"] = f'{registration.get("register_type")} {registration.get("register_number")}' writer.writerow(row) time.sleep(60 / PER_MINUTE) print(f"Verbruikt: {spent} credits")
Een tweede run binnen 24 uur kost niets. Het antwoord heeft dan Idempotency-Status: replayed en request_credit_cost 0.
1{2 "entity_id": "94eb910fef13f94585c48c263fa446d4",3 "name": "Hetzner Online GmbH",4 "meta": {5 "request_credit_cost": 0,6 "credits_remaining": 1457 }8}
enrich, een kant-en-klare verrijking voor CSV-, JSON- en Excel-bestanden.
Kosten in de gaten houden
Schat vooraf in met de prijslijst: 5 credits per bedrijf voor de basisgegevens, plus de prijs van elke feature. De basisgegevens kosten bij elke match. Features zonder gegevens kosten niets, dus de werkelijke kosten zijn vaak lager. De toeslagen zijn geen features: de AI-modus kost ook zonder match, Realtime bij elke geslaagde opvraging.
| Wat | Credits |
|---|---|
| Bedrijfsprofiel met de basisgegevens | 5 |
| Elke feature, alleen als die gegevens oplevert | 1 tot 80 |
| AI-modus, ook zonder match | +20 |
| Realtime, voor elke geslaagde live-opvraging | +10 |
Limiet: 60 aanvragen per minuut.
Wat een aanvraag werkelijk heeft gekost, staat in elk antwoord onder meta.request_credit_cost.
Wat een aanvraag kostte, staat in meta.request_credit_cost, het resterende saldo in meta.credits_remaining. Tel de kosten onderweg op, zoals in het script hierboven.
Vóór elke aanvraag controleert de API of je saldo de hoogst mogelijke prijs dekt. Is dat niet zo, dan antwoordt de API met HTTP 402 en berekent niets. Het script stopt dan.
Je saldo en gebruik kun je altijd gratis controleren via account.
Veelgemaakte fouten
- Registernummer zonder rechtbank: Staat er in je gegevens alleen „HRB 6089”, dan vindt de API geen bedrijf. Voeg de registerrechtbank toe of gebruik naam en plaats.
- Eén sleutel, één aanvraag: Dezelfde
Idempotency-Keymet andere parameters levert HTTP 422. Gebruik voor een gewijzigde aanvraag een nieuwe sleutel. - Formaat van de sleutel: Tot 128 tekens uit letters, cijfers en
. _ : -zijn toegestaan, beginnend met een letter of cijfer. Een sleutel in een ander formaat negeert de API. De aanvraag loopt dan zonder deze bescherming. - Timeout: Met Realtime of veel features duurt een aanvraag langer. Stel de timeout van je client in op minstens 120 seconden.