API Version 1.0 (Live)

Certificate Generation API Reference

Welcome to the CertEngine Pro API. Our RESTful JSON API enables you to seamlessly integrate enterprise-grade automated certificate generation, email delivery, and cryptographic verification directly into your own software, Learning Management System (LMS), or HR platform.

Automate Your Workflow with our API

While our web dashboard is perfect for bulk CSV uploads, the Certificate Generation API is designed for continuous automation. For example, the moment a student scores 100% on a test in your LMS, your server can ping our /issue endpoint. We instantly render the PDF certificate in the background, secure it with a QR code, and email it to the student without any manual intervention.

Authentication & Setup

The API requires Bearer Token authentication. All requests must be made over HTTPS. API keys are strictly tied to your workspace and should never be exposed in frontend client code.

Generating Your API Keys:

  1. Log into your Developer Dashboard as an Admin.
  2. Navigate to Settings > Developer API.
  3. Click Generate Secret Key and securely store the token.

Include your secret key in the Authorization header:

HTTP Headers 
Authorization: Bearer ce_live_xxxxxxxxxxxxxxxxxxxxxxxxx

Rate Limits & Async Architecture

To guarantee stability across all enterprise clients, the API enforces a limit of 60 requests per minute per workspace.

Because generating high-resolution PDF certificates is computationally heavy, our generation endpoints (/issue and /batch-issue) operate asynchronously. When you send a valid request, we instantly return a 202 Accepted status. The job is placed in our Redis queue, processed, and we will fire a Webhook back to your server once the PDF is ready.

GET

List Active Templates

Endpoint: /v1/templates

Retrieves all active design templates available in your workspace. This endpoint is critical because it returns the required_dynamic_fields array, telling your application exactly which variables (like "Name" or "Course Title") need to be passed to generate the certificate successfully.

Response: 200 OK 
{
  "success": true,
  "data": [
    {
      "template_id": "tpl_9f8e7d6c5b",
      "name": "Employee of the Month",
      "dimensions": { "width": 1920, "height": 1080 },
      // Send these exact keys in your /issue request
      "required_dynamic_fields": [
        "Department",
        "Manager Name",
        "Award Month"
      ]
    }
  ]
}
GET

Get Workspace Balance

Endpoint: /v1/workspace/balance

Retrieve your current credit balance, plan tier, and a ledger of recent transactions.

POST

Generate a Single Certificate

Endpoint: /v1/certificates/issue

This is the core endpoint to automatically generate a digital certificate. It logs the record, deducts 1 credit, and queues the PDF render.

Request Parameters

Parameter Type Description
template_id
Required		 string The unique ID of the template from the templates endpoint.
recipient_name
Required		 string Full name of the recipient (e.g., "Jane Doe").
recipient_email string Email address. Required if you set send_email to true.
dynamic_fields object Key-value pairs matching your template variables.
Note on ID Strategy: If your workspace requires "Manual" Certificate IDs instead of Auto-generation, you must pass "Certificate ID": "YOUR_ID" inside this object.
send_email boolean Set to true to have CertEngine automatically email the certificate via your Custom SMTP.
POST Request Payload
Response: 202 Accepted 
{
  "template_id": "tpl_9f8e7d6c5b",
  "recipient_name": "Jane Doe",
  "recipient_email": "jane@company.com",
  "send_email": true,
  "dynamic_fields": {
    "Department": "Engineering",
    "Manager Name": "John Smith",
    // Required ONLY if workspace is set to 'Manual IDs'
    "Certificate ID": "ENG-2023-001" 
  }
}
POST

Bulk Certificate Generation API

Endpoint: /v1/certificates/batch-issue

Queue multiple certificates in a single API call. This is the optimal way to automate bulk operations and bypass the 60 requests/minute limit.
Important Payload Limit: The maximum array size permitted dynamically scales with your Plan Tier. Exceeding your limit triggers a 413 Payload Too Large.

Batch Payload 
{
  "template_id": "tpl_9f8e7d6c5b",
  "recipients": [
    {
      "recipient_name": "Alice Cooper",
      "recipient_email": "alice@company.com",
      "dynamic_fields": { "Department": "Sales" }
    },
    {
      "recipient_name": "Bob Builder",
      "send_email": false,
      "dynamic_fields": { "Department": "Construction" }
    }
  ]
}
GET

Retrieve Certificate

Endpoint: /v1/certificates/{uuid}

Fetch the public verification URL, image paths, and current status of an existing certificate using its unique UUID.

POST

Revoke a Certificate

Endpoint: /v1/certificates/{uuid}/revoke

Permanently revoke a certificate. This instantly flags the database. If an employer or auditor subsequently scans the certificate's QR code or visits its URL, they will be met with a strict "Credential Revoked" security warning.

Response 
{
  "success": true,
  "message": "Certificate successfully revoked.",
  "data": {
    "certificate_id": "CE-2023-X7Y8Z9",
    "status": "revoked"
  }
}

Webhooks & Event Triggers

Because CertEngine handles PDF rendering asynchronously, your application shouldn't "poll" or guess when an image is ready. Instead, configure a Webhook URL in your Developer Dashboard. We will dispatch an HTTP POST request to your server the millisecond an event occurs.

Event: certificate.issued

Fired when a queued certificate has been successfully generated and saved to AWS/cloud storage. The payload contains the final verification link and document identifiers.

{
  "event": "certificate.issued",
  "timestamp": "2023-10-16T09:16:00Z",
  "data": {
    "certificate_id": "CE-2023-X7Y8Z9",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "recipient_name": "Jane Doe",
    "remaining_credits": 1247
  }
}

Standard Error Codes

  • 400
    Bad Request: Missing parameters, invalid template ID, or missing a Manual ID when required by workspace settings.
  • 401
    Unauthorized: Missing or invalid Bearer token. Verify your keys in the dashboard.
  • 402
    Payment Required: Insufficient workspace credits to complete the transaction. Purchase a top-up bundle.
  • 404
    Not Found: Template or Certificate UUID not found within your organization's scope.
  • 413
    Payload Too Large: You exceeded the dynamic batch limit permitted by your current subscription plan tier.
  • 429
    Too Many Requests: You have exceeded the 60 requests/minute API rate limit. Please throttle your application.