Certificates API
The Certificates API allows you to request certificates, check approval status, download certificates and verify them programmatically.
List certificates
GET /api/v1/certificates
Query parameters
| Parameter | Type | Description |
|---|---|---|
type |
string | ghg_inventory, carbon_neutral, net_zero, offset_retirement, custom |
status |
string | pending, under_review, approved, issued, revoked |
periodStart |
date | Certificates covering periods that start on or after this date |
periodEnd |
date | Certificates covering periods that end on or before this date |
page |
integer | Page number |
pageSize |
integer | Max 100 |
Response
{
"data": [
{
"id": "cert_abc123",
"certId": "CERT-2024-ACME-0012",
"type": "carbon_neutral",
"status": "issued",
"beneficiaryName": "ACME Corporation Ltd",
"periodStart": "2024-01-01",
"periodEnd": "2024-12-31",
"scopeCoverage": [1, 2, 3],
"emissionsTco2e": 1240.5,
"offsetsTco2e": 1240.5,
"issuedAt": "2025-01-20T10:00:00Z",
"verifyUrl": "https://alchemos.io/verify/CERT-2024-ACME-0012"
}
]
}
Get a certificate
GET /api/v1/certificates/{certId}
Returns the full certificate record including audit trail and linked retirements.
Request a certificate
POST /api/v1/certificates
Request body
{
"type": "carbon_neutral",
"periodStart": "2024-01-01",
"periodEnd": "2024-12-31",
"beneficiaryName": "ACME Corporation Ltd",
"scopeCoverage": [1, 2, 3],
"retirementIds": ["ret_001", "ret_002"],
"signatoryName": "Jane Smith",
"signatoryTitle": "Chief Sustainability Officer",
"notes": "Annual carbon neutral certification for FY2024"
}
| Field | Type | Required | Description |
|---|---|---|---|
type |
string | ✅ | Certificate type code |
periodStart |
date | ✅ | Certification period start |
periodEnd |
date | ✅ | Certification period end |
beneficiaryName |
string | ✅ | Legal entity name on certificate |
scopeCoverage |
integer[] | ✅ | Scope numbers covered |
retirementIds |
string[] | Conditional | Required for carbon_neutral type |
signatoryName |
string | ✅ | Authorising signatory |
signatoryTitle |
string | ✅ | Signatory role/title |
notes |
string | Optional | Additional context |
Response (201)
{
"data": {
"id": "cert_xyz789",
"certId": "CERT-2024-ACME-0013",
"type": "carbon_neutral",
"status": "pending",
"createdAt": "2025-01-15T08:00:00Z"
}
}
Get certificate download URLs
GET /api/v1/certificates/{certId}/downloads
Returns pre-signed download URLs (valid for 15 minutes).
Response (issued certificates only)
{
"data": {
"pdf": "https://storage.alchemos.io/certs/...?token=...",
"svg": "https://storage.alchemos.io/certs/...?token=...",
"pngBadge": "https://storage.alchemos.io/certs/...?token=..."
}
}
Public verification endpoint
This endpoint requires no authentication and is suitable for embedding in external verification workflows.
GET https://api.alchemos.io/public/certificates/{certId}
Response
{
"certId": "CERT-2024-ACME-0012",
"type": "carbon_neutral",
"status": "valid",
"beneficiaryName": "ACME Corporation Ltd",
"periodStart": "2024-01-01",
"periodEnd": "2024-12-31",
"emissionsTco2e": 1240.5,
"offsetsTco2e": 1240.5,
"issuedAt": "2025-01-20T10:00:00Z",
"signatureValid": true
}
Certificate type codes
| Code | Description |
|---|---|
ghg_inventory |
GHG Inventory Certificate |
carbon_neutral |
Carbon Neutral Certificate |
net_zero |
Net-Zero Aligned Certificate |
offset_retirement |
Offset Retirement Certificate |
custom |
Custom named certificate |