{"openapi":"3.0.3","info":{"title":"Binding Signature API","version":"2.8.1","description":"REST API for envelopes, templates, bulk send, webhooks, PowerForms, API keys, scheduling, contacts, preview, embedded signing, and audit trails. Session routes mirror the dashboard; v2 routes use API keys."},"servers":[{"url":"https://www.bindingsignature.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key"}},"schemas":{"Envelope":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","sent","viewed","completed","declined","voided","expired"]},"scheduledSendAt":{"type":"string","format":"date-time","nullable":true},"signingOrder":{"type":"string","enum":["sequential","parallel"]}}},"BulkJob":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"recipients":{"type":"integer"},"sent":{"type":"integer"},"failed":{"type":"integer"},"scheduledSendAt":{"type":"string","format":"date-time","nullable":true},"smsNotify":{"type":"boolean"}}},"Contact":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["signer","approver","witness","viewer"]},"createdAt":{"type":"string","format":"date-time"}}},"PowerForm":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"documentTitle":{"type":"string"},"templateId":{"type":"string","nullable":true},"redirectUrl":{"type":"string","format":"uri","nullable":true},"smsNotify":{"type":"boolean"},"active":{"type":"boolean"},"url":{"type":"string","format":"uri","description":"Public signing page at /f/{slug}"}}},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":"string","format":"date-time","nullable":true}}},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"}}},"WebhookCreate":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["envelope.sent","envelope.completed","envelope.voided","envelope.declined","signer.signed","signer.viewed"]}},"active":{"type":"boolean","default":true}}}}},"paths":{"/api/v2/envelopes":{"get":{"summary":"List envelopes","parameters":[{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Envelope list"}}},"post":{"summary":"Create envelope","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","signers"],"properties":{"title":{"type":"string"},"signers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["signer","approver","witness","viewer","cc"]},"phone":{"type":"string","description":"Mobile number for SMS delivery when smsNotify is true"}}}},"signingOrder":{"type":"string","enum":["sequential","parallel"]},"smsNotify":{"type":"boolean","description":"Business+ — also SMS sign link when Twilio configured"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/api/v2/envelopes/{id}":{"get":{"summary":"Get envelope","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Envelope"}}},"patch":{"summary":"Update envelope","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"signingOrder":{"type":"string","enum":["sequential","parallel"]}}}}}},"responses":{"200":{"description":"Updated"}}},"delete":{"summary":"Void envelope","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Voided"}}}},"/api/v2/envelopes/{id}/documents":{"get":{"summary":"Download envelope PDF","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string","enum":["original","signed","certificate"]}}],"responses":{"200":{"description":"PDF binary"}}}},"/api/v2/envelopes/{id}/audit":{"get":{"summary":"Audit trail","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Audit events"}}}},"/api/v2/envelopes/{id}/preview":{"get":{"summary":"Preview envelope as signer (API key auth)","description":"Same payload as session GET /api/envelopes/{id}/preview — document, fields, signers, and branding.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"signerId","in":"query","schema":{"type":"string"},"description":"Preview as this signer (defaults to first signer)"}],"responses":{"200":{"description":"Preview payload with documentBase64, fields, signers, and branding"},"400":{"description":"No documents uploaded"},"404":{"description":"Envelope not found"}}}},"/api/v2/envelopes/{id}/schedule":{"patch":{"summary":"Reschedule envelope","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["scheduledSendAt"],"properties":{"scheduledSendAt":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Rescheduled"}}},"delete":{"summary":"Cancel scheduled send","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returned to draft"}}}},"/api/envelopes/{id}/send":{"post":{"summary":"Send or schedule envelope (session or API key)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scheduledSendAt":{"type":"string","format":"date-time"},"smsNotify":{"type":"boolean"},"signerPhones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"phone":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Sent or scheduled"}}}},"/api/envelopes/{id}/upload":{"post":{"summary":"Upload first document PDF (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"PDF file"}}}}}},"responses":{"200":{"description":"Document uploaded"}}}},"/api/envelopes/{id}/documents":{"get":{"summary":"List envelope documents (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Document list"}}},"post":{"summary":"Add additional document PDF (session auth, draft only)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"Document added"}}}},"/api/envelopes/{id}/void":{"post":{"summary":"Void envelope (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Envelope voided"}}}},"/api/envelopes/{id}/schedule":{"patch":{"summary":"Reschedule envelope (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["scheduledSendAt"],"properties":{"scheduledSendAt":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Rescheduled"}}},"delete":{"summary":"Cancel scheduled send (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returned to draft"}}}},"/api/envelopes/{id}/fields":{"get":{"summary":"List envelope fields and documents (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Fields, signers, and document list"}}},"put":{"summary":"Replace all fields on draft envelope (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fields"],"properties":{"fields":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"page":{"type":"integer"},"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"signerId":{"type":"string"},"documentId":{"type":"string"},"required":{"type":"boolean"}}}}}}}}},"responses":{"200":{"description":"Fields saved"}}},"post":{"summary":"Auto-place signature fields from signers (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"includeDates":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Fields suggested and saved"}}}},"/api/envelopes/{id}/remind":{"post":{"summary":"Send reminders to pending signers (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Reminders sent"}}}},"/api/envelopes/{id}/download":{"get":{"summary":"Download envelope PDF or ZIP (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string","enum":["document","signed","certificate"]},"description":"document=original, signed=completed PDF"},{"name":"format","in":"query","schema":{"type":"string","enum":["pdf","zip"]}},{"name":"documentId","in":"query","schema":{"type":"string"},"description":"Single document id"}],"responses":{"200":{"description":"PDF or ZIP binary"}}}},"/api/envelopes/{id}/certificate":{"get":{"summary":"Download completion certificate PDF (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Certificate PDF"}}}},"/api/envelopes/{id}/preview":{"get":{"summary":"Sender preview — document, fields, and signers (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"signerId","in":"query","schema":{"type":"string"},"description":"Preview as this signer (defaults to first signer)"}],"responses":{"200":{"description":"Preview payload with documentBase64, fields, signers, and branding"},"400":{"description":"No documents uploaded"}}}},"/api/envelopes/{id}/preview/document/{documentId}":{"get":{"summary":"Preview a single document PDF (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Document base64 payload for preview mode"}}}},"/api/envelopes/{id}/signers/{signerId}/reassign":{"post":{"summary":"Reassign a pending signer to a new name/email (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"signerId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Signer updated and invite resent if envelope is sent"}}}},"/api/contacts":{"get":{"summary":"List org address book contacts (session auth)","responses":{"200":{"description":"Contact list","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}}}}}}},"post":{"summary":"Create or update a contact (session auth)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["signer","approver","witness","viewer"],"default":"signer"}}}}}},"responses":{"200":{"description":"Contact upserted"}}}},"/api/contacts/import":{"post":{"summary":"Import contacts from CSV (session auth)","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"CSV with name, email, optional role columns"}}}},"application/json":{"schema":{"type":"object","properties":{"csv":{"type":"string","description":"CSV text with name, email, optional role columns"}}}}}},"responses":{"200":{"description":"Import summary { imported, total }"}}}},"/api/v2/templates":{"get":{"summary":"List templates","responses":{"200":{"description":"Template list"}}},"post":{"summary":"Create template","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"Created"}}}},"/api/v2/templates/global":{"get":{"summary":"Curated global template pack","description":"Browse-only global templates with categories. Auto-provisions the curated pack if empty, including sample PDFs (isSampleDocument) and default signature/date fields for demos.","responses":{"200":{"description":"Global template pack","content":{"application/json":{"schema":{"type":"object","properties":{"pack":{"type":"string","enum":["curated"]},"count":{"type":"integer"},"categories":{"type":"array","items":{"type":"string"}},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"hasDocument":{"type":"boolean"},"isSampleDocument":{"type":"boolean","description":"True when PDF is an auto-generated sample for demos"},"fieldCount":{"type":"integer"}}}}}}}}}}}},"/embed/sign/{token}":{"get":{"summary":"Embedded signing UI (iframe-friendly)","description":"Minimal-chrome signing page for iframe embeds. Same token as /sign/{token}.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"Signer signing token"}],"responses":{"200":{"description":"HTML signing page"}}}},"/api/v2/bulk-send":{"get":{"summary":"List bulk jobs","responses":{"200":{"description":"Jobs with scheduledSendAt and smsNotify"}}},"post":{"summary":"Start bulk send campaign","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","templateId"],"properties":{"name":{"type":"string"},"templateId":{"type":"string"},"envelopeTitle":{"type":"string"},"scheduledSendAt":{"type":"string","format":"date-time","description":"Schedule each envelope in the campaign"},"smsNotify":{"type":"boolean","description":"Also SMS sign links when phone columns present"},"csv":{"type":"string","description":"CSV text with name, email, optional phone/mobile columns"},"recipients":{"type":"array","items":{"type":"object"}}}}}}},"responses":{"201":{"description":"Job created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkJob"}}}}}}},"/api/v2/bulk-send/{id}":{"get":{"summary":"Get bulk job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job detail"}}}},"/api/v2/bulk-send/{id}/process":{"post":{"summary":"Process next bulk batch","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated job"}}}},"/api/v2/webhooks":{"get":{"summary":"List webhooks","responses":{"200":{"description":"Webhooks","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"post":{"summary":"Create webhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"}}}},"responses":{"201":{"description":"Created with secret"}}}},"/api/v2/webhooks/{id}":{"patch":{"summary":"Update webhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated"}}},"delete":{"summary":"Delete webhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}},"/api/v2/webhooks/{id}/test":{"post":{"summary":"Test webhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Test event sent"}}}},"/api/v2/webhooks/{id}/rotate-secret":{"post":{"summary":"Rotate webhook secret","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"New secret returned once"}}}},"/api/api-keys":{"get":{"summary":"List org API keys (session auth)","responses":{"200":{"description":"Keys list with canManage flag","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"canManage":{"type":"boolean"},"plan":{"type":"string"}}}}}}}},"post":{"summary":"Create org API key (Business+, session auth)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Key created — full key returned once in response"}}}},"/api/api-keys/{id}":{"delete":{"summary":"Revoke an API key (session auth, Business+)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}},"/api/powerforms":{"get":{"summary":"List PowerForms (session auth, Business+)","responses":{"200":{"description":"PowerForms with public url","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PowerForm"}}}}}}},"post":{"summary":"Create a PowerForm (session auth, Business+)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"slug":{"type":"string"},"documentTitle":{"type":"string"},"templateId":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"},"smsNotify":{"type":"boolean","description":"SMS sign links when Twilio is configured"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PowerForm"}}}}}},"patch":{"summary":"Update a PowerForm (session auth, Business+)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"documentTitle":{"type":"string"},"redirectUrl":{"type":"string","format":"uri","nullable":true},"active":{"type":"boolean"},"smsNotify":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated"}}}},"/api/f/{slug}":{"get":{"summary":"Public PowerForm metadata (no auth)","security":[],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Form name, branding, templateId, smsNotify flag"},"404":{"description":"Form not found or inactive"}}},"post":{"summary":"Submit a PowerForm — creates and sends an envelope (no auth)","security":[],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"Required when form has smsNotify enabled"},"merge":{"type":"object","additionalProperties":{"type":"string"},"description":"Template merge field values"}}}}}},"responses":{"200":{"description":"{ signUrl, redirectUrl, envelopeId }"},"400":{"description":"Invalid input or missing phone for SMS form"},"404":{"description":"Form not found"}}}},"/api/webhooks":{"get":{"summary":"List webhooks (session auth, Business+)","responses":{"200":{"description":"Webhook list with parsed events array"}}},"post":{"summary":"Create webhook (session auth, Business+)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Created — secret shown once in dashboard UI"}}}},"/api/webhooks/{id}":{"patch":{"summary":"Update webhook URL, events, or active state (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated"}}},"delete":{"summary":"Delete webhook (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}},"/api/webhooks/{id}/test":{"post":{"summary":"Send test event to webhook URL (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Test delivery succeeded"},"502":{"description":"Delivery failed"}}}},"/api/webhooks/{id}/rotate-secret":{"post":{"summary":"Rotate webhook signing secret (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"New secret returned once"}}}},"/api/webhooks/deliveries":{"get":{"summary":"List recent webhook deliveries (session auth, last 50)","responses":{"200":{"description":"Delivery log with status, attempts, errors"}}}},"/api/webhooks/deliveries/{id}/retry":{"post":{"summary":"Retry a failed webhook delivery (session auth)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Retry result"},"404":{"description":"Not found"}}}},"/api/openapi":{"get":{"summary":"OpenAPI specification","security":[],"responses":{"200":{"description":"This document as JSON"}}}},"/api/health":{"get":{"summary":"Health check","security":[],"responses":{"200":{"description":"OK"}}}}}}