Skip to main content

​
Certificates

A certificate is the digital credential that binds a student to a course, issued by an institution. It includes a signed PDF file, a public verification URL, and an immutable snapshot of the student’s identity at issuance time.

​
The certificate object

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "issued",
  "issued_at": "2024-12-01T00:00:00.000000Z",
  "revoked_at": null,
  "revocation_reason": null,
  "public_verification_url": "https://verificar.dokstamp.eu/a1b2c3d4",
  "blockchain_tx_hash": null,
  "blockchain_tx_url": null,
  "institution": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Federal University of Technology"
  },
  "course": {
    "uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "name": "Bachelor of Computer Science"
  },
  "student": {
    "uuid": "f6a7b8c9-d0e1-2345-fghi-456789012345",
    "name": "Maria Fernanda Silva"
  },
  "cohort": null,
  "enrollment": null,
  "template": null,
  "files": [
    {
      "type": "certificate",
      "uuid": "h8i9j0k1-l2m3-4567-nopq-678901234567"
    }
  ]
}
FieldTypeDescription
uuidstringUnique identifier
statusenumdraft, issued, revoked, expired
issued_atdatetimeOfficial issuance date
revoked_atdatetime|nullRevocation timestamp
revocation_reasonstring|nullReason for revocation
public_verification_urlstring|nullShareable URL for third-party verification
blockchain_tx_hashstring|nullBlockchain transaction hash (if anchored)
filesarrayAttached PDF files

​
List certificates

GET /certificates

# List all issued certificates for a course
curl "https://api.dokstamp.com/certificates?where[status]=issued&where[course_uuid]=c3d4e5f6-a7b8-9012-cdef-123456789012&sort[column]=issued_at&sort[order]=desc" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  -H "X-Tenant: {TENANT}"

​
Issue a certificate

POST /certificates
ParameterTypeRequiredDescription
institution_uuidstringYesIssuing institution UUID
course_uuidstringYesCourse UUID
student_uuidstringYesRecipient student UUID
file_uuidstringYesUUID of the uploaded PDF file (must be unused)
finishbooleanNotrue to immediately issue the certificate (see below). Defaults to false (creates as draft)
cohort_uuidstringNoCohort UUID
enrollment_uuidstringNoEnrollment UUID
template_uuidstringNoCertificate template UUID
public_verification_urlstringNoCustom verification URL (auto-generated if omitted)
finish: true triggers the full issuance pipeline in a single call: sets status to issued, cryptographically signs all files, generates the academic transcript PDF, and sends the certificate notification to the student. Without it, the certificate is saved as draft.
curl -X POST https://api.dokstamp.com/certificates \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: {TENANT}" \
  -d '{
    "institution_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "course_uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "student_uuid": "f6a7b8c9-d0e1-2345-fghi-456789012345",
    "file_uuid": "h8i9j0k1-l2m3-4567-nopq-678901234567",
    "cohort_uuid": "e5f6a7b8-c9d0-1234-efgh-345678901234",
    "enrollment_uuid": "g7h8i9j0-k1l2-3456-mnop-567890123456",
    "finish": true
  }'
Response 201: 
{
  "data": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "issued",
    "issued_at": "2024-12-01T00:00:00.000000Z",
    "public_verification_url": "https://verificar.dokstamp.eu/a1b2c3d4",
    "institution": { "name": "Federal University of Technology" },
    "course": { "name": "Bachelor of Computer Science" },
    "student": { "name": "Maria Fernanda Silva" }
  }
}
A file UUID can only be used once. If you attempt to create a second certificate with the same file_uuid, you will receive a 422 error. Upload a new file for each certificate.

​
Get a certificate

GET /certificates/{uuid}

GET /certificates/{uuid}?includes[student]=1&includes[course]=1&includes[institution]=1&includes[files]=1

​
Update a certificate

PATCH /certificates/{uuid}
PUT   /certificates/{uuid}
You can update certificates in draft status. Updating an issued certificate is restricted.

​
Delete a certificate

DELETE /certificates/{uuid}
DELETE /certificates/batch/destroy

​
Badge assertion (Open Badges)

GET /certificates/{uuid}/badges/assertions
Returns the W3C Open Badges 2.0 assertion for the certificate. This endpoint is used by badge verification services and badge backpacks (e.g., Badgr, Credly).