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 a foreign API onto your stack and explain the data residency story to every enterprise customer, build PKI infrastructure yourself and burn 12–18 months on cryptography that someone else has already solved, or call a GCC-native signing API and ship the feature in an afternoon. This is the technical brief on the third option.
Standard HTTP/JSON API. Bearer token auth. No SDK lock-in — every endpoint is a curl one-liner away
SahlSign API documentation, v1
API endpoints, document storage, and webhook delivery all run from in-region infrastructure. No cross-border transfer of customer PII by default
SahlSign infrastructure, 2026
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 95% of 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
GCC-hosted, Arabic-aware, priced in regional currency, designed against PDPL frameworks.
- Document storage, audit trails, and webhook delivery all in-region; no cross-border transfer of customer PII by default
- Native Arabic field labels, RTL templates, bilingual Certificates of Completion
- Certificate cites the relevant local statute (Qatar ECTL Art. 28, KSA ETL Art. 14, UAE FDL 46 Art. 8)
- 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
- Certificate cites ESIGN / UETA / eIDAS; no native GCC statute reference
- 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.
Typical integration time from API key generation to first webhook-confirmed signed document. The signing-platform decision used to be a quarter-long project. The right API turns it into an afternoon.
SahlSign customer integration benchmarks, 2025
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 local statute references on the certificate are not marketing differentiators. They are the procurement gate.
Build on a regional API and the gate opens by default. Build on a foreign API and you spend the next two years explaining why your customer's contract data lives in Frankfurt or Virginia.
Related reading
- Why Regional Hosting Matters for Sensitive Documents — the hosting promise the API ships against, and why it survives 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.