Skip to main content

​
Integration Guide

This guide is for developers integrating an existing academic system — an ERP, Student Information System (SIS), or LMS — with the DokStamp API. It covers the full integration lifecycle: initial setup, ongoing entity sync, deletion rules, and the audit trail.

Syncing Academic Structure

How to sync courses, modules, cohorts, and students from your system to DokStamp.

Deletion Rules

What can and cannot be deleted once certificates have been issued.

Audit Log

Every change is logged — who changed what, when, and from where.

Entity Registration Order

The dependency graph all integrations must follow.

​
Typical integration scenario

Third-party system (ERP/SIS)          DokStamp API
        │                                   │
        │  New course created               │
        │ ────────────────────►│ POST /courses
        │                                   │
        │  Module added to course           │
        │ ────────────────────►│ POST /modules
        │                                   │  POST /courses/{id}/attach/modules
        │                                   │
        │  New cohort (graduating class)    │
        │ ────────────────────►│ POST /cohorts
        │                                   │
        │  Student becomes eligible         │
        │ ────────────────────►│ GET /students?where[email]=...
        │                                   │  POST /students (if not found)
        │                                   │  POST /enrollments
        │                                   │
        │  Certificate issuance triggered   │
        │ ────────────────────►│ POST /files
        │                                   │  POST /certificates

​
Before you start

Institution setup is required first. The institution is the root entity — all courses, modules, and certificates depend on it. It can be created via:
  • The DokStamp dashboard (manual, one-time setup)
  • The API: POST /institutions
Once the institution exists, all subsequent entity sync can be done programmatically.

​
Integration modes

​
Synchronous (real-time)

Your system calls DokStamp’s API directly when an entity changes. Simple to implement, works well for low-volume scenarios. 
User action in ERP → API call to DokStamp → Response handled immediately

​
Asynchronous (queue-based)

Your system enqueues a job whenever an entity changes. A background worker processes the queue and calls DokStamp’s API. Recommended for high-volume integrations or when DokStamp availability should not affect your system’s performance. 
User action in ERP → Job enqueued → Worker calls DokStamp API → Retry on failure
Retry strategy: Use exponential backoff. Retry on HTTP 429 (rate limit) and 5xx (server errors). Do not retry on 4xx (client errors — these indicate a data or auth problem that needs investigation).

​
Idempotency: search before create

DokStamp does not expose idempotency keys. The recommended pattern is to look up an entity before creating it to avoid duplicates. 
// Before creating a student, check if they already exist
const existing = await api.get('/students', {
  params: { 'where[email]': student.email }
});

const studentUuid = existing.data.length > 0
  ? existing.data[0].uuid
  : (await api.post('/students', student)).data.uuid;
Apply the same pattern for courses (by code), cohorts (by code), and modules (by code + institution_uuid).