CertLaurel

API documentation

Issue a certificate with one HTTP call. The recipient is emailed automatically, and every certificate gets a public verification page. The API is included on every plan, free included.

Quickstart

1 Create an account and verify your email — sign up free, then open the verification link we email you.

2 Create an API key — in the dashboard: API keys → Create key. Pick the issue scope for automations that only send certificates, or full for everything. The full key is shown once — store it somewhere safe.

3 Issue a certificate:

curl -X POST https://certlaurel.com/v1/certificates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: workshop-2026-11-ada-001" \
  -d '{
    "template": "classic",
    "recipient_name": "Ada Lovelace",
    "recipient_email": "ada@example.com",
    "program_title": "Spring Workshop Series",
    "issue_date": "2026-11-14",
    "custom_line": "12 continuing education credit hours"
  }'

4 Read the response. A 201 means the certificate was issued and emailed. The response includes the verification_url — the public page the QR code on the certificate opens:

{
  "id": 42,
  "verify_id": "8fK2mQ9xR4tZbN7pL",
  "status": "issued",
  "template": "classic",
  "recipient_name": "Ada Lovelace",
  "recipient_email": "ada@example.com",
  "program_title": "Spring Workshop Series",
  "issuer_name": "Your Organization",
  "issue_date": "2026-11-14",
  "verification_url": "https://certlaurel.com/verify/8fK2mQ9xR4tZbN7pL",
  "pdf_url": "https://certlaurel.com/files/42/pdf?exp=...&sig=...",
  "png_url": "https://certlaurel.com/files/42/png?exp=...&sig=...",
  "delivery": { "status": "sent", "to_email": "ada@example.com" }
}

The pdf_url / png_url are signed download links that expire (7 days by default) — fetch fresh ones any time with GET /v1/certificates/:id. The verification URL never expires.

Authentication

Send your key on every request: Authorization: Bearer YOUR_API_KEY. Keys are stored only as hashes on our side; if a key leaks, revoke it in the dashboard and create a new one — revocation takes effect immediately.

ScopeCan do
issueIssue certificates (POST /v1/certificates, POST /v1/batches), read usage and templates. Nothing else.
fullEverything: issue, fetch, list, revoke, resend, batches.

Each key can make up to 60 requests per minute. Over that, you'll get a 429 rate_limited response with a Retry-After header — wait that many seconds and continue.

Endpoints

Method & pathScopeWhat it does
POST /v1/certificatesissueIssue one certificate and email it to the recipient. → 201 (200 on an idempotent replay). 402 when out of credits.
GET /v1/certificates/:idfullFetch one certificate: status, fresh signed file URLs, latest delivery status.
GET /v1/certificates?limit=&cursor=fullList your certificates, newest first (your issuance record).
POST /v1/certificates/:id/revokefullRevoke a certificate. Optional JSON body: { "reason": "..." }. The verification page flips to REVOKED immediately. No credit refund.
POST /v1/certificates/:id/resendfullRe-send the delivery email. Free.
POST /v1/batchesissueBulk issue from CSV — see "Bulk issuing" below.
GET /v1/batches/:idfullFetch a batch: counts, per-row errors, issued certificates.
GET /v1/usageany keyCurrent period: plan, allowance, used, remaining.
GET /v1/templatesany keyThe active templates and the fields they accept.
GET /verify/:verifyIdpublicThe public verification page (HTML). Also at /verify/:verifyId.json as JSON, with the certificate preview at /verify/:verifyId/preview.png.
GET /files/:certId/:kind?exp=&sig=signed URLDownload the PDF (kind=pdf) or PNG (kind=png) behind a signed, expiring link.
GET /healthpublicLiveness and configuration summary.

Issuing: fields

FieldRequiredNotes
recipient_nameyesPrinted on the certificate.
recipient_emailyesThe certificate is emailed here.
program_titleyesThe course / workshop / event name printed on the certificate.
templatenoA template slug from GET /v1/templates. Defaults to classic.
issue_datenoYYYY-MM-DD. Defaults to today.
custom_linenoOptional extra line, e.g. hours or CE credits.
issuer_namenoDefaults to your account's business name.
signature_name / signature_titlenoThe signature block printed on the certificate.
curl https://certlaurel.com/v1/usage -H "Authorization: Bearer YOUR_API_KEY"
curl https://certlaurel.com/v1/templates -H "Authorization: Bearer YOUR_API_KEY"
curl https://certlaurel.com/verify/8fK2mQ9xR4tZbN7pL.json

Idempotency — safe retries

Networks fail and automations re-run. Send an Idempotency-Key header with each issue request, unique per certificate you intend to create (an attendee ID, a row number, a form response ID all work well).

Credits and limits

Bulk issuing from CSV

Two ways in: upload the file in the dashboard (Bulk CSV), or post it to the API:

curl -X POST https://certlaurel.com/v1/batches \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: class-of-nov-2026" \
  -d '{
    "filename": "class.csv",
    "defaults": { "program_title": "Spring Workshop Series" },
    "csv": "recipient_name,recipient_email\nAda Lovelace,ada@example.com\nGrace Hopper,grace@example.com"
  }'

The first row is a header: recipient_name, recipient_email are required columns; program_title, issue_date, custom_line, template are optional per-row columns, and common aliases (name, email, course) are understood. Values in defaults apply to rows that don't carry their own. A raw text/csv body works too, with defaults as query parameters.

Partial success is normal: good rows issue, bad rows come back in errors with a plain explanation ("Row 3: the email looks incomplete — 'sam@exampl'"), and you're charged only for rows that issued. Re-posting with the same Idempotency-Key replays safely — each row derives its own key.

No code? Use Zapier or Make

The same POST /v1/certificates endpoint works from Zapier's Webhooks by Zapier action or a Make HTTP module — no programming. Popular recipes:

Use an issue-scope key, set the Idempotency-Key header to the trigger's unique ID (row ID, attendee ID, response ID), and map the name/email fields. The full step-by-step guide, with exact settings for each recipe, is here: Zapier & Make guide.

Errors

Every API error is JSON: { "error": { "code": "...", "message": "..." } }. The message is written to be shown to a human — it says what happened and what to do next.

HTTPCodeMeaning & what to do
400validation_errorA field is missing or doesn't look right. The message names the field — fix it and retry.
400template_not_foundThat template slug isn't available. GET /v1/templates lists the current ones.
400invalid_jsonThe request body wasn't valid JSON. Check for a missing comma or quote.
400empty_csv / missing_columns / no_rowsThe CSV upload was empty, missing its name/email header columns, or had a header but no recipients.
401unauthorizedThe API key is missing, wrong, or revoked. Re-copy it from the dashboard, or create a new one.
402insufficient_creditsYou're out of certificates for this period. Upgrade, or wait for the next period — the response includes an upgrade link. Nothing was charged.
403insufficient_scopeYour key can't do this (e.g. an issue key trying to revoke). Create a full-scope key.
403invalid_signatureA signed download link was changed or copied incompletely. Fetch a fresh link from the certificate.
404not_foundThat certificate, batch, or file doesn't exist — or it belongs to a different account.
409idempotency_conflictThat Idempotency-Key was already used for a different certificate. Use a fresh key for a new certificate.
410link_expiredA signed download link has expired. Fetch the certificate again for fresh links.
413payload_too_largeThe request was too large. Split big CSV uploads into smaller files.
429rate_limitedMore than 60 requests in a minute on one key. Wait the number of seconds in the Retry-After header, then continue.
502render_failedWe couldn't generate the certificate. You weren't charged — try again.
503billing_not_configuredPlan changes aren't open yet. Your current plan keeps working.