If you're building a SaaS, fintech, HR-tech, or legal-tech product for GCC customers, your users will eventually need to sign documents. You have three options: glue an English-first API onto your stack and retrofit Arabic, RTL and local legal references yourself, build PKI infrastructure yourself and burn 12–18 months on cryptography that someone else has already solved, or call a signing API built for the region. This is the technical brief on the third option.
Status, October 2026: early access. The public REST API described below is not generally available yet — endpoints, names and pricing may change before launch. What is live today: webhooks for signing and contract events (owners and admins set them up in Settings → Webhooks; the live event names are
envelope.*,contract.*andobligation.*, not thedocument.*names sketched below). To join API early access, email sales@sahlsign.com.
Standard HTTP/JSON API. Bearer token auth. No SDK lock-in — every endpoint is a curl one-liner away
Planned API design (early access)
Where your customers' documents are stored is confirmed in writing per customer. If a residency requirement applies, tell SahlSign before you subscribe and we confirm whether it can be met
SahlSign privacy policy
Webhook signing scheme with timestamp + nonce. Replay attacks rejected by the verifier; standard pattern
Webhook security model
The signing lifecycle, mapped to endpoints
Every signing transaction follows the same shape: create the document, configure the signers, send for signing, get webhook updates, fetch the sealed result. The API exposes a clean primitive for each step.
POST /v1/documents
Upload the source PDF (multipart or base64), get back a document ID. Optionally attach metadata for your own correlation.
POST /v1/documents/:id/signers
Add signers with name, email, role, and signing order. Sequential or parallel routing configured here.
POST /v1/documents/:id/send
Trigger the signing flow. Signers receive branded email with unique URL; OTP verification gates the signing event itself.
Webhook fires + GET /v1/documents/:id
Subscribe to document.completed; pull the final sealed PDF + Certificate of Completion via the get-document endpoint.
The endpoint surface
The full v1 API is small by design — eight endpoints cover the common integration needs. Templates and webhooks layer on top for higher-throughput patterns.
Core REST endpoints
- POST /v1/documents — upload and create
Source PDF in, document ID out. Accepts multipart upload up to 25MB or base64 in the JSON body for smaller files. Returns the document with status = draft.
- GET /v1/documents — paginated list
List your documents with cursor-based pagination. Filter by status, signer email, date range, or metadata tag.
- GET /v1/documents/:id — fetch details
Returns the document with current signing status, the audit trail, signer list, and (when completed) the sealed-PDF download URL.
- DELETE /v1/documents/:id — void or cancel
Voids an in-progress document, notifying all signers. Idempotent — repeat calls return the same final state.
- POST /v1/documents/:id/send — trigger signing
Begins the signing flow. Returns 202 Accepted with the signer URLs. Idempotency-Key header supported to prevent double-sends.
- POST /v1/templates/:id/send — template-based one-shot
Create a document from a pre-configured template and send for signing in a single call. Best for repeatable flows (onboarding, recurring contracts).
- POST /v1/webhooks — register callback URL
Subscribe to document events. HMAC-SHA256-signed payloads, sent with retries on backoff (2s, 10s, 30s, 2m, 10m).
- GET /v1/verify/:id — public verification
Open the verification page for a completed document. Anyone can hit this; no auth required. Powers the verify URL on the Certificate of Completion.
Webhook events
Webhooks are the right pattern for production integrations — polling the document status endpoint wastes API quota and lags real-time. SahlSign emits six events covering the signing lifecycle.
Webhook event surface. All events arrive as HMAC-SHA256-signed POST requests to your registered endpoint. Verify the signature against the SAHLSIGN_WEBHOOK_SECRET in your dashboard.
| Jurisdiction | Law | Cross-border transfer rule | Intensity |
|---|---|---|---|
| document.sent | Signing flow started | Fired immediately after POST /send completes. Payload includes signer URLs (don't expose these client-side). | Moderate |
| document.viewed | A signer opened the link | Fired the first time each signer follows their signing URL. Useful for reminder logic. | Moderate |
| document.signed | A single signer completed | One fire per signer in a multi-party doc. Includes signer email, IP, user-agent, and signing timestamp. | Restricted |
| document.completed | All signers done; PDF sealed | The 'integration complete' event. Sealed PDF + Certificate of Completion download URLs included. | Strict |
| document.declined | A signer refused | Fired when any signer hits decline. Document moves to voided state; integration should react accordingly. | Restricted |
| document.expired | Signing window elapsed | Documents have a configurable expiry (default 30 days). Cleanup hook for your backend. | Moderate |
A production signing integration with SahlSign is typically three things on your side: a "send for signing" call from your app's contract-creation flow, a webhook handler for document.completed, and a stored reference linking the SahlSign document ID to your domain object. That's the whole footprint.
— The integration shape worth copying
Why GCC-native API matters for your customers
Most SaaS teams treat data residency as a procurement checkbox. For GCC enterprise customers it's a compliance hard requirement — and the answer affects whether you close the deal.
SahlSign API
Arabic-aware, priced in regional currency, designed against PDPL frameworks.
- Data location confirmed in writing per customer — tell us any residency requirement before you subscribe and we confirm whether it can be met
- Native Arabic field labels, RTL templates, bilingual Certificates of Completion
- Every Certificate of Completion lists the signers, audit timeline and document hashes, with a QR code to verify it online
- Pricing in QAR / SAR / AED; per-document model with no envelope counting
- Support and incident response from GCC-domiciled engineers in your timezone
- Data-processing addenda available that map to PDPPL, KSA PDPL, UAE PDPL — not just GDPR
Foreign signing API
Mature SDKs, global brand, but the deployment story is harder for GCC enterprise.
- Document storage in US or EU regions; cross-border transfer triggers DPA paperwork under every GCC PDPL
- Arabic as a translation overlay; RTL not first-class in the API responses or templates
- USD pricing on envelope-volume model; FX exposure on every invoice
- Support in US/EU business hours; integration tickets often span a sleep cycle
- DPA written against GDPR; mapping to PDPL is the customer's problem
Auth, rate limits, and operational ergonomics
Boring infrastructure questions tend to surface late and cause integration grief if they weren't designed for. Here's what you get on day one.
Operational specs
- Auth: Bearer tokens, per-tenant + per-environment
Generate API keys from the dashboard; one set per environment (staging / production). Keys can be scoped to specific endpoints if your integration only needs a subset.
- Rate limits: 300 req/min Professional, 1,000 req/min Enterprise
Burst-friendly; soft throttle returns 429 with Retry-After. Webhook delivery has its own quota separate from API ingress.
- Idempotency-Key support on all mutating endpoints
Retry network failures safely without creating duplicate documents. Standard pattern: generate a UUID per logical operation, include as header.
- Webhook retry with exponential backoff
Failed deliveries retry at 2s, 10s, 30s, 2m, 10m, then give up and surface the failure in the dashboard. Verify HMAC signature before processing.
- Sandbox environment with test signer flows
Separate API host for staging; no envelope cost, sealed PDFs marked TEST. Run your full integration test suite without billable usage.
- Stable v1 contract
API versioned in the URL path. Breaking changes get a new major version with deprecation notice. v1 endpoints will be supported for 24+ months past any v2 release.
The pricing math for a 500-document/month workload
Engineering teams underweight cost on signing infrastructure because it doesn't bite until the customer base grows. For a mid-scale integration (~500 docs/month), the gap between regional and foreign API pricing is meaningful.
Per-document API cost at 500 docs/month volume
Indicative pricing for the volume bracket where most growing GCC SaaS integrations sit. Foreign-API pricing converted to USD-equivalent per-envelope rates.
Public pricing tiers, SahlSign and major foreign e-signature APIs, 2026. Exact rates depend on contract terms and volume commits.
At 500 documents/month, the difference between $1/doc and $5/doc is $24,000/year. At 2,000 documents/month, it's $96,000/year. At enterprise volumes, the gap pays for an engineer.
Build-versus-buy, decisively settled
The "build it ourselves" option is the longest path. PAdES-B-T sealing, RFC 3161 timestamping, certificate management, OTP infrastructure, audit-chain integrity — every one of those is a small engineering challenge that adds up. Twelve months in, you have a worse version of what SahlSign already ships, plus an ongoing security and compliance burden.
The takeaway
For a GCC product team, the API choice is not which signing platform has the most features — it's which one your enterprise customer's procurement team can sign off on without a 90-day DPA negotiation. GCC data residency, PDPL-mapped DPAs, Arabic-native templates, and bilingual certificates of completion are not marketing differentiators. They are the procurement gate.
Whichever API you build on, get its data location confirmed in writing before you commit — it is the first question your customer's procurement team will ask.
Related reading
- Why Regional Hosting Matters for Sensitive Documents — the data-residency questions your enterprise customers will ask, and why they matter in procurement.
- How to Verify a Signed PDF — what your API consumers — and their counterparties — will run on the PDFs your integration produces.
- The Future of Identity and Signing in the Middle East — where the API roadmap is heading as Nafath, UAE Pass, and QDI become first-class signing identities.