Dezelfde bedrijven, in je eigen systeem.

Een sleutel

Maak een sleutel aan bij Koppelingen in je account. Kies alleen lezen als het systeem alleen hoeft te kijken, of lezen en schrijven als het contacten en links moet aanmaken. De sleutel wordt één keer getoond. Stuur hem bij elke aanroep mee: Inloggen

Authorization: Bearer sk_live_…

Elke aanroep gaat naar https://swungby.com/api/v1/ en geeft JSON terug.

Hoe een antwoord eruitziet

Altijd hetzelfde omhulsel: bij succes data en meta, bij een fout errors en meta. In meta staat altijd een request_id; dat nummer mail je ons als iets niet klopt, dan vinden we het meteen terug.

{
  "data": { "client": { "id": 5, "name": "Dutch Leads" } },
  "meta": { "request_id": "8a3f…" }
}

GET /api/v1/meWie ben ik

De klant en de sites bij deze sleutel, wat de sleutel mag, en het verbruik van deze maand. De eerste aanroep die iedereen doet.

curl https://swungby.com/api/v1/me \
  -H "Authorization: Bearer sk_live_…"

GET /api/v1/companiesDe bedrijven die langskwamen

Dezelfde lijst als in je scherm: laatste bezoek eerst, met per bedrijf hoe zeker we zijn (certain, probable, uncertain), waaraan we het herkenden, de bekeken pagina's, de toestand, wie het heeft, de contactpersonen met hun herkomst, en via welk kanaal het laatste bezoek binnenkwam (last_channel: search, social, email, campaign, referral of direct, met de naam in last_channel_name). Filter met status=open of all.

curl "https://swungby.com/api/v1/companies?limit=50&status=open" \
  -H "Authorization: Bearer sk_live_…"

GET /api/v1/visitsLosse bezoeken

Elk bezoek van een herkend bedrijf, met de pagina's, de tijd en het kanaal waarlangs het binnenkwam (channel en channel_name). Filter op één bedrijf met company_id, of op een tijdstip met since.

curl "https://swungby.com/api/v1/visits?company_id=cmp_4821&since=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer sk_live_…"

POST /api/v1/contactsContacten erin

Je contacten, hoogstens duizend per aanroep. Dezelfde regels als de upload in het scherm: een echt e-mailadres, kleine letters, en alleen gekoppeld aan bedrijven die wij al kennen. Een fout adres krijgt een aanwijzer naar de rij.

curl -X POST https://swungby.com/api/v1/contacts \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "contacts": [ { "email": "jan@acme.nl", "name": "Jan", "job_title": "Inkoop" } ] }'

POST /api/v1/click-tokensLinks met een token voor je mails

Per ontvanger een link naar een pagina op je site. Wie erop klikt, herkennen we met zekerheid, ook vanaf een telefoon of thuis. Onbekende adressen worden meteen als contact opgeslagen, dus één aanroep is genoeg. De campagnenaam reist mee in het token en is in de link niet te zien.

curl -X POST https://swungby.com/api/v1/click-tokens \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "destination": "https://jouwsite.nl/aanbod", "campaign": "najaar",
        "contacts": [ { "email": "jan@acme.nl" } ] }'

Bladeren

Lijsten geven hoogstens 200 rijen per keer, standaard 25. Staat in meta.pagination has_more op true, dan stuur je next_starting_after mee als starting_after voor de volgende pagina. Er is geen totaal: dat kost een telling over een lijst die alleen maar groeit, en je hebt hem niet nodig om door te bladeren.

Als iets misgaat

Een fout heeft altijd een code voor je programma en een zin voor jou. Bij een verkeerd veld staat er een aanwijzer bij, zoals /contacts/12/email.

missing_token

Geen sleutel meegestuurd.

invalid_token

Deze sleutel kennen we niet.

token_revoked

De sleutel is ingetrokken.

insufficient_scope

Deze sleutel mag alleen lezen.

validation_failed

Een veld klopt niet; kijk naar de aanwijzer.

not_found

Dit bestaat niet, of hoort niet bij jou. Dat onderscheid maken we bewust niet.

rate_limit_exceeded

Te snel achter elkaar; wacht het aantal seconden in Retry-After.

Hoe snel je mag

Twintig aanroepen per seconde en zeshonderd per minuut per account. Elk antwoord zegt in X-RateLimit-Remaining hoeveel je nog hebt; dat getal is bij benadering, want het wordt per server bijgehouden. Ruim genoeg om elke ochtend je hele lijst op te halen.

Webhooks

Een bericht naar jouw adres zodra er een nieuw bedrijf is herkend: één keer per bedrijf, met dezelfde inhoud als GET /companies. Maak hem aan bij Koppelingen of via POST /webhooks; het geheim krijg je één keer. Elke levering draagt een handtekening in de kop X-Signature, en die controleer je zo:

// Node.js
const [t, v1] = req.headers["x-signature"].split(",").map((d) => d.split("=")[1]);
const verwacht = crypto.createHmac("sha256", geheim).update(t + "." + rawBody).digest("hex");
const klopt = verwacht === v1 && Math.abs(Date.now() / 1000 - Number(t)) < 300;

Antwoord met een 2xx binnen tien seconden. Lukt dat niet, dan proberen we het opnieuw na 30 seconden, 2 minuten, 10 minuten, een uur, zes uur en een dag. Na zeven keer hapert de webhook en krijgt de eigenaar een mail; na 72 uur haperen zonder één succes zetten we hem uit, en met één knop of POST /webhooks/{id}/resume staat hij weer aan. Elke levering met elke poging staat in GET /webhooks/{id}/deliveries, en een mislukte levering stuur je met één knop opnieuw. Dubbele leveringen herken je aan het id; bewaar wat je al had.

Voor je AI-assistent

Werk je met Claude Code, Codex of een andere assistent? Geef die dit adres en je sleutel, en zeg wat je wilt: de bedrijven van deze week ophalen, contacten klaarzetten, links voor je mail maken, of een webhook aanmaken. Dezelfde rechten en hetzelfde tempo als de API.

{
  "mcpServers": {
    "swungby": {
      "url": "https://swungby.com/api/mcp",
      "headers": { "Authorization": "Bearer sk_live_…" }
    }
  }
}

Bijvoorbeeld: “Haal de bedrijven op die deze week naar mijn prijzen keken en zet ze als notitie in mijn CRM.”

Versie

Dit is versie 1, in het pad als /v1. Velden komen erbij zonder dat er iets breekt; verdwijnt er ooit iets, dan komt er een /v2 naast en blijft /v1 minstens een jaar werken. Id's hebben een voorvoegsel (cmp_, vst_, key_) zodat je ze nooit door elkaar haalt.