SignSpry REST API v1

Authenticatie

Maak een sleutel aan in de ontwikkelaarsconsole en stuur die mee bij elk verzoek:

curl https://signspry.com/api/v1/account \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Een sleutel heeft alleen de scopes die bij het aanmaken zijn aangevinkt — envelopes:read (lijst, status, audittrail, verzegelde PDF), envelopes:write (aanmaken, versturen, herinneren, intrekken, ondertekenings- en insluitlinks), templates:read, account:read. Een aanroep buiten de scopes van de sleutel geeft 403 terug met de ontbrekende scope. Sleutels verlopen (na 30 dagen, 90 dagen, een jaar of nooit — je krijgt een week van tevoren een e-mail) en geven daarna 401 terug, en ze kunnen worden vastgezet op een IP-toegestaan-lijst (adressen of CIDR-bereiken), waarbij ze vanaf elk ander adres 403 teruggeven. Geef elke integratie een eigen sleutel met de beperktste scopes die nodig zijn, zodat het intrekken van de ene sleutel nooit een andere breekt.

Een envelop aanmaken & versturen

Eén aanroep uploadt documenten (base64-PDF's), voegt ontvangers en velden toe en verstuurt. Coördinaten zijn fracties van de pagina (0–1) vanaf linksboven; recipient is een index in de array met ontvangers; status: "sent" mailt de uitnodigingen meteen (laat het weg om een concept te bewaren).

curl -X POST https://signspry.com/api/v1/envelopes \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Service Agreement",
    "message": "Please sign by Friday.",
    "expires_days": 15,
    "reminder_days": 2,
    "status": "sent",
    "documents": [{"name": "agreement.pdf", "content_b64": "'"$(base64 -w0 agreement.pdf)"'"}],
    "recipients": [
      {"name": "Asha Vendor", "email": "asha@vendor.in", "routing_order": 1},
      {"name": "Manu Shekhar", "email": "manu@signspry.com", "routing_order": 2},
      {"name": "Accounts",  "email": "accounts@signspry.com", "role": "cc"}
    ],
    "fields": [
      {"recipient": 0, "type": "signature", "page": 0, "x": 0.10, "y": 0.72, "w": 0.25, "h": 0.05},
      {"recipient": 0, "type": "text", "page": 0, "x": 0.10, "y": 0.60, "w": 0.20, "h": 0.04,
       "label": "PAN", "validation": {"type": "pan"}},
      {"recipient": 1, "type": "signature", "page": 1, "x": 0.10, "y": 0.72, "w": 0.25, "h": 0.05}
    ]
  }'

Veldtypen: signature initials text date checkbox dropdown (met options) radio (met group_name) formula. Validaties: email numbers letters date phone_in pincode pan gstin {"type":"custom","regex":"…"}.

Ingebed ondertekenen

In plaats van (of naast) uitnodigingen per e-mail kun je een ondertekenings-URL ophalen en die in je eigen app openen — via een iframe of een redirect. Als de ondertekenaar klaar is, wordt die doorgestuurd naar je return_url met ?envelope=…&event=signed (of declined).

curl -X POST https://signspry.com/api/v1/envelopes/ENV_ID/recipients/RECIPIENT_ID/signing-link \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"return_url": "https://yourapp.com/signing-done"}'

#  {"url": "https://signspry.com/sign/…", "recipient": {…}}

Ontvanger-ID's komen uit de create-/detail-antwoorden. Elke aanroep maakt een nieuwe link aan en maakt oude links voor die ontvanger ongeldig. De ondertekenvolgorde blijft gelden — een ondertekenaar die nog moet wachten, ziet een pagina "wacht op anderen".

Webhooks

Voeg een endpoint toe in de console; elke overeenkomende gebeurtenis stuurt JSON via POST naar dat endpoint:

POST https://yourapp.com/webhooks/signet
X-Signet-Event: envelope.completed
X-Signet-Signature: sha256=<hex HMAC-SHA256 of raw body, keyed with your whsec_… secret>

{"id":"…","event":"envelope.completed","created_at":1787480000.1,
 "data":{"envelope":{"id":"…","title":"…","status":"completed","recipients":[…]}}}

Verifiëren (Python): hmac.new(secret, raw_body, hashlib.sha256).hexdigest() == header.split("sha256=")[1]. Mislukte leveringen worden twee keer opnieuw geprobeerd; recente leveringsresultaten zie je in de console. Events: envelope.sent recipient.viewed recipient.signed recipient.declined recipient.reassigned envelope.completed envelope.voided envelope.expired reminder.sent

Referentie