Skip to main content

​
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"
}
FieldTypeDescription
uuidstringUnique identifier — use this in all related resource requests
namestringDisplay name
legal_namestringOfficial legal entity name
tax_idstringTax registration number (e.g., CNPJ)
countrystringCountry of registration
websitestringInstitution website
linkedin_organizationstringLinkedIn organization slug
statusenumactive, inactive, suspended
is_badges_enabledbooleanWhether Open Badges issuance is enabled
badge_image_uuidstring|nullUUID 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
ParameterTypeRequiredDescription
namestringYesDisplay name (max 255 chars)
countrystringYesCountry of registration
legal_namestringNoOfficial legal entity name
tax_idstringNoTax registration number
websitestringNoInstitution website URL
linkedin_organizationstringNoLinkedIn organization identifier
statusenumNoactive (default), inactive, suspended
is_badges_enabledbooleanNoEnable Open Badges issuance
badge_image_uuidstringNo*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
ParameterTypeRequiredDescription
uuidsarrayYesArray 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.