اینڈ پوائنٹس
تمام آپریشنز، اسی OpenAPI دستاویز سے تیار شدہ جس سے انٹرایکٹو حوالہ بنتا ہے (ہر پاتھ
اس سے لنک ہے)۔ بیس URL: https://api.bonafidesign.com۔ کلائنٹ تیار کرنے یا اسے Postman یا Insomnia میں امپورٹ کرنے کے لیے دستاویز کو JSON یا
YAML کے طور پر ڈاؤن لوڈ کریں۔
Auth وہ ہے جو آپریشن قبول کرتا ہے: ایک API کلید (Authorization: Bearer bf_… یا
x-api-key)، ڈیش بورڈ سیشن (ڈیش بورڈ کی اپنی کالز)، دستخط کنندہ کا ٹوکن (/v1/signing/*)، ناظر کا ٹوکن (/v1/viewer/*، ناظر کی ای میل کے لنک سے)، یا کچھ بھی نہیں۔
Templates
| Endpoint | What it does | Auth |
|---|---|---|
POST /v1/templates | Create a template | API key or dashboard |
GET /v1/templates | List templates | API key or dashboard |
GET /v1/templates/{id} | Get a template | API key or dashboard |
DELETE /v1/templates/{id} | Delete a template that was never used by an envelope or signing link | API key or dashboard |
POST /v1/templates/{id}/files | Upload the source PDF (or a .docx, converted to PDF to keep the exact Word layout) | API key or dashboard |
POST /v1/templates/{id}/import | Convert a Word document (.docx) into an editable Document-mode draft body (nothing is stored) | API key or dashboard |
PUT /v1/templates/{id}/draft | Create or replace the draft version | API key or dashboard |
POST /v1/templates/{id}/publish | Publish the draft as a new immutable version | API key or dashboard |
GET /v1/templates/{id}/versions | List versions (newest first) | API key or dashboard |
GET /v1/templates/{id}/versions/{version} | Get a version (number, "latest" or "draft") | API key or dashboard |
GET /v1/templates/{id}/versions/{version}/document | The base PDF of a version (number, "latest" or "draft"); drafts give the uploaded original unless ?edited=true | API key or dashboard |
POST /v1/templates/{id}/versions/{version}/render | Render a watermarked PREVIEW PDF with variables | API key or dashboard |
Envelopes
| Endpoint | What it does | Auth |
|---|---|---|
POST /v1/envelopes | Create and send an envelope from a template, with optional send-time routing, CC, viewers and reminders (dry_run=true validates and renders only) | API key or dashboard |
GET /v1/envelopes | List envelopes | API key or dashboard |
GET /v1/envelopes/{id} | Get an envelope | API key or dashboard |
GET /v1/envelopes/{id}/document | Download the rendered original, the sealed PDF or the standalone certificate of completion | API key or dashboard |
POST /v1/envelopes/{id}/void | Void an envelope in progress | API key or dashboard |
POST /v1/envelopes/{id}/viewers | Add viewers to an envelope in progress (read-only status page, emailed right away; limited per envelope by plan) | API key or dashboard |
DELETE /v1/envelopes/{id}/viewers/{viewer} | Revoke a viewer: every status link they were sent stops working | API key or dashboard |
POST /v1/envelopes/{id}/recipients/{recipient}/resend | Email the recipient a fresh signing link (their turn only; at most once a minute) | API key or dashboard |
GET /v1/envelopes/{id}/events | The envelope audit trail with hash-chain verification | API key or dashboard |
GET /v1/envelopes/{id}/events/stream | Server-sent events for one envelope (Last-Event-ID = seq resumes) | API key or dashboard |
Signing
| Endpoint | What it does | Auth |
|---|---|---|
POST /v1/envelopes/{id}/sessions | Mint a short-lived, single-use signing session for a recipient (embedded or hosted) | API key or dashboard |
POST /v1/signing/exchange | Exchange a session token (email link / embed) for a short-lived access token | Public |
GET /v1/signing/session | Load the signer view | Signer token |
GET /v1/signing/document | The PDF to display to the signer | Signer token |
POST /v1/signing/otp | Send a one-time code (email; SMS if enabled for the org) | Signer token |
POST /v1/signing/otp/verify | Verify the one-time code | Signer token |
POST /v1/signing/attachments | Upload a file for an attachment field (multipart: field, file) | Signer token |
POST /v1/signing/submit | Submit field values, signature and consent | Signer token |
POST /v1/signing/decline | Decline to sign (ends the envelope) | Signer token |
Signing links
| Endpoint | What it does | Auth |
|---|---|---|
GET /v1/links/{id} | Public description of an always-on link | Public |
POST /v1/links/{id}/start | Visitor details → email OTP (rate limited) | Public |
POST /v1/links/{id}/verify | Verify the OTP; creates the envelope and a signing session | Public |
POST /v1/signing-links | Create an always-on signing link | API key or dashboard |
GET /v1/signing-links | List signing links | API key or dashboard |
PATCH /v1/signing-links/{id} | Change, pause or resume a link | API key or dashboard |
DELETE /v1/signing-links/{id} | Delete a link (envelopes it created stay) | API key or dashboard |
Viewers
| Endpoint | What it does | Auth |
|---|---|---|
POST /v1/viewer/exchange | Exchange a viewer link token (from the viewer email) for a short-lived access token | Public |
GET /v1/viewer/envelope | Read-only envelope status for a viewer (the first open is recorded in the audit trail) | Viewer token |
GET /v1/viewer/document | The document, when the sender let viewers see it (the sealed PDF once sealed) | Viewer token |
GET /v1/viewer/stream | Server-sent `update` pings when the envelope changes (refetch the status); access token in the query | Viewer token |
Webhooks
| Endpoint | What it does | Auth |
|---|---|---|
POST /v1/webhook-endpoints | Register a webhook endpoint (Standard Webhooks; the secret is returned once) | API key or dashboard |
GET /v1/webhook-endpoints | List webhook endpoints with delivery health | API key or dashboard |
GET /v1/webhook-endpoints/{id} | Get a webhook endpoint | API key or dashboard |
PATCH /v1/webhook-endpoints/{id} | Change URL, events, description or pause | API key or dashboard |
DELETE /v1/webhook-endpoints/{id} | Delete a webhook endpoint | API key or dashboard |
POST /v1/webhook-endpoints/{id}/secret | Reveal the signing secret | Dashboard only |
POST /v1/webhook-endpoints/{id}/secret/rotate | Rotate the signing secret (the old one also signs for 24 h) | API key or dashboard |
GET /v1/webhook-endpoints/{id}/deliveries | Recent delivery attempts | API key or dashboard |
POST /v1/webhook-endpoints/{id}/test | Send a `webhook.test` ping | API key or dashboard |
POST /v1/events/{id}/redeliver | Deliver an envelope event to an endpoint again | API key or dashboard |
API keys
| Endpoint | What it does | Auth |
|---|---|---|
POST /v1/api-keys | Create an org API key (bf_live_/bf_test_); shown once | Dashboard only |
GET /v1/api-keys | List org API keys | Dashboard only |
DELETE /v1/api-keys/{id} | Revoke an API key | Dashboard only |
Directory
| Endpoint | What it does | Auth |
|---|---|---|
GET /v1/scim | SCIM endpoint, token state and provisioned users | Dashboard only |
POST /v1/scim/token | Create (or replace) the SCIM bearer token; shown once | Dashboard only |
DELETE /v1/scim/token | Revoke the SCIM token (provisioning stops) | Dashboard only |
Account
| Endpoint | What it does | Auth |
|---|---|---|
GET /v1/me/preferences | Your settings across organizations (the organization each sign-in starts in) | Dashboard only |
PUT /v1/me/preferences | Choose the organization each sign-in starts in (one of yours), or null for the first | Dashboard only |
Organization
| Endpoint | What it does | Auth |
|---|---|---|
GET /v1/organization/settings | Feature flags (e.g. SMS add-on) | API key or dashboard |
GET /v1/organization/email-branding | Email branding settings and what the plan allows | API key or dashboard |
PUT /v1/organization/email-branding | Change email branding (display name, custom message; footer and Powered-by removal by plan) | API key or dashboard |
POST /v1/organization/email-branding/preview | Render a sample email for the organization (optionally with unsaved branding); the plan's limits apply | API key or dashboard |
POST /v1/organization/logo | Upload a logo (multipart `file`, PNG/JPEG/SVG/WebP ≤ 512 KB) → public URL to store via Better Auth organization.update | Dashboard only |
GET /v1/public/logos/{org}/{file} | A public organization logo | Public |
GET /v1/usage | Metered usage for a billing period (YYYY-MM) | API key or dashboard |
SSO
| Endpoint | What it does | Auth |
|---|---|---|
GET /v1/sso/discover | Does this email sign in with company SSO? (public, rate limited) | Public |
GET /v1/sso/connections | Settings and health of the org's SSO connections | Dashboard only |
GET /v1/sso/connections/{providerId} | Settings and health of one connection | Dashboard only |
PUT /v1/sso/connections/{providerId}/settings | Enforcement, default role and JIT provisioning | Dashboard only |
POST /v1/sso/connections/{providerId}/tests | Start a test login; open `url` in a popup and poll the test | Dashboard only |
GET /v1/sso/connections/{providerId}/tests/{testId}/start | Redirect to the IdP for a test login (popup) | Dashboard only |
GET /v1/sso/connections/{providerId}/tests/{testId} | Outcome of a test login | Dashboard only |
POST /v1/sso/saml-metadata | Fetch an IdP metadata URL server-side | Dashboard only |
GET /v1/sso/audit | SSO and SCIM administration audit trail (newest first) | Dashboard only |
Billing
| Endpoint | What it does | Auth |
|---|---|---|
GET /v1/billing | Plan, usage this period, upcoming invoice and entitlements | API key or dashboard |
GET /v1/billing/subscription | Plan and usage (subset of GET /v1/billing) | API key or dashboard |
POST /v1/billing/checkout | Start a subscription (Stripe Checkout URL) or switch an existing one in place | Dashboard only |
POST /v1/billing/portal | Stripe Customer Portal URL (cards, invoices, tax IDs, cancel) | Dashboard only |
POST /v1/billing/webhooks/stripe | Stripe webhook receiver (Stripe-Signature verified) | Public |
Verification
| Endpoint | What it does | Auth |
|---|---|---|
GET /.well-known/bona-fide/keys.json | Ed25519 public keys that sign evidence anchors, with validity periods (public) | Public |
GET /v1/public/anchors | Signed evidence anchors, newest first (public) | Public |
GET /v1/public/anchors/latest | The latest signed evidence anchor (public) | Public |
GET /v1/public/anchors/{sequence} | A signed evidence anchor by sequence number (public) | Public |
POST /v1/public/verify | Look up a document by SHA-256: envelope summary, Merkle leaf, inclusion proof and signed anchor (public; hash the file locally) | Public |
GET /v1/public/documents/{token} | Download a sealed PDF with the link from a completion email (public; the link expires after 30 days) | Public |