CertSeal REST API

The CertSeal REST API lets you build custom integrations: create batches, issue single or bulk certificates, look up issued certificates, and manage webhook subscriptions. For an interactive reference, see the full API reference.

Base URL

All endpoints are served over HTTPS under the /api/v1 prefix:

https://services.certseal.com/api/v1

Authentication

Send your workspace API key as a Bearer token on every request:

Authorization: Bearer csk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create and manage keys in CertSeal under Settings → API keys. The full token is shown once at creation (it starts with csk_live_); store it securely. A workspace can have up to 10 active keys, and the workspace is implied by the key — there’s no workspace ID to pass.

Authentication errors return 401 with a stable code: MISSING_API_KEY, INVALID_API_KEY, or EXPIRED_API_KEY.

Rate limits

Each API key is limited to 120 requests per minute. Standard RateLimit-* headers are included on every response. Exceeding the limit returns 429 with the RATE_LIMITED code and a Retry-After header (in seconds).

Endpoints

All endpoints require the Authorization header above.

Auth

Method	Path	Description
POST	/auth	Verify the API key; returns workspaceId and username.

Batches

Method	Path	Description
GET	/batches	List batches (cursor, limit 1–100, status = active/archived/all).
GET	/batches/{id}	Get a single batch.
POST	/batches	Create a batch (requires title and designId).
POST	/batches/{id}/archive	Archive a batch.
POST	/batches/{id}/unarchive	Restore an archived batch.

Designs

Method	Path	Description
GET	/designs	List your certificate designs (read-only).

Recipients

Recipients are nested under a batch.

Method	Path	Description
GET	/batches/{batchId}/recipients	List recipients (optional emailStatus filter, pagination).
GET	/batches/{batchId}/recipients/{recipientId}	Get one recipient.
POST	/batches/{batchId}/recipients	Issue one certificate (optional send: true).
POST	/batches/{batchId}/recipients/bulk	Issue up to 100 certificates in one call.
PATCH	/batches/{batchId}/recipients/{recipientId}	Update a recipient or its variables.
DELETE	/batches/{batchId}/recipients/{recipientId}	Delete a recipient.
POST	/batches/{batchId}/recipients/{recipientId}/send	Queue the certificate email.

Certificates

Method	Path	Description
GET	/certificates/{certificateId}	Look up a certificate by ID (CERT-2026-...).
GET	/certificates/by-token/{shareToken}	Look up by public share token.

Webhooks

Method	Path	Description
GET	/webhooks/subscriptions	List subscriptions.
POST	/webhooks/subscriptions	Create a subscription; returns the signing secret once.
GET	/webhooks/subscriptions/{id}	Get a subscription.
DELETE	/webhooks/subscriptions/{id}	Delete a subscription.
POST	/webhooks/subscriptions/{id}/test	Send a sample delivery.
POST	/webhooks/subscriptions/{id}/rotate-secret	Rotate the signing secret.

See the Webhooks guide for events, payloads, and signature verification.

Errors

Non-2xx responses use a consistent JSON envelope:

{
  "error": "VALIDATION_ERROR",
  "message": "A human-readable explanation.",
  "detail": { "field": "email" }
}

Common codes include VALIDATION_ERROR, NOT_FOUND, CONFLICT, BATCH_ARCHIVED, QUOTA_EXCEEDED, PLAN_LIMIT_EXCEEDED, and RATE_LIMITED, alongside the auth codes above.

Example request

Issue a single certificate and email it immediately:

curl -X POST \
  https://services.certseal.com/api/v1/batches/BATCH_ID/recipients \
  -H "Authorization: Bearer $CERTSEAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "data": { "course": "Advanced React Patterns", "score": "96%" },
    "send": true
  }'

Support

Building on the API? Email support@certseal.com — we typically reply within 1 business day (Monday–Friday, 9:00 AM–6:00 PM SGT). See the support guide for all contact options.