Elke organisatie werkt anders. De één stuurt een contract handmatig op ter ondertekening. De ander wil dat een ondertekenverzoek automatisch de deur uitgaat zodra er in het eigen systeem een dossier wordt afgerond. Daarvoor is de Signly API. Je koppelt Signly rechtstreeks aan je eigen software, zoals een CRM, HR-systeem, zorgdossier of maatwerkapplicatie. Ondertekenverzoeken ontstaan, versturen en ronden zichzelf volautomatisch af. Geen kopiëren en plakken en geen handmatige stappen. Jouw proces bepaalt het tempo en Signly regelt de rechtsgeldige handtekening.
Zo automatiseert een zorgorganisatie het versturen van zorgovereenkomsten direct vanuit hun eigen dossiersysteem. Bij elke nieuwe cliënt staat de overeenkomst automatisch klaar ter ondertekening.
Wat kun je met de API?
Alles wat je in de Signly-webapp doet, kan ook via de API. Zo bouw je ondertekenen in als vaste stap in je eigen workflow.
- Ondertekenverzoeken automatisch aanmaken vanuit je eigen systeem
- Documenten uploaden en ondertekenaars toevoegen
- Meerdere verificatiemethodes: e-mail, SMS, DigiD, iDIN, handtekening, paraaf
- Realtime statusupdates via webhooks
- Getekend document en rechtsgeldig audit-bewijs ophalen
Aan de slag
Je hebt nodig:
- Een access token. Vraag deze aan via info@signly.nl. Je ontvangt een sleutel plus 25 test-credits om de koppeling mee te bouwen.
- Base URL:
https://api.signly.nl - Volledige API-referentie (Swagger): https://api.signly.nl/documentation
Authenticatie. Stuur je token als Bearer-Api in de Authorization-header bij elke call:
De flow in 7 stappen
1. Afdeling ophalen → 2. Verzoek aanmaken → 3. Ondertekenaar toevoegen → 4. Document toevoegen → 5. Verzoek versturen → 6. Status volgen (webhook) → 7. Getekend document en bewijs ophalen
Stap 1: Afdelingen ophalen
Een ondertekenverzoek hoort bij een afdeling. Haal eerst de beschikbare afdelingen op en onthoud de id.
-H “Authorization: Bearer-Api $TOKEN”
-H “Accept: application/json”
Stap 2: Ondertekenverzoek aanmaken
Alleen department_id is verplicht. De rest is optioneel.
-H “Authorization: Bearer-Api $TOKEN”
-H “Accept: application/json”
-H “Content-Type: application/json”
-d ‘{“department_id”:123,”expires_at”:”2026-12-31 23:59:59″}’
Optionele velden zijn expires_at (Y-m-d H:i:s), emails (maximaal 10 kopie-ontvangers) en is_inline. Uit het antwoord haal je de id van het verzoek. Die noemen we hieronder {signRequestId}.
Stap 3: Ondertekenaar toevoegen
Voeg één of meer ondertekenaars toe. Elke ondertekenaar heeft minimaal één verificatiemethode.
-H “Authorization: Bearer-Api $TOKEN”
-H “Accept: application/json”
-H “Content-Type: application/json”
-d ‘{“firstname”:”Jan”,”lastname”:”Jansen”,”email”:”jan@voorbeeld.nl”,”verifications”:[{“type”:1,”email”:”jan@voorbeeld.nl”}]}’
De velden firstname, lastname en email zijn verplicht. Optioneel zijn reminder_after en max_reminders (1 tot 5).
| type | Methode |
|---|---|
| 1 | |
| 2 | SMS (vereist phone) |
| 3 | DigiD |
| 4 | iDIN (vereist services[]) |
| 5 | Handtekening |
| 6 | Paraaf |
Stap 4: Document toevoegen
Upload het document als multipart/form-data. Zet Content-Type niet zelf. Curl doet dat bij -F.
-H “Authorization: Bearer-Api $TOKEN”
-H “Accept: application/json”
-F “name=Overeenkomst”
-F “type=1”
-F “filename=overeenkomst.pdf”
-F “file=@/pad/naar/overeenkomst.pdf”
De velden name en type zijn verplicht (1 is bestand, 2 is tekst). Toegestaan zijn PDF, DOC en DOCX tot 15 MB. Handtekeningvelden plaats je met placeholders in de PDF, bijvoorbeeld [[signer.1.signature]] of [[signer.1.name]]. De schaal loopt van 0.5 tot 3, bijvoorbeeld [[signer.1.signature.x2]].
Stap 5: Verzoek versturen (ready)
-H “Authorization: Bearer-Api $TOKEN”
-H “Accept: application/json”
-H “Content-Type: application/json”
-d ‘{“add_inline_links”:”false”}’
De ondertekenaars ontvangen nu een uitnodiging. Let op dat je een 402 krijgt bij onvoldoende credits.
Stap 6: Status volgen
Webhooks zijn de aanbevolen manier en staan verderop beschreven. Je kunt ook pollen op de status.
-H “Authorization: Bearer-Api $TOKEN”
-H “Accept: application/json”
De status staat in het veld state_id.
| state_id | Betekenis |
|---|---|
| 1 | Aangemaakt |
| 2 | Klaar of afgerond (DONE) |
| 3 | In behandeling |
| 4 | Afgewezen |
| 5 | Goedgekeurd |
| 6 | Geen herinneringen meer |
| 7 | Verlopen |
| 8 | Geannuleerd |
| 9 | Mislukt |
| 60 | Afgehandeld door ondertekenaars |
De waarden 40, 50 en 51 zijn technische foutstatussen.
Stap 7: Getekend document en bewijs ophalen
Zodra het verzoek is afgerond, haal je het getekende document op.
-H “Authorization: Bearer-Api $TOKEN”
-o getekend-document.pdf
Daarna haal je het ondertekenbewijs op, de audit trail.
-H “Authorization: Bearer-Api $TOKEN”
-o onderteken-bewijs.pdf
Let op de AVG-bewaartermijn. Signly bewaart getekende documenten en het bewijs 28 dagen. Daarna worden ze verwijderd. Download ze dus direct naar je eigen systeem.
Verzoeken beheren
Herinnering sturen
-H “Authorization: Bearer-Api $TOKEN”
-H “Accept: application/json”
Verzoek annuleren
-H “Authorization: Bearer-Api $TOKEN”
-H “Accept: application/json”
Webhooks
Met een ingestelde webhook_url stuurt Signly automatisch een POST bij elke gebeurtenis. Signly probeert dit tot 3 keer. Dit is een voorbeeld van de payload.
“event_type”: “sign_request_state_updated”,
“company_id”: 123,
“department_id”: 456,
“data”: { “sign_request_id”: 789, “state”: 2 },
“dispatched_at”: “2026-07-16T10:00:00+00:00”
}
De belangrijkste waarden voor event_type zijn:
sign_request_state_updatedvoor een statuswijziging van het verzoek.data.stateis destate_iduit de tabel hierboven.email_verification_sentenemail_verification_verifiedsms_verification_sentensms_verification_verifiedsignature_verification_verifiedenparaph_verification_verifiedidin_verification_sent,idin_verification_failedenidin_verification_verified
Bij verificatie-events bevat data de velden verification_id, signer_id en sign_request_id.
Meer weten?
- Volledige API-referentie: https://api.signly.nl/documentation
- API-koppeling aanvragen: info@signly.nl
Ook benieuwd naar kant-en-klare koppelingen zonder zelf te bouwen? Bekijk onze integraties.
