Certificate API

List Certificates

Retrieves all certificates for the authenticated user or a specific user (admin only).

Query Parameters

string

Admin only: User UUID to retrieve certificates for

Response

array

Array of certificate objects

Show Certificate Object

string

Certificate UUID

string

Unique certificate number (e.g., “CERT-1234”)

number

Course ID

string

Course title

string

Issue timestamp (ISO 8601)

string

Certificate type: “completion”, “participation”, “achievement”

Example Request

curl https://your-domain.com/api/certificates

Example Response

{
  "certificates": [
    {
      "id": "uuid-here",
      "certificateNumber": "CERT-1234567890-ABC123",
      "courseId": 42,
      "courseTitle": "Introduction to Programming",
      "issuedAt": "2024-01-15T10:30:00Z",
      "certificateType": "completion"
    }
  ]
}

Issue Certificate

Issues a new certificate for a completed course. Requires course completion and certificate enablement.

Request Body

number

required

Course ID to issue certificate for

Response

object

Show Certificate Object

string

Certificate UUID

string

Unique certificate number

string

Success or informational message

Example Request

curl -X POST https://your-domain.com/api/certificates \
  -H "Content-Type: application/json" \
  -d '{
    "courseId": 42
  }'

Example Response

{
  "certificate": {
    "id": "uuid-here",
    "certificateNumber": "CERT-1234567890-ABC123"
  },
  "message": "Certificate created successfully"
}

Validation

Before issuing a certificate, the API validates:

✓ User has completed the course (status = “completed”)
✓ Certificates are enabled for the course (certificate_enabled = true)
✓ Certificate doesn’t already exist for this user-course combination

Download Certificate

Generates and downloads a PDF certificate. The PDF is generated on-demand and uploaded to S3 for future access.

Path Parameters

string

required

Certificate UUID

Response

Returns a PDF file with:

Content-Type: application/pdf
Content-Disposition: attachment; filename="certificate-{number}.pdf"

Example Request

curl https://your-domain.com/api/certificates/uuid-here/download \
  -o certificate.pdf

Certificate Generation

The API:

Validates user access (owner or admin)
Checks if PDF already exists in S3
If not, generates PDF with:
- Platform logo and name (from brand settings)
- Learner name
- Course title
- Certificate number
- Issue date
- Certificate type (completion/participation/achievement)
- Digital signature (if configured)
Uploads PDF to S3
Saves PDF URL to database (certificate_url)
Returns PDF file

Certificate Types

Three certificate types are supported:

Type	Description	Use Case
completion	Course completion certificate	User completed all required lessons and quizzes
participation	Participation certificate	User attended/participated in the course
achievement	Achievement certificate	User achieved specific milestones or scores

Certificate Configuration

Certificates are configured at the course level with these fields:

Brand Integration

Certificates automatically include:

Platform Logo: Fetched from brand settings (logoBlack for white background)
Organization Name: From brand settings (platformName)
Fallback: Uses default logo and “EaseLMS” if brand settings unavailable

Certificate Notifications

When a certificate is issued, the API automatically:

Sends email notification to the user
Includes download link in the email
Email contains certificate number and course details

Certificate Number Format

Certificate numbers are generated as:

CERT-{timestamp}-{random}

Example: CERT-1705320600000-A1B2C3D4E This ensures:

Uniqueness (timestamp + random)
Sortability (timestamp-based)
Easy identification (CERT prefix)

PDF Storage

Generated PDFs are:

Stored in S3 with path: certificates/{userId}/certificate-{number}.pdf
URL saved to certificate_url field
Reused for future downloads (regenerated only if missing)
Accessible via direct S3 URL or download endpoint

Error Codes

Status Code	Description
200	Success - Returns PDF file
400	Bad Request - Course not completed or certificates disabled
401	Unauthorized - Authentication required
403	Forbidden - Not authorized to download this certificate
404	Not Found - Certificate not found
500	Internal Server Error - PDF generation failed

Overview

Resources

Certificate API

List Certificates

Query Parameters

Response

Example Request

Example Response

Issue Certificate

Request Body

Response

Example Request

Example Response

Validation

Download Certificate

Path Parameters

Response

Example Request

Certificate Generation

Certificate Types

Certificate Configuration

Brand Integration

Certificate Notifications

Certificate Number Format

PDF Storage

Error Codes

​List Certificates

​Query Parameters

​Response

​Example Request

​Example Response

​Issue Certificate

​Request Body

​Response

​Example Request

​Example Response

​Validation

​Download Certificate

​Path Parameters

​Response

​Example Request

​Certificate Generation

​Certificate Types

​Certificate Configuration

​Brand Integration

​Certificate Notifications

​Certificate Number Format

​PDF Storage

​Error Codes

List Certificates

Query Parameters

Response

Example Request

Example Response

Issue Certificate

Request Body

Response

Example Request

Example Response

Validation

Download Certificate

Path Parameters

Response

Example Request

Certificate Generation

Certificate Types

Certificate Configuration

Brand Integration

Certificate Notifications

Certificate Number Format

PDF Storage

Error Codes