Skip to main content

​
List Certificates

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

​
Query Parameters

​
userId
string
Admin only: User UUID to retrieve certificates for

​
Response

​
certificates
array
Array of certificate objects

​
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

​
courseId
number
required
Course ID to issue certificate for

​
Response

​
certificate
object
​
message
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:
  1. ✓ User has completed the course (status = “completed”)
  2. ✓ Certificates are enabled for the course (certificate_enabled = true)
  3. ✓ 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

​
id
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:
  1. Validates user access (owner or admin)
  2. Checks if PDF already exists in S3
  3. 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)
  4. Uploads PDF to S3
  5. Saves PDF URL to database (certificate_url)
  6. Returns PDF file

​
Certificate Types

Three certificate types are supported:
TypeDescriptionUse Case
completionCourse completion certificateUser completed all required lessons and quizzes
participationParticipation certificateUser attended/participated in the course
achievementAchievement certificateUser 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:
  1. Sends email notification to the user
  2. Includes download link in the email
  3. 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:
  1. Stored in S3 with path: certificates/{userId}/certificate-{number}.pdf
  2. URL saved to certificate_url field
  3. Reused for future downloads (regenerated only if missing)
  4. Accessible via direct S3 URL or download endpoint

​
Error Codes

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