> ## Documentation Index
> Fetch the complete documentation index at: https://docs.easelms.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Certificate API

> API endpoints for issuing and downloading course completion certificates

## List Certificates

<api method="GET" endpoint="/api/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

**Certificate Object**

**id** `string`

Certificate UUID

**certificateNumber** `string`

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

**courseId** `number`

Course ID

**courseTitle** `string`

Course title

**issuedAt** `string`

Issue timestamp (ISO 8601)

**certificateType** `string`

Certificate type: "completion", "participation", "achievement"

### Example Request

```bash theme={null}
curl https://your-domain.com/api/certificates
```

### Example Response

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

***

## Issue Certificate

<api method="POST" endpoint="/api/certificates" />

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`

**Certificate Object**

**id** `string`

Certificate UUID

**certificateNumber** `string`

Unique certificate number

**message** `string`

Success or informational message

### Example Request

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

### Example Response

```json theme={null}
{
  "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

<api method="GET" endpoint="/api/certificates/{id}/download" />

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

```bash theme={null}
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:

| 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:

Enable/disable certificates for this course

Certificate type: "completion", "participation", "achievement"

Custom template selection

Custom certificate title (e.g., "Certificate of Excellence")

Custom description text

URL to signature image

Signatory name

Signatory title (e.g., "CEO", "Lead Instructor")

Additional custom text

***

## 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 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.