Partner-API

Zo werkt het

De API is voor alle partners hetzelfde. In vijf stappen:

1. Wij zetten de API voor uw bedrijf aan; in uw beheeromgeving maakt u op het tabblad API een API-sleutel aan.
2. Wanneer een klant een opleiding moet volgen, roept uw systeem POST /v1/users aan met uw identificatie van de klant.
3. Wij maken een profiel aan zonder e-mail en geven een toegangslink (entryUrl) terug; die toont u de klant als knop.
4. De klant klikt erop en zit direct in de cursus.
5. De stand leest u op elk moment uit via GET /v1/users/{identifier}, of wij melden hem aan uw server via een webhook.

U bent de verwerkingsverantwoordelijke voor de identificatie, wij verwerken alleen gepseudonimiseerde gegevens. Stuur als identificatie nooit een e-mailadres of een naam - een e-mailadres weigert de API met de fout 422.

Adres en authenticatie

Elke aanroep gaat via HTTPS naar het adres hieronder en draagt uw API-sleutel in de header Authorization.

https://api.responsiblo.com
Authorization: Bearer rsb_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• rsb_live_... opent uw productieprogramma, rsb_test_... uw testprogramma (sandbox).
• De sleutel wordt maar één keer getoond, bij het aanmaken; wij bewaren alleen de vingerafdruk ervan. Bewaar hem als geheim op uw server - nooit in een browser of een app.
• De sleutel heeft rechten: read (de stand en de lijst van personen, het certificaat) en write (het doorsturen en anonimiseren van personen). Hij kan beperkt zijn tot uw IP-adressen en een geldigheid hebben.
• Vervanging: u maakt een nieuwe sleutel aan, de oude blijft nog 7 dagen geldig en verloopt dan.
• Antwoorden worden nooit in de cache opgeslagen (Cache-Control: no-store) en de API neemt geen aanroepen vanuit een browser aan (geen CORS).

POST /v1/users

Stuurt een persoon door naar het programma van de sleutel (recht write).

curl -X POST https://api.responsiblo.com/v1/users \
  -H "Authorization: Bearer $RSB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"client-48213","language":"cs","label":"campaign-2026-10"}'

201 Created voor een nieuwe persoon, 200 OK als de identificatie al bestaat - er verandert niets, de aanroep kan veilig worden herhaald. De body is de stand hieronder, inclusief entryUrl. Een uitgeputte limiet van personen of van licenties van het programma geeft 403.

GET /v1/users/{identifier}

Stand van een persoon (recht read): wat een compliancecheck nodig heeft, niets meer.

curl https://api.responsiblo.com/v1/users/client-48213 -H "Authorization: Bearer $RSB_KEY"

{
  "identifier": "client-48213",
  "program": "your-program",
  "status": "in_progress",
  "progress": 43,
  "lessonsCompleted": 3,
  "lessonsTotal": 7,
  "quizScore": null,
  "label": "campaign-2026-10",
  "createdAt": "2026-10-20T10:02:11Z",
  "startedAt": "2026-10-20T10:05:40Z",
  "completedAt": null,
  "lastActivityAt": "2026-10-20T10:31:40Z",
  "expiresAt": null,
  "certificate": null,
  "entryUrl": "https://your-company.responsiblo.com/entry/..."
}

quizScore is het resultaat van de eindquiz in %, zodra die is afgerond. Tijden zijn in UTC op hele seconden. Het veld certificate bevat het certificaat van de persoon (zie hieronder); zolang die er geen heeft, is het null.

?include=detail

Voegt de voortgang in elke cursus en het resultaat van elke quiz toe - nooit de afzonderlijke antwoorden.

"courses": [{"id": "733db340-...", "name": "Introduction", "progress": 40, "lessonsCompleted": 2, "lessonsTotal": 5, "completed": false}],
"quizzes": [{"id": "d2e72fd7-...", "name": "Quiz of the introduction", "score": 85, "completedAt": "2026-10-20T10:31:40Z"}]

GET /v1/users

Lijst van de personen die u naar het programma van de sleutel hebt doorgestuurd (recht read), per pagina: elk item heeft de vorm van de stand hierboven. Optioneel status (alleen personen in die stand), limit (1 tot 500, standaard 100) en cursor.

curl "https://api.responsiblo.com/v1/users?status=completed&limit=100" -H "Authorization: Bearer $RSB_KEY"

{
  "items": [{ "identifier": "client-48213", "status": "completed", "...": "the state of GET /v1/users/{identifier}" }],
  "nextCursor": "MjAyNi0xMC0yMFQxMDowMjoxMVp8...",
  "limit": 100
}

curl "https://api.responsiblo.com/v1/users?status=completed&limit=100&cursor=MjAyNi0xMC0yMFQxMDowMjoxMVp8..." -H "Authorization: Bearer $RSB_KEY"

• Ga verder met cursor = nextCursor zolang nextCursor niet null is; de cursor is een ondoorzichtige tekst, stel hem nooit zelf samen.
• Personen komen op volgorde van het moment van doorsturen, in een vaste volgorde (ook bij hetzelfde moment), geen enkele twee keer; geanonimiseerde personen staan niet in de lijst.
• Met het filter status bekijken we per pagina hoogstens 2000 personen, een pagina kan daarom minder items hebben dan limit, of zelfs geen - ga verder zolang er een nextCursor is.

Certificaat van de persoon

Zodra de persoon het programma afrondt, geeft de cursus een certificaat af - onder het pseudoniem van de persoon (de bijnaam van het profiel ID XXXXXX), zonder naam en zonder e-mail. Er wordt niets per e-mail verstuurd; in de stand van de persoon staat het veld certificate met het nummer, de tijden en de openbare verificatiepagina, en de pdf downloadt u via GET /v1/users/{identifier}/certificate.

"certificate": {
  "number": "RSP-7KQ2-M4XH-9TWB",
  "issuedAt": "2026-10-20T10:39:15Z",
  "expiresAt": "2028-10-20T10:39:12Z",
  "verifyUrl": "https://responsiblo.com/verify/RSP-7KQ2-M4XH-9TWB"
}

curl https://api.responsiblo.com/v1/users/client-48213/certificate -H "Authorization: Bearer $RSB_KEY" -o client-48213.pdf

• De verificatiepagina verifyUrl toont alleen het pseudoniem, het programma, de partner en de geldigheid - nooit uw identificatie.
• De pdf geeft application/pdf terug (recht read). Zonder certificaat is het antwoord 404 certificateNotFound, terwijl de pdf nog wordt gemaakt 404 certificatePdfNotReady met Retry-After.
• Een ingetrokken certificaat wordt nooit uitgegeven (het veld certificate is dan null, de pdf 404); een certificaat waarvan de geldigheid is verstreken, blijft een waarheidsgetrouw bewijs en wordt uitgegeven.
• Een webhook meldt het certificaat met de gebeurtenis certificate.issued (direct na user.completed).

DELETE /v1/users/{identifier}

Anonimiseert een persoon (recht write): uw identificatie, het label en elk webhookbericht dat haar noemt, verdwijnen uit het profiel; de toegangslinks zijn niet meer geldig. Het certificaat en het resultaat van de cursus blijven onder het nummer van het certificaat bestaan - als compliancebewijs.

curl -X DELETE https://api.responsiblo.com/v1/users/client-48213 -H "Authorization: Bearer $RSB_KEY"

HTTP/1.1 204 No Content

Antwoord 204 zonder body; elke volgende aanroep met dezelfde identificatie geeft 404 userNotFound, herhalen is dus veilig. Dezelfde identificatie kunt u daarna opnieuw doorsturen als een nieuwe persoon.

Toegangslink

Toon entryUrl aan de persoon (een knop Cursus starten in uw systeem). De link meldt de persoon aan in de cursus - zonder e-mail en zonder wachtwoord.

De link is 30 dagen geldig en kan meerdere keren worden gebruikt; elke aanroep GET /v1/users/{identifier} geeft een nieuwe. Stuur hem nooit naar iemand anders: wie de link heeft, komt binnen als die persoon.

Webhooks

Op het tabblad API van uw beheeromgeving stelt u per programma één webhook in: een openbaar HTTPS-adres van uw server en de gebeurtenissen. Daarna sturen wij u een POST met JSON - alleen identificaties en standen, nooit de toegangslink.

POST https://your-server.example/responsiblo/webhook
Content-Type: application/json
X-Responsiblo-Event: user.completed
X-Responsiblo-Delivery: 5b0c1f9e-2d1a-4a57-9a3e-0d6c9c1f2b77
X-Responsiblo-Signature: t=1792492800,v1=3f1c...e9

{
  "id": "5b0c1f9e-2d1a-4a57-9a3e-0d6c9c1f2b77",
  "type": "user.completed",
  "createdAt": "2026-10-20T10:40:00Z",
  "apiVersion": "1.3.2",
  "program": "your-program",
  "data": {
    "identifier": "client-48213",
    "status": "completed",
    "progress": 100,
    "lessonsCompleted": 7,
    "lessonsTotal": 7,
    "quizScore": 85,
    "label": "campaign-2026-10",
    "startedAt": "2026-10-20T10:05:40Z",
    "completedAt": "2026-10-20T10:39:12Z",
    "expiresAt": null
  }
}

Handtekening

Elk bericht draagt de header X-Responsiblo-Signature: t=<Unix-tijd>,v1=<HMAC-SHA256 van de tekst t.body met het geheim van de webhook, hex>. Het geheim (whsec_...) wordt één keer getoond bij het aanmaken van de webhook. Controleer de handtekening en de leeftijd van t voordat u een bericht vertrouwt; gebruik X-Responsiblo-Delivery als idempotentiesleutel.

// PHP: $secret = "whsec_...", $header = X-Responsiblo-Signature, $body = the raw body
preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m);
$valid = $m
    && abs(time() - (int) $m[1]) <= 300
    && hash_equals(hash_hmac('sha256', $m[1] . '.' . $body, $secret), $m[2]);

Aflevering en herhaling

Afgeleverd = antwoord 2xx binnen 10 seconden. Anders proberen we het opnieuw na 1 minuut, 5 minuten, 30 minuten, 2 uur en 12 uur, daarna geven we het op. Omleidingen volgen we niet.

20 niet-afgeleverde berichten op rij zetten de webhook uit tot u hem weer aanzet; de berichten uit die tijd wachten. De knop Test stuurt een ping; het afleverlogboek vindt u in uw beheeromgeving.

De gebeurtenis certificate.issued voegt u in de instellingen van een webhook toe; een webhook die vóór versie 1.2 is aangemaakt, krijgt hem niet vanzelf.

Fouten

Elke fout heeft één vorm: status, code, reason en message; een fout 422 voegt errors toe (veld - wat er mis is).

{ "status": "error", "code": 422, "reason": "invalidBody", "message": "The body is not valid.",
  "errors": { "identifier": "identifier must be a pseudonym of the partner, never an e-mail address" } }

Voor programma's en agents

• Beslis op basis van code en reason, nooit op basis van de tekst van message; errors is een object veld -> wat er mis is.
• Herhaal alleen 429, 500 en certificatePdfNotReady, en wel na Retry-After seconden (anders met een groeiende tussenpoos); herhaal andere 4xx dan 429 niet zonder de aanroep te corrigeren.
• POST /v1/users is idempotent op identifier (201 de eerste keer, daarna 200); DELETE geeft de eerste keer 204 en daarna 404 - beide kunnen veilig worden herhaald.
• Ontdubbel webhooks op X-Responsiblo-Delivery; de volgorde van de berichten is niet gegarandeerd, de stand in data is beslissend.

Leninggids

De leninggids is een korte cursus voor een aanvrager bij een kredietverstrekker: vóór de ondertekening van het contract doorloopt de aanvrager drie lessen, acht praktijksituaties en eventueel een quiz, alles met de cijfers van de eigen offerte, en bevestigt aan het einde de offerte. Op elk scherm kan de aanvrager om uitleg vragen. De offerte stuurt u via de API, u krijgt een toegangslink en een webhook meldt u het resultaat.

De leninggids activeren wij in overleg met u.

Ook hier is de aanvrager alleen uw pseudonieme profiel uit POST /v1/users. De offerte wordt bepaald door uw referenties (externalApplicationId, offerReference) en de documenten alleen door een link met een SHA-256-vingerafdruk - nooit een naam, e-mail, persoonsnummer, rekeningnummer of telefoonnummer. responsiblo keurt de lening niet goed, downloadt of bewaart de documenten niet, verifieert de identiteit niet en geeft voor de gids geen certificaat af.

1. U maakt het profiel van de aanvrager aan: POST /v1/users met uw pseudoniem.
2. U stuurt de offerte: POST /v1/users/{identifier}/loan-offers; het antwoord 201 bevat entryUrl.
3. entryUrl geeft u aan de aanvrager via uw eigen geverifieerde kanaal. De link is 30 dagen geldig en kan meerdere keren worden gebruikt; de gids toont de cijfers van de offerte van de aanvrager.
4. Het einde hoort u via een webhook (loanGuide.completed, loanGuide.assistanceRequested en andere).
5. De stand leest u via GET …/loan-offers/{offerReference}, de vastlegging voor uw dossier via GET …/evidence. Gewijzigde offerte = nieuwe offerte met supersedes, ingetrokken aanvraag = POST …/cancel.

Tot de activering antwoorden de bewerkingen van de gids met 404 notFound of 409 loanGuideNotConfigured. Het recht write verstuurt en annuleert een offerte, read leest de stand en de vastlegging.

POST /v1/users/{identifier}/loan-offers

Stuurt een offerte naar het profiel van de aanvrager (recht write). De optionele header Idempotency-Key heeft 1 tot 255 zichtbare ASCII-tekens. Voorbeeld: een lening van CZK 10.000, terug te betalen CZK 10.800 in één betaling 30 dagen na de uitbetaling, JKP (jaarlijks kostenpercentage) 155,10%.

curl -X POST https://api.responsiblo.com/v1/users/applicant-30417/loan-offers \
  -H "Authorization: Bearer $RSB_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: offer-30417-1" \
  -d '{
  "externalApplicationId": "APP-30417",
  "offerReference": "OFF-30417-1",
  "locale": "cs-CZ",
  "currency": "CZK",
  "principalMinor": 1000000,
  "disbursedAmountMinor": 1000000,
  "totalPayableMinor": 1080000,
  "aprPercent": "155.10",
  "interestRate": { "percent": "8", "period": "month" },
  "repayment": {
    "type": "singlePayment",
    "amountMinor": 1080000,
    "due": { "kind": "relative", "days": 30, "anchor": "disbursement" }
  },
  "documents": [
    { "role": "precontract_information", "reference": "DOC-PRE-30417", "title": "Předsmluvní informace",
      "url": "https://documents.lender.example/pre/30417.pdf",
      "sha256": "623f4a37e444268c076896d6c2f389b46f568d1a26539b013f2ba25d03846f72" },
    { "role": "contract_package", "reference": "DOC-CON-30417", "title": "Smlouva a podmínky",
      "url": "https://documents.lender.example/contract/30417.pdf",
      "sha256": "9c7bfe0077d1189914f0e1c483c961f4c5b36e9892385f3d2ab6168e0c088aa6" }
  ],
  "validUntil": "2026-11-15T18:00:00Z"
}'

HTTP/1.1 201 Created

{
  "offerReference": "OFF-30417-1",
  "externalApplicationId": "APP-30417",
  "offerStatus": "active",
  "guideStatus": "created",
  "validUntil": "2026-11-15T18:00:00Z",
  "snapshotSha256": "8055bfa3c5f2c163691b85785eaf61221169a123bed67aff2c1dbaf2a8e44e7e",
  "entryUrl": "https://your-company.responsiblo.com/entry/...",
  "createdAt": "2026-11-10T09:14:05Z"
}

Dezelfde body opnieuw (onder dezelfde referenties of dezelfde Idempotency-Key) geeft 200 met de bestaande offerte en een nieuwe entryUrl; een andere body daaronder geeft 409 offerConflict. Een profiel heeft één actieve offerte: een volgende zonder supersedes geeft 409 activeOfferExists, een foutieve supersedes 409 notSupersedable. De instellingen van uw gids (quiz, contact) worden op dat moment voor de offerte vergrendeld.

Stand, vastlegging en annulering

• GET /v1/users/{identifier}/loan-offers/{offerReference} - stand (recht read): offerStatus (active, expired, superseded, cancelled), guideStatus (created, in_progress, completed), afgeronde lessen, praktijk, quiz (null als die uit staat) en de momenten van het voorleggen van de offerte, de bevestiging en het verzoek om uitleg. Nooit antwoorden, waarden van de offerte of de link. De afronding blijft, ook als de offerte later verloopt.
• GET /v1/users/{identifier}/loan-offers/{offerReference}/evidence - vastlegging voor uw dossier (recht read): schemaVersion loan-guide-evidence/1, een momentopname van uw offerte met de vingerafdruk snapshotSha256, de uitgave van de cursus met vingerafdrukken van de lessen, gebeurtenissen in de volgorde sequence, elk antwoord met alle pogingen, de bevestiging en limitations - wat de vastlegging niet bewijst (voorgelegd betekent niet gelezen, de identiteit beweert u, documenten alleen via een link, geen certificaat, geen goedkeuring van de lening).
• POST /v1/users/{identifier}/loan-offers/{offerReference}/cancel - annuleert een actieve offerte (recht write), reasonCode = withdrawn_by_provider of application_closed; 200 geeft de stand terug, een offerte die niet actief is of waarvan de gids is afgerond, geeft 409 notActive.

curl https://api.responsiblo.com/v1/users/applicant-30417/loan-offers/OFF-30417-1 -H "Authorization: Bearer $RSB_KEY"

{
  "offerReference": "OFF-30417-1",
  "externalApplicationId": "APP-30417",
  "offerStatus": "active",
  "guideStatus": "completed",
  "quizEnabled": true,
  "lessonsCompleted": 3,
  "lessonsTotal": 3,
  "practiceCompleted": true,
  "quizPassed": true,
  "offerPresentedAt": "2026-11-10T18:32:47Z",
  "confirmedAt": "2026-11-10T18:34:02Z",
  "completedAt": "2026-11-10T18:34:02Z",
  "assistanceRequested": false,
  "assistanceRequestedAt": null,
  "validUntil": "2026-11-15T18:00:00Z",
  "evidenceErased": false,
  "...": "..."
}

curl -X POST https://api.responsiblo.com/v1/users/applicant-30417/loan-offers/OFF-30417-1/cancel \
  -H "Authorization: Bearer $RSB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reasonCode":"withdrawn_by_provider"}'

?externalApplicationId= is alleen nodig als één offerReference bij meerdere aanvragen van het profiel hoort (anders 409 ambiguousOfferReference).

Webhooks van de gids

De webhook van het programma (zie Webhooks) ontvangt de gebeurtenissen van de gids zonder apart abonnement. Handtekening, aflevering en herhaling zijn dezelfde als bij de andere gebeurtenissen; data bevatten identifier, offerReference, externalApplicationId, guideStatus, occurredAt en sequence (volgorde van de gebeurtenissen van één offerte) - nooit de vastlegging, waarden van de offerte of de toegangslink.

POST https://your-server.example/responsiblo/webhook
Content-Type: application/json
X-Responsiblo-Event: loanGuide.completed
X-Responsiblo-Delivery: 0f6e2a4c-91d3-4b8e-a7c5-3e2d1b9f6a08
X-Responsiblo-Signature: t=1794335647,v1=8b2d...4c

{
  "id": "0f6e2a4c-91d3-4b8e-a7c5-3e2d1b9f6a08",
  "type": "loanGuide.completed",
  "createdAt": "2026-11-10T18:34:07Z",
  "apiVersion": "1.3.2",
  "program": "your-program",
  "data": {
    "identifier": "applicant-30417",
    "offerReference": "OFF-30417-1",
    "externalApplicationId": "APP-30417",
    "guideStatus": "completed",
    "occurredAt": "2026-11-10T18:34:02Z",
    "sequence": 23
  }
}

Elke gebeurtenis komt bij één webhook hoogstens één keer aan (idempotentiesleutel = X-Responsiblo-Delivery). Een later aangemaakte webhook speelt oudere gebeurtenissen niet opnieuw af en gebeurtenissen ouder dan 28 dagen worden niet meer gemeld.

Bewaartermijn van de vastlegging

Wanneer het traject van een offerte eindigt (afgeronde, geannuleerde, verlopen of vervangen offerte), loopt de bewaartermijn uit de instellingen van uw gids (standaard 30 dagen). Daarna wordt de vastlegging verwijderd: GET …/evidence geeft 410 evidenceErased en de stand antwoordt verder met evidenceErased: true, de referenties en de momenten. Een actieve offerte wordt nooit verwijderd. De vastlegging die u moet bewaren, downloadt u direct na loanGuide.completed.

Fouten van de gids

Fouten hebben de vorm van de API hierboven. Daarnaast voor de gids:

Een fout herhaalt nooit een waarde die u hebt gestuurd. Voorbeeld: dezelfde offerte met een betaling van CZK 10.700 in plaats van CZK 10.800 en een geldigheid van 9 dagen:

"repayment": { "type": "singlePayment", "amountMinor": 1070000, "due": { "kind": "relative", "days": 30, "anchor": "disbursement" } },
"validUntil": "2026-11-19T18:00:00Z"

HTTP/1.1 422 Unprocessable Entity

{
  "status": "error",
  "code": 422,
  "reason": "invalidOffer",
  "message": "The offer contains invalid data.",
  "errors": {
    "repayment.amountMinor": "sumMismatch",
    "validUntil": "tooFar"
  }
}

Limieten

120 aanroepen per minuut per sleutel. Na 30 geweigerde sleutels vanaf één adres binnen tien minuten wacht het adres 10 minuten.

Het logboek van de aanroepen (zonder bodies, de identificatie alleen als SHA-256-vingerafdruk) bewaren we 180 dagen, afgeleverde en opgegeven webhookberichten 30 dagen.

Status en contract

• GET /v1/status - zonder sleutel, geeft {"status":"ok","version":"1.3.2"}
• GET /openapi - zonder sleutel, het OpenAPI 3-document van de partner-API

Sandbox

De testsleutel rsb_test_... opent uw testprogramma met dezelfde cursus. Personen daarin stoppen na 7 dagen; de webhook van het testprogramma staat los van die van productie.

Versiegeschiedenis

• 1.3.2 (2026-11) - Elke bewerking van het OpenAPI-document heeft een naam en een beschrijving, en de bewerkingen zijn in groepen ingedeeld. /v1/status en de webhooks melden de versie 1.3.2. De vorm van de verzoeken en antwoorden blijft ongewijzigd.
• 1.3.1 (2026-10) - Correcties zonder wijziging van de endpoints en hun antwoorden.
• 1.3.0 (2026-10) - Leninggids: POST /v1/users/{identifier}/loan-offers, stand, vastlegging en annulering van een offerte, webhooks loanGuide.*, bewaartermijn van de vastlegging. Optioneel veld returnUrl van een offerte (eigen terugkeeradres).
• 1.2.0 (2026-10) - GET /v1/users met paginering, het certificaat van de persoon (veld certificate, GET /v1/users/{identifier}/certificate, gebeurtenis certificate.issued), DELETE /v1/users/{identifier} (anonimisering), identificatie van hoogstens 64 tekens, bewaartermijn van het logboek.
• 1.1.0 (2026-10) - API-sleutels, POST /v1/users, GET /v1/users/{identifier} met ?include=detail, toegangslink, webhooks, één vorm van fouten, openbare status en OpenAPI, limieten.
• 1.0.0 (2024) - GET /v1/user/{identifier} met de JWT van de partnersleutel.

Wilt u de API voor uw bedrijf? Schrijf ons