B2B Data

De API

Dezelfde database als het scherm, rechtstreeks in je eigen systeem. Zoeken op alle filters, een bedrijf opvragen op KVK-nummer, en een lijst nummers omzetten naar volledige regels.

Een sleutel maken

Log in op de tool en ga naar Instellingen. Daar maak je een sleutel aan en zie je hem één keer. Wij bewaren hem niet, alleen zijn vingerafdruk en de eerste twaalf tekens, dus schrijf hem meteen op. Kwijt is kwijt: dan trek je hem in en maak je een nieuwe. Je mag er vijf tegelijk open hebben staan.

Meesturen

Elk verzoek heeft de sleutel nodig. Twee vormen, kies er één:

Authorization: Bearer b2b_1234abcd…
x-api-key: b2b_1234abcd…

Zonder sleutel krijg je 401, met een ingetrokken sleutel ook. Het basisadres is https://mijnb2bdata.nl/v1.

De ingangen

GET /v1/tellen gratis

Hoeveel bedrijven voldoen aan een filter. Telt niet mee voor je limiet, dus je mag hier zo vaak op vragen als je wil. Filters geef je mee als queryparameter; een meerkeuzefilter scheid je met komma's.

curl -H "x-api-key: $SLEUTEL" \
  "https://mijnb2bdata.nl/v1/tellen?provincies=Utrecht,Flevoland&mw_min=10"

{ "treffers": 78681, "geschat": false }

GET /v1/bedrijf 1 rij

Eén bedrijf. kvk mag acht cijfers zijn (dan krijg je de hoofdvestiging), twaalf cijfers, of een vestigingsnummer.

curl -H "x-api-key: $SLEUTEL" \
  "https://mijnb2bdata.nl/v1/bedrijf?kvk=33002587"

{ "bedrijf": {
    "bedrijfsnaam": "NatWest Markets N.V.",
    "kvk": "330025870000", "kvk_nummer": "33002587",
    "vestigingsnummer": "000020381977",
    "postcode": "1082MD", "plaatsnaam": "Amsterdam", "provincie": "Noord-Holland",
    "sbi": "6419", "sbi_omschrijving": "Overige geldscheppende financiële instellingen",
    "medewerkers_kl": "6: 100 tot 199",
    "telefoonnummer": "+31204642699", "emailadres": null, "website": null,
    "linkedin_url": "https://www.linkedin.com/company/natwest",
    "kl_totaal": null, "kl_lease": null, "lease_zekerheid": null } }

Niet gevonden geeft 404.

POST /v1/zoek per rij

Zoeken met dezelfde filters als het scherm. Hoogstens 1000 rijen per verzoek; met offset blader je verder. Zonder limit krijg je er vijftig.

curl -X POST -H "x-api-key: $SLEUTEL" -H "content-type: application/json" \
  https://mijnb2bdata.nl/v1/zoek \
  -d '{"filters":{"provincies":["Utrecht"],"mw_min":50,"vracht_min":3},"limit":100}'

{ "aantal": 100, "limit": 100, "offset": 0, "rijen": [ … ] }

Wil je eerst weten hoe groot het is, vraag dan /v1/tellen met hetzelfde filter. Dat kost niets.

POST /v1/verrijk per gevonden rij

Je eigen lijst nummers erin, volledige regels eruit. Acht cijfers is een KVK-nummer, twaalf een vestigingsnummer; beide mogen door elkaar in dezelfde lijst. Hoogstens 10.000 per verzoek. Wat wij niet kennen komt terug in niet_gevonden en kost niets.

curl -X POST -H "x-api-key: $SLEUTEL" -H "content-type: application/json" \
  https://mijnb2bdata.nl/v1/verrijk \
  -d '{"sleutels":["33002587","000020381977","00000001"]}'

{ "gevraagd": 3, "gevonden": 2, "niet_gevonden": ["00000001"], "rijen": [ … ] }

Elke rij begint met sleutel: het nummer zoals jij het aanleverde. Zo leg je het antwoord naast je eigen bestand zonder te hoeven zoeken welke regel bij welke hoort.

GET /v1/filters gratis

De namen van alle filters die wij aannemen, gesplitst in meerkeuze en enkelvoudig. Handig om te controleren of je een naam goed hebt: een filter dat wij niet kennen wordt stilzwijgend genegeerd, en dan krijg je te veel rijen in plaats van een foutmelding.

Filters

Een meerkeuzefilter geef je als lijst, of als object met mode om hem om te draaien:

"provincies": ["Utrecht", "Flevoland"]
"provincies": { "mode": "not", "v": ["Limburg"] }

De meest gebruikte:

Filter	Soort	Wat het doet
`q`	tekst	Zoekt in bedrijfsnaam, plaats en adres
`provincies`, `gemeenten`, `plaatsen`	meerkeuze	Plaatsbepaling
`pc4_van`, `pc4_tot`	getal	Postcodegebied van en tot
`sbi1` t/m `sbi4`	meerkeuze	Sector, van hoofdgroep naar detail
`mw_min`, `mw_max`	getal	Aantal medewerkers
`vracht_min`, `bedrijfs_min`, `personen_min`, `bus_min`	getal	Minstens zoveel voertuigen van die soort
`totaal_min`, `totaal_max`	getal	Omvang van het hele wagenpark
`lease_min`, `lease_pa_min`, `lease_ba_min`	getal	Geschatte leasevoorraad
`heeft_telefoon`, `heeft_email`, `heeft_website`, `heeft_linkedin`	ja/nee	Alleen bedrijven waar dat bij staat
`excl_nonmailing`	ja/nee	Laat bedrijven met een non-mailingvlag weg
`hoofdvestiging`, `uniek_concern`	ja/nee	Eén regel per bedrijf in plaats van per vestiging
`opgericht_van`, `opgericht_tot`	datum	Oprichtingsdatum, als `2020-01-01`
`ids`	meerkeuze	Precies deze vestigingsnummers, verder niets

De volledige lijst haal je op met /v1/filters, of je bouwt de selectie in het scherm en leest de filters af aan de chips boven de tabel.

Wat het kost

Rijen die het pand uit gaan tellen mee voor de exportlimiet van je abonnement, precies zoals een export in het scherm. Eén rij is één vestiging. Tellen en de filterlijst zijn gratis. Op het tabblad Verbruik zie je per moment waar het verbruik vandaan komt: de API staat er als zoek, bedrijf of verrijk.

Vraag eerst /v1/tellen en dan pas /v1/zoek. Dat scheelt je een selectie van tienduizend rijen die je achteraf toch weggooit, en tellen kost niets.

Foutmeldingen

Code	Wat er aan de hand is
`400`	Verzoek klopt niet: een veld ontbreekt of de lijst is te lang
`401`	Geen sleutel meegestuurd, of de sleutel is ingetrokken
`402`	Exportlimiet van deze maand bereikt. Er is niets afgeschreven
`404`	Onbekend adres, of het bedrijf bestaat niet bij ons
`405`	Verkeerde methode: `zoek` en `verrijk` zijn POST
`500`	Aan onze kant. Probeer het zo nog eens

Elke fout komt terug als JSON met een veld fout waarin in gewoon Nederlands staat wat er mis is.

Wat je met de gegevens mag doen

De gegevens zijn voor gebruik binnen je eigen organisatie. Doorverkopen of doorleveren aan derden mag niet. Voor eenmanszaken, VOF's en maatschappen is vooraf toestemming nodig voordat je ze belt; dat is wettelijk zo geregeld en staat los van waar de gegevens vandaan komen. Bedrijven met een non-mailingvlag sluit je uit met excl_nonmailing. De volledige voorwaarden staan op de voorpagina.

Aantallen voertuigen per bedrijf komen naar buiten als klasse en niet als getal. Dat is geen onmacht maar een afspraak met de bron: een voertuig mag niet aan een bedrijf te koppelen zijn. Optellingen over een hele selectie zijn wel gewone getallen.