Document signing
e-Sign PDFs by URL with full request and response examples, review flows, and verification.
Electronic signatures with pasby are verifiable at in.pasby.africa. Example checker URL: https://in.pasby.africa/document-checker/1a2b2a10-d9f7-11ee-9111-89bbff3a3763.
Document endpoints sign PDFs hosted at a direct, publicly reachable URL. Scope: document:sign. A webhook is always required.
Sandbox base URL: https://s.pasby.africa
SDK: pasby.docs.docSign, docReview, docSignatureRefresh — TypeScript SDK.
e-Doc model
idstringUnique document flow id (often
doc_…).tostring[]Recipient NINs.
iatnumberCreated-at unix timestamp.
expnumberExpiration unix timestamp.
destinationstringpasby device destination (e.g.
mobile).handledbooleanWhether the request has been handled.
fileobjectsource(URL) andname(title) of the PDF.hookobjectWebhook
hostandreference.requestobjectClient, app, and IP metadata.
useragentstringUser-agent of the originating client.
Signing
POST /api/v2/document/signing
Request payload
| Field | Type | Description |
|---|---|---|
to | string[] | One or more recipient NINs |
file.url | string | Direct URL to the PDF |
file.title | string | Display name for the document |
webhook.host | string | HTTPS callback URL |
webhook.reference | string | Your correlation id |
Headers (v2): x-api-key, x-access-secret
Headers (v1): x-api-key, x-access-token
curl -sS -X POST "https://s.pasby.africa/api/v2/document/signing" \
-H "x-api-key: bk-test_YOUR_KEY" \
-H "x-access-secret: YOUR_APP_SECRET" \
-H "Content-Type: application/json" \
-d '{
"to": ["12345678901", "77772477777", "22200044534"],
"file": {
"url": "https://file.example.com/bucket/service-agreement.pdf",
"title": "Service Agreement"
},
"webhook": {
"host": "https://your-app.com/pasby/events",
"reference": "doc-contract-001"
}
}'{
"status": "successful",
"reason": "Signature request propagated",
"data": {
"request": {
"id": "doc_1707025000-AaBb",
"to": ["12345678901", "77772477777", "22200044534"],
"destination": "mobile",
"handled": false,
"file": {
"source": "https://file.example.com/bucket/service-agreement.pdf",
"name": "Service Agreement"
},
"hook": {
"host": "https://your-app.com/pasby/events",
"reference": "doc-contract-001"
},
"request": {
"client": "bcn_•••••••",
"app": "app_•••••••",
"ip": "::1"
},
"iat": 1707025000,
"exp": 1707025360
}
}
}| Response field | Description |
|---|---|
request | e-Doc model |
Track completion via webhooks and flow ping.
Review with signees
POST /api/v2/document/review — structured multi-signee workflow with metadata per signer.
| Field | Required | Constraints |
|---|---|---|
name | Yes | Signee display name |
email | Yes | Valid email |
nin | Yes | Signee NIN |
type | Yes | business or person |
representing | Yes | Entity represented |
title | No | Role or title |
Include file, webhook, and signee[] in the body. Monitor with ping/SSE and webhooks per signee.
curl -sS -X POST "https://s.pasby.africa/api/v2/document/review" \
-H "x-api-key: bk-test_YOUR_KEY" \
-H "x-access-secret: YOUR_APP_SECRET" \
-H "Content-Type: application/json" \
-d '{
"file": {
"url": "https://your-cdn.com/documents/agreement.pdf",
"title": "Partnership Agreement"
},
"webhook": {
"host": "https://your-app.com/pasby/events",
"reference": "review-001"
},
"signee": [
{
"name": "Jane Doe",
"email": "jane@example.com",
"nin": "12345678901",
"type": "person",
"representing": "Jane Doe",
"title": "Director"
},
{
"name": "John Smith",
"email": "john@example.com",
"nin": "98765432109",
"type": "business",
"representing": "Acme Ltd",
"title": "Signatory"
}
]
}'{
"status": "successful",
"reason": "Document signing flow created",
"data": {
"link": "https://sign.with.pasby.africa/contract/doc_1707025100-BbCc",
"request": {
"id": "doc_1707025100-BbCc",
"mode": "interface",
"handled": false,
"signee": [
{
"name": "Jane Doe",
"email": "jane@example.com",
"nin": "12345678901",
"type": "person",
"representing": "Jane Doe",
"title": "Director"
}
]
}
}
}| Response field | Description |
|---|---|
data.link | Hosted signing UI — share with signers who need the browser review experience |
data.request | e-Doc model including signee and statusLog |
Open data.link for signers. Track each signee with flow ping and webhooks.
Refresh stalled flow
POST /api/v2/document/refresh — fetch the latest document state when a flow stalls or you need to reconcile after webhooks. Returns file.stamped, signatures, and per-signee statusLog when signing is complete.
Pass the document id from signing/review create (doc_…, at least 40 characters).
Use after webhooks miss a delivery or when statusLog shows signers still pending. Pair with flow ping while the flow is in progress.
curl -sS -X POST "https://s.pasby.africa/api/v2/document/refresh" \
-H "x-api-key: bk-test_YOUR_KEY" \
-H "x-access-secret: YOUR_APP_SECRET" \
-H "Content-Type: application/json" \
-d '{ "flow": "doc_1707025200-CcDd0123456789012345678901234567890" }'{
"status": "successful",
"reason": "Esignature refreshed successfully",
"data": {
"doc": {
"id": "doc_1707025200-CcDd0123456789012345678901234567890",
"handled": true,
"file": {
"name": "Service Agreement",
"stamped": "https://cdn.pasby.africa/edoc/doc_1707025200-CcDd-stamped.pdf"
},
"signee": [
{
"name": "Jane Doe",
"nin": "12345678901",
"signedAt": 1707025300
}
],
"signatures": [
{
"nin": "12345678901",
"name": "Jane Doe",
"signature": "<base64-encoded-signature>"
}
]
}
}
}| Response field | Description |
|---|---|
data.doc | Full e-Doc model with stamped file URL and signature payloads |
data.doc.file.stamped | Signed PDF URL when available |
data.doc.signatures | Cryptographic signature data per signer |
Verify completed documents at in.pasby.africa using the stamped file URL.