Stampa

Stampa Public API Integrations

This guide describes the Stampa public API integration contract for systems that create signing requests, track status, receive webhooks, and download completed artifacts.

Current URLs:

  • Swagger UI: https://admin.stamping.co.il/swagger
  • OpenAPI JSON: https://admin.stamping.co.il/api/openapi/v1/openapi.json
  • API base: https://admin.stamping.co.il/api/v1
  • OAuth token endpoint: https://admin.stamping.co.il/oauth/token

When docs.stamping.co.il is available, publish this guide, the OpenAPI document, SDK links, and Postman collection there.

Provisioning

API access is enabled per organization by plan eligibility and the organization API integrations flag. Stampa Support or a platform administrator enables access; the customer then creates OAuth clients in Integrations.

Secrets must not be sent by email. Provision credentials in Stampa or another agreed secure channel.

Sandbox requests use production OAuth clients with X-Stampa-Sandbox: true. The backend must also have Integrations:Sandbox:Enabled=true; otherwise sandbox requests fail with 403.

Authentication

Stampa public API access uses OAuth2 client credentials.

curl -X POST https://admin.stamping.co.il/oauth/token \
  -u "$STAMPA_CLIENT_ID:$STAMPA_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Request-Id: crm-token-001" \
  -d "grant_type=client_credentials&scope=organization.read usage.read templates.read envelopes.write envelopes.read webhooks.manage"

The token endpoint also accepts client_id and client_secret as form fields. HTTP Basic authentication is preferred.

Successful response:

{
  "access_token": "stampa_access_example",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "organization.read usage.read templates.read envelopes.write envelopes.read",
  "expires_at": "2026-09-11T11:00:00Z"
}

Access tokens are opaque bearer tokens stored only as hashes. Default lifetime is 1 hour. Client secrets are shown once, expire after 365 days, and may be rotated with up to two active expiring secrets per client.

Scopes

  • organization.read: organization profile and plan context.
  • usage.read: usage, diagnostics, and rate-limit visibility.
  • templates.read: template list and template detail.
  • files.write: upload source files.
  • envelopes.read: envelope detail, recipients, document download, final PDF, and audit trail.
  • envelopes.write: create, send, cancel, remind, extend, and sandbox lifecycle simulation.
  • webhooks.manage: webhook endpoints, test deliveries, delivery listing, replay, and secret rotation.

Unsupported scopes are rejected.

Request IDs, Errors, And Idempotency

X-Request-Id is for diagnostics and traceability only. It is echoed in response headers and public API error bodies.

Use Idempotency-Key for duplicate prevention on supported mutations: file upload, envelope create/send/cancel/remind/extend, webhook test, and webhook replay.

Same organization plus same key plus same body returns the stored response. Same organization plus same key plus different body returns 409 Conflict. Current retention is 24 hours.

All public API errors use this shape:

{
  "error": {
    "code": "forbidden",
    "message": "OAuth token is missing scope: templates.read.",
    "details": [],
    "request_id": "crm-2026-09-11-001"
  }
}

Common HTTP statuses: 400, 401, 403, 404, 409, 429, 500.

Rate Limits And IP Allowlists

Rate limits are enforced per OAuth client and organization. Defaults are plan/config dependent: Professional 60/min, Business 180/min, Premium 600/min, Enterprise configurable. Upload/heavy operations use a lower upload-specific limit.

OAuth clients may optionally have IP allowlists. Leave the allowlist empty to accept any source IP. Add one IP address or CIDR range per line to restrict calls.

One Envelope Per Document

Stampa intentionally supports one document/template per envelope. If a customer needs multiple documents, create one envelope per document and group them in the source system using externalReference or externalMetadataJson.

Requests containing more than one document in documents are rejected with 400.

Template-Based Signing

Create from template:

curl -X POST https://admin.stamping.co.il/api/v1/envelopes/from-template \
  -H "Authorization: Bearer $STAMPA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: crm-envelope-001" \
  -H "Idempotency-Key: crm-envelope-001" \
  -d '{
    "title": "NDA for ACME Ltd",
    "workflowType": "Sequential",
    "templateId": "00000000-0000-0000-0000-000000000000",
    "expiresAt": "2026-10-11T10:00:00Z",
    "externalReference": "crm-agreement-001",
    "externalSystem": "igates-crm",
    "externalMetadataJson": "{\"crmRecordId\":\"crm-123\",\"agreementRequestId\":\"agr-456\"}",
    "recipients": [
      {
        "roleName": "Customer signer",
        "fullName": "Dana Cohen",
        "email": "dana@example.com",
        "phone": "+972501234567",
        "signingOrder": 1,
        "deliveryChannel": "Email",
        "authenticationMethod": "SecureLink",
        "type": "Signer",
        "language": "he"
      },
      {
        "roleName": "iGATES countersigner",
        "fullName": "Ofer Davidyan",
        "email": "ofer@igates.co.il",
        "phone": "+972547552558",
        "signingOrder": 2,
        "deliveryChannel": "Email",
        "authenticationMethod": "SecureLink",
        "type": "Signer",
        "language": "en"
      }
    ],
    "initialValues": []
  }'

Template roles are mapped by recipient.roleName. The role name must match a template role. Required roles that need completion must have recipients. Field prefill uses initialValues; each item references a fieldDefinitionId from template detail.

Allowed values:

  • Workflow: Sequential, Parallel, GroupedRounds.
  • Recipient type: Signer, FormFiller, Approver, Viewer, Cc.
  • Delivery channel: Email, Sms, WhatsApp, ManualLink, Api.
  • Authentication method: SecureLink, OtpSms, OtpWhatsApp.
  • Language: organization-supported language codes such as en or he; blank uses the organization default.

Recover after timeout:

curl https://admin.stamping.co.il/api/v1/envelopes/by-external-reference/crm-agreement-001 \
  -H "Authorization: Bearer $STAMPA_TOKEN" \
  -H "X-Request-Id: crm-recover-001"

Lifecycle

Envelope statuses: Draft, ReadyToSend, Sending, Sent, Opened, InProgress, WaitingForNextSigner, ProcessingFinalPdf, Completed, DeliveryFailed, FinalPdfFailed, Declined, Cancelled, Expired, Archived, Deleted.

Recipient statuses: Pending, WaitingForTurn, InvitationSent, DeliveryFailed, LinkOpened, AuthenticationPending, AuthenticationVerified, AuthenticationFailed, Viewed, InProgress, Completed, Declined, Cancelled, Expired.

Lifecycle endpoints:

  • GET /api/v1/envelopes/{id}
  • GET /api/v1/envelopes/by-external-reference/{externalReference}
  • GET /api/v1/envelopes/{id}/recipients
  • POST /api/v1/envelopes/{id}/send
  • POST /api/v1/envelopes/{id}/remind
  • POST /api/v1/envelopes/{id}/cancel
  • POST /api/v1/envelopes/{id}/extend

Completed Documents

GET /api/v1/envelopes/{id}/documents/final-pdf and GET /api/v1/envelopes/{id}/documents/audit-trail return authenticated PDF bytes. They do not return public redirects.

If an artifact is not ready, the API returns 404. Integrations should wait for document.final_pdf_ready or poll the envelope until finalPdfFileId and auditTrailFileId are populated.

Webhooks

Supported events: envelope.created, envelope.sent, recipient.opened, recipient.authentication_verified, recipient.authentication_failed, recipient.completed, recipient.declined, envelope.completed, envelope.cancelled, envelope.expired, envelope.delivery_failed, document.final_pdf_ready.

Delivery headers:

  • X-Stampa-Delivery: delivery ID.
  • X-Stampa-Event: event name.
  • X-Stampa-Timestamp: Unix timestamp in seconds.
  • X-Stampa-Signature: sha256=<lowercase-hex-hmac>.

Signature input:

<X-Stampa-Timestamp>.<raw request body>

Sample fixture:

secret: whsec_test_secret
timestamp: 1790000000
payload: {"id":"evt_test_001","type":"envelope.completed","created_at":"2026-09-11T10:00:00Z","data":{"envelope_id":"00000000-0000-0000-0000-000000000001","status":"Completed","external_reference":"crm-agreement-001"}}
expected signature: sha256=2aa12f214b10d712f677fef320841925b59e7d6e7e686cc816cedb991a610433

Reject deliveries outside your replay window, for example 5 minutes. Compare signatures with a constant-time comparison.

Webhook acknowledgement is any 2xx status. Failed responses retry up to 5 attempts with exponential backoff and jitter. Deliveries are at-least-once and may arrive out of order; consumers should deduplicate by X-Stampa-Delivery.

Sandbox Mode

When sandbox mode is enabled server-side, send X-Stampa-Sandbox: true. Sandbox requests still require a valid bearer token, plan eligibility, organization feature-flag access, scopes, IP allowlists, and rate-limit checks.

Sandbox create/get/send/cancel/remind/extend returns synthetic envelopes and does not create production envelopes, contact recipients, consume production charges, or queue production lifecycle webhooks.

Lifecycle simulation endpoints:

  • POST /api/v1/sandbox/envelopes/{id}/Completed
  • POST /api/v1/sandbox/envelopes/{id}/Declined
  • POST /api/v1/sandbox/envelopes/{id}/Expired
  • POST /api/v1/sandbox/envelopes/{id}/Cancelled

Webhook testing does not require real recipients. Use POST /api/v1/webhooks/{id}/test and POST /api/v1/webhooks/deliveries/{id}/replay.

Sandbox final PDF and audit-trail downloads return deterministic sample PDF bytes, so integrations can test authenticated download handling without production documents.

SDKs And Postman

  • TypeScript SDK: sdks/typescript
  • C# SDK: sdks/csharp/Stampa.Api.Client
  • Postman collection: docs/stampa-public-api.postman_collection.json