API documentation

Base: https://smartcerts.co/api/v1 · Format: JSON (UTF-8) · Dates: AAAA-MM-DD

Quickstart

1. In the dashboard, under API, create a key (Professional, Scale and free trial plans).
2. Create an issuance in the dashboard or through the API and note its id.
3. Issue:

curl -X POST https://smartcerts.co/api/v1/issuances/42/credentials \
  -H "Authorization: Bearer $SMARTCERTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"recipient_name":"Ana Beatriz Souza","recipient_email":"ana@exemplo.com","external_id":"aluno-1287","send_email":true}'

The response includes the code and the url of the credential.

Authentication

Send the key in the header Authorization: Bearer <chave>. The key belongs to the organization, not a person, and is shown only once when created. Revoke unused keys in the dashboard.

Issuances

An issuance is a course, event or certification: type, title, edition, duration, template, signature and delivery email.

Method	Breadcrumb
GET	/issuances	List (paginated: page, per_page up to 100)
GET	/issuances/{id}	One issuance
POST	/issuances	Create. Fields: title (required), type, template (classico, moderno, minimal), edition, hours, location, title_url, description, signer, signer_role, email_subject, email_body

Types: participation, completion, professional, training, workshop, event, recognition, other.

Issue credentials

POST /issuances/{id}/credentials

Field
recipient_name	Required
recipient_email	For email delivery and search
external_id	The ID in your system. Idempotency: repeating the same value returns the existing credential (200) instead of creating another
title	Document title (default: based on type, e.g. "Certificate of Completion")
extra_info	Additional text (score, module, note)
issued_on, expires_on	Dates (issuance defaults to today; no expiration)
send_email	true sends the delivery email immediately

Without external_id, the same email in the same issuance does not generate a second credential. Response: 201 (created) or 200 (already existed), with the credential object.

In batches (up to 500 per call): send {"credentials": [ {...}, {...} ], "send_email": false}. The response separates created, existing and over_quota.

Query

Method	Breadcrumb
GET	/credentials	Filters: issuance_id, email, external_id; paginated
GET	/credentials/{code}	A credential from your organization

Revoke

POST /credentials/{code}/revoke with {"reason": "..."} (optional). The public page will show "revoked" and the reason.

Verify (public)

GET /verify/{code}, without a key: returns the same information as the public page, excluding recipient email. Useful for verifying certificates from another system.

curl https://smartcerts.co/api/v1/verify/k7m2p9x4w3qa

Credential object

{
  "code": "k7m2p9x4w3qa",
  "state": "valid",               // valid | expired | revoked
  "url": "https://smartcerts.co/certificate/k7m2p9x4w3qa",
  "pdf_url": "https://smartcerts.co/certificate/k7m2p9x4w3qa/pdf",
  "title": "Certificado de Conclusão",
  "recipient": { "name": "Ana Beatriz Souza", "email": "ana@exemplo.com" },
  "issuer": { "name": "Instituto Exemplo", "website": "https://..." },
  "issuance": { "id": 42, "type": "completion", "title": "Gestão de Projetos na Prática", "edition": "Turma de setembro", "hours": "40 horas" },
  "extra_info": null,
  "external_id": "aluno-1287",
  "issued_on": "2026-09-15",
  "expires_on": null,
  "revoked_at": null,
  "revocation_reason": null,
  "sent_at": "2026-09-15T14:02:11-03:00",
  "views": 3,
  "downloads": 1
}

Errors and limits

Errors always use the format {"error": {"code": "...", "message": "...", "fields": {...}}}.

HTTP	code
401	unauthorized	Missing or invalid key
402	quota_exceeded	Free trial limit reached
403	plan_required	Plan without API access
404	not_found	Does not exist or belongs to another organization
422	invalid	Invalid fields (details in fields)
429		Over 120 calls per minute per key (public verification: 60 per minute per IP)

There are no credential webhooks or sandbox yet. To test, use the free trial or a test issuance and revoke it afterward.