Partner-API

Slik fungerer det

API-et er det samme for alle partnere. I fem trinn:

1. Vi slår på API-et for bedriften deres; i administrasjonen deres oppretter dere en API-nøkkel under fanen API.
2. Når en klient skal læres opp, kaller systemet deres POST /v1/users med deres identifikator for klienten.
3. Vi oppretter en profil uten e-post og returnerer en inngangslenke (entryUrl); den viser dere klienten som en knapp.
4. Klienten klikker på den og er rett inne i kurset.
5. Status leser dere når som helst via GET /v1/users/{identifier}, eller vi varsler serveren deres via en webhook.

Dere er behandlingsansvarlig for identifikatoren, vi behandler bare pseudonymiserte opplysninger. Send aldri en e-postadresse eller et navn som identifikator - en e-postadresse avviser API-et med feilen 422.

Adresse og autentisering

Hvert kall går via HTTPS til adressen nedenfor og bærer API-nøkkelen deres i headeren Authorization.

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

• rsb_live_... åpner produksjonsprogrammet deres, rsb_test_... testprogrammet deres (sandbox).
• Nøkkelen vises bare én gang, når den opprettes; vi lagrer bare fingeravtrykket av den. Oppbevar den som en hemmelighet på serveren deres - aldri i en nettleser eller en app.
• Nøkkelen har tillatelser: read (status og listen over personer, sertifikatet) og write (å sende og anonymisere personer). Den kan være begrenset til IP-adressene deres og ha en gyldighet.
• Bytte: dere oppretter en ny nøkkel, den gamle gjelder i 7 dager til og utløper deretter.
• Svar lagres aldri i hurtigbuffer (Cache-Control: no-store), og API-et tar ikke imot kall fra en nettleser (ingen CORS).

POST /v1/users

Sender en person til nøkkelens program (tillatelse 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 for en ny person, 200 OK når identifikatoren allerede finnes - ingenting endres, kallet kan trygt gjentas. Innholdet i svaret er status nedenfor, inkludert entryUrl. En oppbrukt grense for personer eller for programmets lisenser gir 403.

GET /v1/users/{identifier}

En persons status (tillatelse read): det en compliancesjekk trenger, ikke noe mer.

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 er resultatet av den avsluttende quizen i %, så snart den er fullført. Tidspunkter er i UTC på hele sekunder. Feltet certificate inneholder personens sertifikat (se nedenfor); så lenge personen ikke har et, er det null.

?include=detail

Legger til fremdriften i hvert kurs og resultatet av hver quiz - aldri de enkelte svarene.

"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

Liste over personene dere har sendt til nøkkelens program (tillatelse read), side for side: hvert element har samme form som status ovenfor. Valgfritt status (bare personer med den statusen), limit (1 til 500, standard 100) og 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"

• Fortsett med cursor = nextCursor så lenge nextCursor ikke er null; markøren er en ugjennomsiktig tekst, sett den aldri sammen selv.
• Personene kommer etter når de ble sendt, i en fast rekkefølge (også ved samme tidspunkt), ingen to ganger; anonymiserte personer er ikke på listen.
• Med filteret status går vi gjennom høyst 2000 personer per side, en side kan derfor ha færre elementer enn limit, også ingen - fortsett så lenge det finnes en nextCursor.

Personens sertifikat

Så snart personen fullfører programmet, utsteder kurset et sertifikat - under personens pseudonym (profilens kallenavn ID XXXXXX), uten navn og uten e-post. Ingenting sendes på e-post; personens status inneholder feltet certificate med nummer, tidspunkter og den offentlige verifiseringssiden, og PDF-en laster dere ned 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

• Verifiseringssiden verifyUrl viser bare pseudonymet, programmet, partneren og gyldigheten - aldri identifikatoren deres.
• PDF-en returnerer application/pdf (tillatelse read). Uten sertifikat er svaret 404 certificateNotFound, mens PDF-en fortsatt lages, 404 certificatePdfNotReady med Retry-After.
• Et tilbakekalt sertifikat utleveres aldri (feltet certificate er da null, PDF-en 404); et sertifikat med utløpt gyldighet forblir et sant bevis og utleveres.
• En webhook varsler om sertifikatet med hendelsen certificate.issued (rett etter user.completed).

DELETE /v1/users/{identifier}

Anonymiserer en person (tillatelse write): identifikatoren deres, etiketten og hver webhookmelding som nevner den, forsvinner fra profilen; inngangslenkene slutter å gjelde. Sertifikatet og resultatet av kurset blir værende under sertifikatets nummer - som compliancebevis.

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

HTTP/1.1 204 No Content

Svar 204 uten innhold; hvert senere kall med samme identifikator returnerer 404 userNotFound, så en gjentakelse er trygg. Samme identifikator kan dere deretter sende på nytt som en ny person.

Inngangslenke

Vis entryUrl til personen (en knapp Start kurset i systemet deres). Den logger personen inn i kurset - uten e-post og uten passord.

Lenken gjelder i 30 dager og kan brukes flere ganger; hvert kall GET /v1/users/{identifier} returnerer en ny. Send den aldri til noen andre: den som har lenken, kommer inn som den personen.

Webhooks

Under fanen API i administrasjonen deres setter dere opp én webhook per program: en offentlig HTTPS-adresse til serveren deres og hendelsene. Deretter sender vi dere POST med JSON - bare identifikatorer og statuser, aldri inngangslenken.

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
  }
}

Signatur

Hver melding bærer headeren X-Responsiblo-Signature: t=<Unix-tid>,v1=<HMAC-SHA256 av teksten t.innhold med webhookens hemmelighet, hex>. Hemmeligheten (whsec_...) vises én gang når webhooken opprettes. Før dere stoler på en melding, kontroller signaturen og alderen på t; bruk X-Responsiblo-Delivery som idempotensnøkkel.

// 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]);

Levering og nye forsøk

Levert = svar 2xx innen 10 sekunder. Ellers prøver vi igjen etter 1 minutt, 5 minutter, 30 minutter, 2 timer og 12 timer, deretter gir vi opp. Omdirigeringer følger vi ikke.

20 ikke-leverte meldinger på rad slår av webhooken til dere slår den på igjen; meldingene fra den perioden venter. Knappen Test sender et ping; leveringsloggen finner dere i administrasjonen deres.

Hendelsen certificate.issued legger dere til en webhook i innstillingene for den; en webhook som ble opprettet før versjon 1.2, får den ikke av seg selv.

Feil

Hver feil har én og samme form: status, code, reason og message; en feil 422 legger til errors (felt - hva som er galt).

{ "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" } }

For programmer og agenter

• Avgjør ut fra code og reason, aldri ut fra teksten i message; errors er et objekt felt -> hva som er galt.
• Gjenta bare 429, 500 og certificatePdfNotReady, og da etter Retry-After sekunder (ellers med økende intervall); gjenta ikke andre 4xx enn 429 uten å rette kallet.
• POST /v1/users er idempotent etter identifier (201 første gang, deretter 200); DELETE returnerer 204 første gang og 404 deretter - begge kan trygt gjentas.
• Dedupliser webhooks etter X-Responsiblo-Delivery; rekkefølgen på meldingene er ikke garantert, det er status i data som avgjør.

Låneveileder

Låneveilederen er et kort kurs for søkere hos en långiver: før kontrakten signeres, går søkeren gjennom tre leksjoner, åtte praktiske situasjoner og eventuelt en quiz, alt med tallene i sitt eget tilbud, og bekrefter tilbudet til slutt. På hver skjerm kan søkeren be om en forklaring. Dere sender tilbudet via API-et, får en inngangslenke, og en webhook varsler dere om resultatet.

Låneveilederen aktiverer vi etter avtale med dere.

Også her er søkeren bare deres pseudonyme profil fra POST /v1/users. Tilbudet identifiseres av referansene deres (externalApplicationId, offerReference) og dokumentene bare av en lenke med et SHA-256-fingeravtrykk - aldri navn, e-post, fødselsnummer, kontonummer eller telefonnummer. responsiblo godkjenner ikke lånet, laster ikke ned eller lagrer dokumentene, verifiserer ikke identiteten og utsteder ikke noe sertifikat for veilederen.

1. Dere oppretter søkerens profil: POST /v1/users med deres pseudonym.
2. Dere sender tilbudet: POST /v1/users/{identifier}/loan-offers; svaret 201 inneholder entryUrl.
3. entryUrl gir dere søkeren via deres egen verifiserte kanal. Lenken gjelder i 30 dager og kan brukes flere ganger; veilederen viser tallene i søkerens tilbud.
4. Når det er ferdig, får dere vite det via en webhook (loanGuide.completed, loanGuide.assistanceRequested med flere).
5. Status leser dere via GET …/loan-offers/{offerReference}, dokumentasjonen for saksmappen deres via GET …/evidence. Endret tilbud = nytt tilbud med supersedes, trukket søknad = POST …/cancel.

Fram til aktiveringen svarer veilederens operasjoner 404 notFound eller 409 loanGuideNotConfigured. Tillatelsen write sender og kansellerer et tilbud, read leser status og dokumentasjonen.

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

Sender et tilbud til søkerens profil (tillatelse write). Den valgfrie headeren Idempotency-Key har 1 til 255 synlige ASCII-tegn. Eksempel: lån på 10 000 CZK, 10 800 CZK å betale i én betaling 30 dager etter utbetalingen, effektiv rente 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"
}

Samme innhold på nytt (under de samme referansene eller samme Idempotency-Key) returnerer 200 med det eksisterende tilbudet og en ny entryUrl; annet innhold under dem returnerer 409 offerConflict. En profil har ett aktivt tilbud: et nytt uten supersedes returnerer 409 activeOfferExists, feil supersedes 409 notSupersedable. Innstillingene for veilederen deres (quiz, kontakt) låses til tilbudet i det øyeblikket.

Status, dokumentasjon og kansellering

• GET /v1/users/{identifier}/loan-offers/{offerReference} - status (tillatelse read): offerStatus (active, expired, superseded, cancelled), guideStatus (created, in_progress, completed), fullførte leksjoner, praktiske situasjoner, quiz (null når den er slått av) og tidspunktene for når tilbudet ble presentert og bekreftet og når det ble bedt om forklaring. Aldri svar, verdier i tilbudet eller lenken. Fullføringen blir stående selv om tilbudet senere utløper.
• GET /v1/users/{identifier}/loan-offers/{offerReference}/evidence - dokumentasjonen for saksmappen deres (tillatelse read): schemaVersion loan-guide-evidence/1, et øyeblikksbilde av tilbudet deres med fingeravtrykket snapshotSha256, kursutgaven med fingeravtrykk av leksjonene, hendelsene i rekkefølgen sequence, hvert svar med alle forsøk, bekreftelsen og limitations - hva dokumentasjonen ikke beviser (presentert betyr ikke lest, identiteten er oppgitt av dere, dokumentene bare som referanse, ikke noe sertifikat, ingen godkjenning av lånet).
• POST /v1/users/{identifier}/loan-offers/{offerReference}/cancel - kansellerer et aktivt tilbud (tillatelse write), reasonCode = withdrawn_by_provider eller application_closed; 200 returnerer status, et tilbud som ikke er aktivt eller har fullført veileder, returnerer 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= trengs bare når én offerReference hører til flere søknader på profilen (ellers 409 ambiguousOfferReference).

Veilederens webhooks

Programmets webhook (se Webhooks) mottar veilederens hendelser uten eget abonnement. Signatur, levering og nye forsøk er de samme som for andre hendelser; data inneholder identifier, offerReference, externalApplicationId, guideStatus, occurredAt og sequence (rekkefølgen på hendelsene for ett tilbud) - aldri dokumentasjonen, verdier i tilbudet eller inngangslenken.

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
  }
}

Hver hendelse når én webhook høyst én gang (idempotensnøkkel = X-Responsiblo-Delivery). En webhook som opprettes senere, spiller ikke av eldre hendelser, og hendelser eldre enn 28 dager varsles ikke lenger.

Lagringstid for dokumentasjonen

Når tilbudets forløp avsluttes (fullført, kansellert, utløpt eller erstattet tilbud), løper lagringstiden fra innstillingene for veilederen deres (som standard 30 dager). Deretter slettes dokumentasjonen: GET …/evidence returnerer 410 evidenceErased, og status svarer fortsatt med evidenceErased: true, referansene og tidspunktene. Et aktivt tilbud slettes aldri. Last ned dokumentasjonen dere må oppbevare, rett etter loanGuide.completed.

Feil i veilederen

Feilene har API-ets form ovenfor. I tillegg for veilederen:

En feil gjentar aldri en verdi dere har sendt. Eksempel: samme tilbud med en betaling på 10 700 CZK i stedet for 10 800 CZK og en gyldighet på 9 dager:

"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"
  }
}

Grenser

120 kall i minuttet per nøkkel. Etter 30 avviste nøkler fra én adresse innen ti minutter må adressen vente 10 minutter.

Loggen over kall (uten innhold, identifikatoren bare som SHA-256-fingeravtrykk) lagrer vi i 180 dager, leverte og oppgitte webhookmeldinger i 30 dager.

Status og kontrakt

• GET /v1/status - uten nøkkel, returnerer {"status":"ok","version":"1.3.2"}
• GET /openapi - uten nøkkel, OpenAPI 3-dokumentet for partner-API-et

Sandbox

Testnøkkelen rsb_test_... åpner testprogrammet deres med det samme kurset. Personer der avsluttes etter 7 dager; webhooken til testprogrammet er atskilt fra produksjonens.

Versjonshistorikk

• 1.3.2 (2026-11) - Hver operasjon i OpenAPI-dokumentet har et navn og en beskrivelse, og operasjonene er delt inn i grupper. /v1/status og webhooks oppgir versjonen 1.3.2. Formen på forespørsler og svar er uendret.
• 1.3.1 (2026-10) - Rettelser uten endring av endepunktene og svarene deres.
• 1.3.0 (2026-10) - Låneveileder: POST /v1/users/{identifier}/loan-offers, status, dokumentasjon og kansellering av et tilbud, webhooks loanGuide.*, lagringstid for dokumentasjonen. Valgfritt felt returnUrl på et tilbud (egen returadresse).
• 1.2.0 (2026-10) - GET /v1/users med sideinndeling, personens sertifikat (feltet certificate, GET /v1/users/{identifier}/certificate, hendelsen certificate.issued), DELETE /v1/users/{identifier} (anonymisering), identifikator på høyst 64 tegn, lagring av loggen.
• 1.1.0 (2026-10) - API-nøkler, POST /v1/users, GET /v1/users/{identifier} med ?include=detail, inngangslenke, webhooks, én form for feil, offentlig status og OpenAPI, grenser.
• 1.0.0 (2024) - GET /v1/user/{identifier} med JWT for partnernøkkelen.

Vil dere ha API-et for bedriften deres? Skriv til oss