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

# Entity Registration Order

> The correct sequence to register entities before issuing certificates. Skipping steps causes validation errors.

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

<Info>
  This is the most common source of `422` validation errors for new integrations. Bookmark this page.
</Info>

***

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

<Steps>
  <Step title="Authenticate">
    **Endpoint:** `POST /auth/login`

    Obtain your `access_token` and `refresh_token`. All subsequent requests require the Bearer token in the `Authorization` header.

    → [Authentication reference](/en/api-reference/authentication/login)
  </Step>

  <Step title="Create an Institution">
    **Endpoint:** `POST /institutions`

    The institution is the issuing body. It is required for courses, modules, certificate templates, and certificates. Create this first.

    → [Institutions reference](/en/api-reference/institutions)
  </Step>

  <Step title="Create an Organization (optional)">
    **Endpoint:** `POST /organizations`

    Organizations are sub-units of an institution (faculties, departments, campuses). Courses can be linked to an organization, but it is not required.

    → [Organizations reference](/en/api-reference/organizations)
  </Step>

  <Step title="Create Module(s)">
    **Endpoint:** `POST /modules`

    Modules are the building blocks of courses — individual subjects or disciplines. Create all modules you need before creating the course.

    → [Modules reference](/en/api-reference/modules)
  </Step>

  <Step title="Create a Course">
    **Endpoint:** `POST /courses`

    A course defines the program of study. Requires an `institution_uuid`. Optionally linked to an `organization_uuid`.

    → [Courses reference](/en/api-reference/courses/overview)
  </Step>

  <Step title="Attach Modules to the Course">
    **Endpoint:** `POST /courses/{course_uuid}/attach/modules`

    Modules 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](/en/api-reference/courses/modules)
  </Step>

  <Step title="Create a Cohort (optional)">
    **Endpoint:** `POST /cohorts`

    A 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](/en/api-reference/courses/cohorts)
  </Step>

  <Step title="Upload the Certificate PDF">
    **Endpoint:** `POST /files`

    Upload 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](/en/api-reference/files)
  </Step>

  <Step title="Create a Certificate Template (optional)">
    **Endpoint:** `POST /certificate-templates`

    Templates 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](/en/api-reference/certificate-templates)
  </Step>

  <Step title="Create a Student">
    **Endpoint:** `POST /students`

    Students are independent of institutions and courses — they exist at the tenant level. Create (or look up) the student before issuing a certificate.

    → [Students reference](/en/api-reference/students/overview)
  </Step>

  <Step title="Create an Enrollment (optional)">
    **Endpoint:** `POST /enrollments`

    An 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](/en/api-reference/enrollments)
  </Step>

  <Step title="Issue the Certificate">
    **Endpoint:** `POST /certificates`

    Combine all the entities above into a certificate. The minimum required fields are `institution_uuid`, `course_uuid`, `student_uuid`, and `file_uuid`.

    → [Certificates reference](/en/api-reference/certificates/overview)
  </Step>
</Steps>

***

## At a glance

| Step | Endpoint                            | Required? | Depends on       |
| ---- | ----------------------------------- | --------- | ---------------- |
| 1    | `POST /auth/login`                  | Yes       | —                |
| 2    | `POST /institutions`                | Yes       | Tenant           |
| 3    | `POST /organizations`               | No        | Institution      |
| 4    | `POST /modules`                     | No\*      | Institution      |
| 5    | `POST /courses`                     | Yes       | Institution      |
| 6    | `POST /courses/{id}/attach/modules` | No\*      | Course + Modules |
| 7    | `POST /cohorts`                     | No        | Course           |
| 8    | `POST /files`                       | Yes       | —                |
| 9    | `POST /certificate-templates`       | No        | Institution      |
| 10   | `POST /students`                    | Yes       | —                |
| 11   | `POST /enrollments`                 | No        | Student + Course |
| 12   | `POST /certificates`                | Yes       | All of the above |

<sub>\*Optional unless you need module-level academic transcripts.</sub>

***

## 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[user][email]=student@email.com` to look up existing students before creating new ones.