API Documentation

Complete reference guide for the Certificate Generator API

                Base URL: https://certgenapi.skalatec.com

                Current Version: v1

                Response Format: PDF files or JSON

Getting Started

The Certificate Generator API allows you to create professional PDF certificates programmatically. Generate certificates in under 2 seconds with a simple HTTP request.

Quick Start

Here's the simplest way to generate your first certificate:

curl -H "X-API-Key: your_api_key" \
  "https://certgenapi.skalatec.com/certificate?certificate_name=John%20Doe&template_url=https://certgenapi.skalatec.com/public/templates/classic-template.pdf&project=my-event"
                

That's it! The API will return a PDF certificate ready for download or display.

Key Features

Auto Resizing: We auto-resize text so you don't have to worry about people with long names
Customization: Change certificate settings to your liking such as font colors, font styles and more
QR Code Integration: Automatic QR code generation with your custom verification URL
Custom Certificate IDs: Use your own certificate ID format or auto-generate secure ULIDs
Multiple Styles: Pre-configured styles including Classic, Modern, Professional, Card, and Modern-Dark
Template Flexibility: Use any PDF template as a base for your certificates
Cloud Storage: Automatic upload to Cloudflare R2 with public access
Webhook Integration: Real-time notifications for processing results

Authentication

All API requests require authentication using an API key. You can provide the API key in two ways:

Method 1: Header (Recommended)

curl -H "X-API-Key: your_api_key_here" \
     "https://certgenapi.skalatec.com/certificate?certificate_name=John%20Doe&template_url=https://example.com/template.pdf&project=my-event"
                

Method 2: Query Parameter

curl "https://certgenapi.skalatec.com/certificate?api_key=your_api_key_here&certificate_name=John%20Doe&template_url=https://example.com/template.pdf&project=my-event"
                

                    Security Note: Always use HTTPS in production. Never expose your API key in client-side code or public repositories.
                

API Endpoints

Generate Certificate

GET /certificate
POST /certificate
                

Generates a certificate and returns JSON with download URL and certificate details. Both GET (query parameters) and POST (JSON body) methods supported.

Get Available Styles

GET /styles

Retrieve all available certificate styles with their properties. No authentication required.

Health Check

GET /health

Check the API status and health.

Parameters

Parameter	Type	Required	Description
`certificate_name`	string	Required	Full name of the certificate recipient
`template_url`	string (URL)	Required	URL to the PDF certificate template
`project`	string	Required	Project folder name for organizing certificates
`style`	string	Optional	Certificate style: Classic, Modern, Professional, Card, Modern-Dark
`certificate_id`	string	Optional	Custom certificate ID (auto-generated if not provided)
`certificate_id_prefix_url`	string	Optional	Base URL for QR code generation
`webhook_url`	string (URL)	Optional	Webhook endpoint to receive processing notifications

Response Format

Success Response

On successful certificate generation, the API returns a JSON response:

{
  "event": "certificate.generated",
  "timestamp": "2025-06-26T12:00:00.000Z",
  "data": {
    "certificate_name": "John Doe",
    "certificate_id": "CID-01HKQRST9V8WXY2Z3ABC4DEF5G",
    "style": "Classic",
    "uploaded_url": "https://storage.example.com/certificates/john-doe.pdf",
    "project_folder": "graduation-2024",
    "certificate_id_prefix_url": "https://verify.example.com"
  }
}
                

Error Response

In case of errors, the API returns a JSON response:

{
  "success": false,
  "message": "Error description",
  "data": {
    "error": "Detailed error information"
  }
}
                

QR Code Verification

Every generated certificate automatically includes a QR code for instant verification. Connect the QR codes to your own verification system by providing a custom verification URL.

How QR Code Verification Works

The API generates QR codes that link to your verification system with the certificate ID appended:

# Your verification URL structure
{certificate_id_prefix_url}/{certificate_id}

# Example QR code URL
https://your-verification-site.com/verify/CID-01HKQRST9V8WXY2Z3ABC4DEF5G
                

Setting Up Verification

Use the certificate_id_prefix_url parameter to specify your verification endpoint:

curl -H "X-API-Key: your_api_key" \
  "https://certgenapi.skalatec.com/certificate?certificate_name=John%20Doe&template_url=https://example.com/template.pdf&project=my-event&certificate_id_prefix_url=https://your-verification-site.com/verify"
                

QR Code Placement

QR codes are automatically placed in the bottom-right corner of each certificate with these specifications:

Property	Value	Description
Size	60x60 pixels	Optimized for scanning while not overwhelming the design
Position	Bottom-right corner	20px margin from bottom and right edges
Format	PNG	High quality, scannable QR code image
Content	Verification URL + Certificate ID	Direct link to your verification system

Certificate ID Format

Certificate IDs use ULID (Universally Unique Lexicographically Sortable Identifier) format for security and uniqueness:

                    Format: CID-01HKQRST9V8WXY2Z3ABC4DEF5G

                    Benefits: Cryptographically secure, chronologically sortable, URL-safe

                    Length: 30 characters (including CID- prefix)

Building Your Verification System

To implement certificate verification on your end:

Create a verification endpoint that accepts certificate IDs
Store certificate records when certificates are generated (use webhooks)
Handle QR code scans by looking up certificate IDs in your database
Display verification results showing certificate validity and details

                    Pro Tip: Use the webhook feature to automatically save certificate records to your database when they're generated, enabling seamless verification lookup.
                

Certificate Templates

Use our ready-to-use templates or bring your own PDF template. Templates define the layout and design of your certificates.

Built-in Templates

We provide professionally designed templates you can use immediately:

Template	URL	Best For
Classic Template	`https://certgenapi.skalatec.com/public/templates/classic-template.pdf`	Formal ceremonies, graduations, academic achievements
Modern Template	`https://certgenapi.skalatec.com/public/templates/modern-template.pdf`	Corporate training, workshops, professional certifications

Custom Templates

You can use any PDF file as a template. The API will overlay the certificate information on your design.

                    Template Requirements:

                    • PDF format (any size/orientation)

                    • Publicly accessible URL (HTTPS recommended)

                    • Reasonable file size (< 10MB)

                    • Leave space for name placement based on selected style

Template Design Tips

Design for the target certificate style positioning
Use high-resolution graphics for professional appearance
Test with different name lengths
Consider QR code placement (bottom-right area)
Ensure sufficient contrast for text overlay

Certificate Styles

Styles control how text is positioned and formatted on your certificate template.

Style	Size	Font	Positioning	Description
Classic	A4	Times Roman	Center, 59.6% from top	Traditional serif font with elegant positioning. Perfect for formal ceremonies.
Modern	A4	Overused Grotesk	Center, middle + 20px offset	Clean, contemporary design. Certificate ID in bottom right.
Modern-Dark	A4	Overused Grotesk	Center, middle + 20px offset	Same as Modern but optimized for dark backgrounds with light text.
Professional	A4	Times Roman	Center, middle positioning	Business-focused design ideal for corporate training.
Card	A5	Helvetica	Scaled for card size (70%)	Compact design optimized for card-sized certificates and badges.

Getting Available Styles Programmatically

Use the /styles endpoint to retrieve all available styles with their properties:

GET https://certgenapi.skalatec.com/styles

// Response:
{
  "success": true,
  "message": "Available certificate styles",
  "data": {
    "styles": [
      { "label": "Classic", "value": "Classic", "size": "A4" },
      { "label": "Modern", "value": "Modern", "size": "A4" },
      { "label": "Modern Dark", "value": "Modern-Dark", "size": "A4" },
      { "label": "Professional", "value": "Professional", "size": "A4" },
      { "label": "Card", "value": "Card", "size": "A5" }
    ],
    "count": 5
  }
}
                

Dynamic Font Sizing

The API automatically adjusts font size based on the recipient's name length:

// Font size calculation based on name length
Short names (< 15 chars): 72pt
Medium names (15-25 chars): 60pt
Long names (> 25 chars): 48pt
                

                    Pro Tip: Test your template with names of different lengths to ensure optimal appearance across all scenarios.
                

Webhook Integration

Webhooks allow you to receive real-time notifications about certificate processing results.

Webhook Events

Event	Description	When Triggered
`certificate.generated`	Certificate successfully created	When PDF generation and upload complete successfully
`certificate.failed`	Certificate generation failed	When any error occurs during processing

Webhook Payload

All webhooks are sent as POST requests with the following JSON structure:

Success Payload

{
  "event": "certificate.generated",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "certificate_name": "John Doe",
    "certificate_id": "CID-01HKQRST9V8WXY2Z3ABC4DEF5G",
    "style": "Modern",
    "uploaded_url": "https://storage.example.com/certificates/john-doe.pdf",
    "project_folder": "tech-conference",
    "certificate_id_prefix_url": "https://verify.example.com"
  }
}
                

Error Payload

{
  "event": "certificate.failed",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "certificate_name": "John Doe",
    "style": "Modern",
    "error": "Template URL is not accessible",
    "project_folder": "tech-conference"
  }
}
                

Webhook Requirements

HTTPS Only: Webhook URLs must use HTTPS protocol
Response Time: Your endpoint should respond within 10 seconds
Status Code: Return 2xx status code to acknowledge receipt
Content-Type: Webhooks are sent with Content-Type: application/json
User-Agent: Requests include User-Agent: Certificate-Generator-API/2.0.0

                    Important: Webhook delivery failures won't affect certificate generation. The API will continue to return the PDF file regardless of webhook status.
                

Error Handling

The API uses conventional HTTP response codes to indicate success or failure.

HTTP Status Codes

Status Code	Description	Common Causes
`200`	Success	Certificate generated successfully
`400`	Bad Request	Missing required parameters, invalid template URL, malformed request
`401`	Unauthorized	Missing or invalid API key
`429`	Too Many Requests	Rate limit exceeded (100 requests per 15 minutes)
`500`	Internal Server Error	Server-side processing error, template processing failure

Error Response Format

All error responses follow this JSON structure:

{
  "success": false,
  "message": "Human-readable error description",
  "data": {
    "error": "Detailed technical error information",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}
                

Common Error Examples

Missing API Key

HTTP 401
{
  "success": false,
  "message": "Authentication required",
  "data": {
    "error": "API key is missing or invalid"
  }
}
                

Invalid Template URL

HTTP 400
{
  "success": false,
  "message": "Template processing failed",
  "data": {
    "error": "Unable to download template from provided URL"
  }
}
                

Best Practices

Always check the HTTP status code first
Implement retry logic for 5xx errors
Handle rate limits with exponential backoff
Log error details for debugging
Validate parameters before sending requests

Code Examples

Quick examples in popular programming languages. For complete examples, visit our dedicated examples page.

Basic Certificate Generation

JavaScript (Fetch) - GET Request

const params = new URLSearchParams({
  certificate_name: 'John Doe',
  template_url: 'https://example.com/template.pdf',
  project: 'my-event'
});

const response = await fetch(`https://certgenapi.skalatec.com/certificate?${params}`, {
  headers: { 'X-API-Key': 'your_api_key' }
});

const result = await response.json();
console.log('Download URL:', result.data.uploaded_url);
                

JavaScript (Fetch) - POST Request

const response = await fetch('https://certgenapi.skalatec.com/certificate', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    certificate_name: 'John Doe',
    template_url: 'https://example.com/template.pdf',
    project: 'my-event'
  })
});

const result = await response.json();
                

Python (Requests)

import requests

response = requests.get(
    'https://certgenapi.skalatec.com/certificate',
    headers={'X-API-Key': 'your_api_key'},
    params={
        'certificate_name': 'John Doe',
        'template_url': 'https://example.com/template.pdf',
        'project': 'my-event'
    }
)

if response.status_code == 200:
    result = response.json()
    print(f"Certificate URL: {result['data']['uploaded_url']}")
                

PHP (cURL)

<?php
$url = 'https://certgenapi.skalatec.com/certificate?' . http_build_query([
    'certificate_name' => 'John Doe',
    'template_url' => 'https://example.com/template.pdf',
    'project' => 'my-event'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: your_api_key']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$result = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $data = json_decode($result, true);
    echo "Certificate URL: " . $data['data']['uploaded_url'];
}
?>
                

SDKs & Libraries

Official and community-maintained libraries to integrate with the Certificate Generator API.

Official SDKs

                    Coming Soon: We're working on official SDKs for popular languages. In the meantime, the REST API is easy to integrate with any HTTP client library.
                

HTTP Client Libraries

You can use any HTTP client library in your preferred language:

Language	Recommended Library	Documentation
JavaScript	Fetch API, Axios	View Examples
Python	Requests, aiohttp	View Examples
PHP	cURL, Guzzle	View Examples
Java	OkHttp, Apache HttpClient	Contact for examples
C#	HttpClient, RestSharp	Contact for examples

OpenAPI Specification

We provide an OpenAPI (Swagger) specification for easy integration:

                    OpenAPI Spec: https://certgenapi.skalatec.com/openapi.json

                    Swagger UI: https://certgenapi.skalatec.com/docs

Postman Collection

Import our Postman collection for quick testing and exploration:

Postman Collection: Download Collection
Environment Variables: Set your API key and base URL

Need Help?

Can't find what you're looking for? We're here to help!

Email Support: febrilian@skalatec.com
Response Time: Usually within 2-4 hours
Code Examples: Complete examples page
Get Started: Contact us to get started