Skip to main content

​
Entity Registration Order

Certificates in DokStamp bind together multiple entities — institution, course, student, file. Each entity depends on others already existing. This page shows the exact order you must follow and which steps are optional.
This is the most common source of 422 validation errors for new integrations. Bookmark this page.

​
Dependency map

Tenant (root — configured for you)
└── Institution
    ├── Organization (optional)
    ├── Module(s)
    └── Course
        ├── Course ← Modules (attach step)
        ├── Module Groups (optional)
        └── Cohort (optional)

Student (independent of institution)
└── Enrollment → Course + Cohort (optional)

File (uploaded independently)

Certificate Template → Institution (optional)

Certificate
  ├── institution_uuid  ← from Institution
  ├── course_uuid       ← from Course
  ├── student_uuid      ← from Student
  ├── file_uuid         ← from File (unused)
  ├── cohort_uuid       ← from Cohort (optional)
  ├── enrollment_uuid   ← from Enrollment (optional)
  └── template_uuid     ← from Certificate Template (optional)

​
Step-by-step order

1

Authenticate

Endpoint: POST /auth/loginObtain your access_token and refresh_token. All subsequent requests require the Bearer token in the Authorization header.→ Authentication reference
2

Create an Institution

Endpoint: POST /institutionsThe institution is the issuing body. It is required for courses, modules, certificate templates, and certificates. Create this first.→ Institutions reference
3

Create an Organization (optional)

Endpoint: POST /organizationsOrganizations are sub-units of an institution (faculties, departments, campuses). Courses can be linked to an organization, but it is not required.→ Organizations reference
4

Create Module(s)

Endpoint: POST /modulesModules are the building blocks of courses — individual subjects or disciplines. Create all modules you need before creating the course.→ Modules reference
5

Create a Course

Endpoint: POST /coursesA course defines the program of study. Requires an institution_uuid. Optionally linked to an organization_uuid.→ Courses reference
6

Attach Modules to the Course

Endpoint: POST /courses/{course_uuid}/attach/modulesModules are not automatically linked to courses. You must explicitly attach them. You can also assign modules to module groups and define ordering.→ Course Modules reference
7

Create a Cohort (optional)

Endpoint: POST /cohortsA cohort is a specific intake or class (e.g., “Class of 2024 — Evening”). Cohorts are linked to a course. Use cohorts when you issue certificates for distinct graduating classes.→ Cohorts reference
8

Upload the Certificate PDF

Endpoint: POST /filesUpload the PDF file of the certificate. The response returns a uuid — this is your file_uuid. A file can only be attached to one certificate; it is marked as used on attachment.→ Files reference
9

Create a Certificate Template (optional)

Endpoint: POST /certificate-templatesTemplates define the visual design of certificates (including Canva configuration). They are reusable across many certificates. Skip if you are providing pre-rendered PDFs.→ Certificate Templates reference
10

Create a Student

Endpoint: POST /studentsStudents are independent of institutions and courses — they exist at the tenant level. Create (or look up) the student before issuing a certificate.→ Students reference
11

Create an Enrollment (optional)

Endpoint: POST /enrollmentsAn enrollment links a student to a course (and optionally a cohort). It tracks academic progression, grade, and completion status. Pass the enrollment_uuid on the certificate for full traceability.→ Enrollments reference
12

Issue the Certificate

Endpoint: POST /certificatesCombine all the entities above into a certificate. The minimum required fields are institution_uuid, course_uuid, student_uuid, and file_uuid.→ Certificates reference

​
At a glance

StepEndpointRequired?Depends on
1POST /auth/loginYes—
2POST /institutionsYesTenant
3POST /organizationsNoInstitution
4POST /modulesNo*Institution
5POST /coursesYesInstitution
6POST /courses/{id}/attach/modulesNo*Course + Modules
7POST /cohortsNoCourse
8POST /filesYes—
9POST /certificate-templatesNoInstitution
10POST /studentsYes—
11POST /enrollmentsNoStudent + Course
12POST /certificatesYesAll of the above
*Optional unless you need module-level academic transcripts.

​
Reusing existing entities

In production, you will not repeat every step for every certificate. Most entities are registered once and reused:
  • Institution, Organization, Course, Modules — registered once per academic catalog update.
  • Students — registered once per person (search before creating to avoid duplicates).
  • Cohorts — registered once per graduating class.
  • Files — each certificate needs its own unique file upload.
  • Certificates — one per student per credential event.
Use GET /students?where[email]=student@email.com to look up existing students before creating new ones.