Skip to content
Sign in Start free

REST API

Issue certificates from your own backend

The CertSeal REST API lets you issue certificates and look them up from your LMS, product, or any other system. Clean JSON, bearer authentication, and signed webhooks.

Read full API docs Prefer no-code? Try Zapier

Overview

Predictable, well-documented, fast

Base URL: https://services.certseal.com/api/v1 — every request uses a workspace API key created in the CertSeal app.

REST + JSON

Predictable JSON over HTTPS with a full OpenAPI spec. Base URL: https://services.certseal.com/api/v1

Webhooks

Subscribe to issuance, delivery, failure, and view events. HMAC-signed payloads with automatic retries.

Batch-first workflow

Create a batch with your design once, then POST recipients with dynamic fields. Issue single or up to 100 at a time.

Issue a certificate

One request. Personalized. Delivered.

Create a batch with your design once, then POST a recipient with dynamic fields. Set send: true to email the certificate immediately.

POST /api/v1/batches/{batchId}/recipients 201 Created 
curl -X POST https://services.certseal.com/api/v1/batches/clx1abcd0000xxxxabcd/recipients \
  -H "Authorization: Bearer $CERTSEAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace",
    "email": "ada@analyticalengine.org",
    "data": {
      "course": "Advanced React Patterns",
      "completed_on": "2026-03-14",
      "score": "96%"
    },
    "send": true
  }'

Authenticate with Authorization: Bearer csk_live_...

Endpoints

Everything you need to automate issuance

Full request and response schemas are in the interactive API reference.

Auth

Verify your API key and get a human-readable workspace label.

  • POST /auth — test API key

Batches

Group recipients under a single design. Create a batch first, then issue into it.

  • GET /batches — list batches
  • POST /batches — create a batch
  • GET /batches/{id} — get a batch
  • POST /batches/{id}/archive — archive
  • POST /batches/{id}/unarchive — unarchive

Recipients

Issue, update, and deliver certificates to individual recipients.

  • GET /batches/{batchId}/recipients — list
  • POST /batches/{batchId}/recipients — issue one
  • POST /batches/{batchId}/recipients/bulk — issue up to 100
  • PATCH /batches/{batchId}/recipients/{id} — update
  • DELETE /batches/{batchId}/recipients/{id} — delete
  • POST /batches/{batchId}/recipients/{id}/send — queue email

Certificates

Look up issued certificates by human-readable ID or share token.

  • GET /certificates/{certificateId} — lookup by ID
  • GET /certificates/by-token/{shareToken} — lookup by share token

Webhooks

Subscribe to workspace events with HMAC-signed deliveries.

  • GET /webhooks/subscriptions — list
  • POST /webhooks/subscriptions — subscribe
  • DELETE /webhooks/subscriptions/{id} — unsubscribe
  • POST /webhooks/subscriptions/{id}/test — send sample event

View full OpenAPI reference →

Webhooks

Get notified instead of polling

Register a webhook subscription and CertSeal POSTs signed JSON to your URL when events happen in your workspace.

Event When it fires
certificate.issued A new recipient was created — via API, bulk import, or the web app.
certificate.sent The certificate email was successfully handed to the mail provider.
certificate.failed The email provider rejected the message. Payload includes an error string.
certificate.viewed Someone opened the public viewer URL for the first time (at most once per recipient).

Deliveries include an X-CertSeal-Signature header. Verify with your subscription signing secret and reject replays older than 5 minutes.

Limits

Rate limits and quotas

Designed for production use with clear limits and machine-readable error codes.

120 req/min

Default rate limit per API key. Returns 429 RATE_LIMITED with Retry-After when exceeded.

Issuing uses quota

Each issued certificate consumes one unit of your plan quota. Lookups, lists, and updates are free.

Stable error codes

Non-2xx responses use { error, message, detail } — the error field is machine-readable.

FAQ

What developers ask first

How do I authenticate?
Send your workspace API key as a Bearer token: Authorization: Bearer csk_live_.... Keys are created from the API Keys page in the CertSeal app and are shown exactly once.
What are the rate limits?
Each API key is limited to 120 requests per minute by default. Exceeding the limit returns 429 with a Retry-After header. Standard RateLimit-* headers are included on every response.
How do webhooks work?
Register a subscription with your URL and the events you want. CertSeal POSTs signed JSON to your endpoint. Verify the X-CertSeal-Signature header using your subscription signing secret. Deliveries are at-least-once — use X-CertSeal-Delivery as an idempotency key.
Do I need to create a batch before issuing?
Yes. A batch ties recipients to a single design (and optional email template). Create the batch via the API or web app, then POST recipients into it.

Start building with the CertSeal API

Read the full interactive reference with request samples, schemas, and webhook verification examples.

Read API docs