Institutions

An institution is the issuing body — the university, school, or organization that grants certificates. It is the top-level entity in the academic hierarchy and must be created before courses, modules, or certificates.

The institution object

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Federal University of Technology",
  "legal_name": "Federal University of Technology Foundation",
  "tax_id": "00.000.000/0001-00",
  "country": "Brazil",
  "website": "https://fut.edu.br",
  "linkedin_organization": "federal-university-of-technology",
  "status": "active",
  "is_badges_enabled": false,
  "badge_image_uuid": null,
  "created_at": "2024-01-15T10:00:00.000000Z",
  "updated_at": "2024-01-15T10:00:00.000000Z"
}

Field	Type	Description
`uuid`	string	Unique identifier — use this in all related resource requests
`name`	string	Display name
`legal_name`	string	Official legal entity name
`tax_id`	string	Tax registration number (e.g., CNPJ)
`country`	string	Country of registration
`website`	string	Institution website
`linkedin_organization`	string	LinkedIn organization slug
`status`	enum	`active`, `inactive`, `suspended`
`is_badges_enabled`	boolean	Whether Open Badges issuance is enabled
`badge_image_uuid`	string\|null	UUID of the badge image file (required if badges enabled)

List institutions

GET /institutions

Query parameters: See Filtering, Sorting & Pagination.

curl https://api.dokstamp.com/institutions \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  -H "X-Tenant: {TENANT}"

Create an institution

POST /institutions

Parameter	Type	Required	Description
`name`	string	Yes	Display name (max 255 chars)
`country`	string	Yes	Country of registration
`legal_name`	string	No	Official legal entity name
`tax_id`	string	No	Tax registration number
`website`	string	No	Institution website URL
`linkedin_organization`	string	No	LinkedIn organization identifier
`status`	enum	No	`active` (default), `inactive`, `suspended`
`is_badges_enabled`	boolean	No	Enable Open Badges issuance
`badge_image_uuid`	string	No*	Required if `is_badges_enabled` is `true`

curl -X POST https://api.dokstamp.com/institutions \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: {TENANT}" \
  -d '{
    "name": "Federal University of Technology",
    "legal_name": "Federal University of Technology Foundation",
    "tax_id": "00.000.000/0001-00",
    "country": "Brazil",
    "website": "https://fut.edu.br",
    "status": "active"
  }'

Response 201:

{
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Federal University of Technology",
    ...
  }
}

Get an institution

GET /institutions/{uuid}

curl https://api.dokstamp.com/institutions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  -H "X-Tenant: {TENANT}"

Update an institution

PATCH /institutions/{uuid}

Send only the fields you want to change. PATCH performs a partial update.

PUT /institutions/{uuid}

PUT replaces the entire resource — all fields must be provided.

Delete an institution

DELETE /institutions/{uuid}

Returns 204 No Content on success. This is a soft delete — the record is not permanently removed.

Deleting an institution does not delete the courses, modules, or certificates under it. Those records will remain but will reference a deleted institution.

Bulk delete

DELETE /institutions/batch/destroy

Parameter	Type	Required	Description
`uuids`	array	Yes	Array of institution UUIDs to delete

{ "uuids": ["uuid-1", "uuid-2", "uuid-3"] }

Get badge issuer configuration

GET /institutions/{uuid}/badges/issuers

Returns the Open Badges issuer profile for the institution. Used when generating badge assertions.

Getting Started

Core Concepts

Authentication

Institutions

Organizations

Courses

Modules

Students

Enrollments

Certificates

Certificate Templates

Files

Guides

Integration Guide

Institutions

Institutions

The institution object

List institutions

Create an institution

Get an institution

Update an institution

Delete an institution

Bulk delete

Get badge issuer configuration

​Institutions

​The institution object

​List institutions

​Create an institution

​Get an institution

​Update an institution

​Delete an institution

​Bulk delete

​Get badge issuer configuration

Institutions

The institution object

List institutions

Create an institution

Get an institution

Update an institution

Delete an institution

Bulk delete

Get badge issuer configuration