Developers

Integrating AccordSeal: an overview for developers

How the pieces of the developer platform fit together: keys or OAuth, creating an agreement, embedded signing, webhooks, and testing in the sandbox.

By the AccordSeal team · Updated · 5 min read

This is a map of the AccordSeal developer platform, not a reference. The full reference is generated from the OpenAPI 3.1 specification and lives inside the app, under Developer settings, together with an integration guide and curl examples.

Choose how to authenticate

API keyOAuth 2.0
Use it whenYour own back end talks to your own AccordSeal organization.Your application acts on behalf of other AccordSeal users or organizations.
HowCreate a key with the scopes it needs and an expiry date. The secret is shown once.Authorization code with PKCE and a consent screen, or client credentials for machine-to-machine.
Good to knowLive keys start ask_live_; test keys start ask_test_.Refresh tokens rotate, and reuse of an old one is detected. Revocation, introspection and RFC 8414 metadata are supported.

Create an agreement

The public API lives under /api/public/v1. You can create an agreement from an uploaded document or from a template in a single call, then send it, remind recipients or void it. When it is complete you can download the signed PDF and the certificate.

Two habits make an integration robust:

  • Send an Idempotency-Key with any request that creates something. If your request times out and you retry within 24 hours, you receive the original response instead of a duplicate agreement.
  • Read the X-RateLimit-* headers. Limits apply per credential and per plan; the headers tell you how much room you have.

Lists use cursor pagination, and every error uses the same envelope, so one error handler covers the whole API.

Embed the signing step

To keep signers inside your product, request an embedded signing URL and load it in a frame.

  • The URL can be used once and expires after five minutes, so request it at the moment you need it.
  • Your page receives postMessage events as the signer progresses.
  • Only origins you have approved can frame the signing page; add them to the key's embed origins.

Listen for webhooks

There are eleven events across three groups: agreement.* (sent, completed, declined, expired, voided), recipient.* (viewed, signed, declined, delegated) and document.* (ready, failed).

Payloads are signed; verify the signature before acting on one. Deliveries are retried, and an endpoint that keeps failing is disabled automatically — you are emailed when that happens. The delivery log shows every attempt, and you can redeliver an event or send a test ping while you build.

Make your handler idempotent. Retries mean you may see the same event more than once.

Test in the sandbox

With a test key, agreements are created in sandbox mode. Emails are captured in a developer log rather than sent, documents carry a “TEST — not legally binding” watermark, and nothing counts towards usage. You can run your whole test suite against it.

Engagement tracking in your own systems

Signer engagement tracking — opens, viewing time, location — is visible in the app and is also available through the public API. Tracking events can be delivered as webhooks, so opens and views reach your systems in real time.

Run your next agreement from draft to proof.

Start with the Free plan, or ask us to walk your team through AccordSeal with your own documents.