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

# Institutions

> Create and manage the institutions that issue certificates.

# 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

```json theme={null}
{
  "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

```http theme={null}
GET /institutions
```

**Query parameters:** See [Filtering, Sorting & Pagination](/en/core-concepts/filtering-sorting-pagination).

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.dokstamp.com/institutions \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Accept: application/json" \
    -H "X-Tenant: {TENANT}"
  ```
</CodeGroup>

***

## Create an institution

```http theme={null}
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`   |

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

**Response `201`:**

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

***

## Get an institution

```http theme={null}
GET /institutions/{uuid}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.dokstamp.com/institutions/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Accept: application/json" \
    -H "X-Tenant: {TENANT}"
  ```
</CodeGroup>

***

## Update an institution

```http theme={null}
PATCH /institutions/{uuid}
```

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

```http theme={null}
PUT /institutions/{uuid}
```

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

***

## Delete an institution

```http theme={null}
DELETE /institutions/{uuid}
```

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

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

***

## Bulk delete

```http theme={null}
DELETE /institutions/batch/destroy
```

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

```json theme={null}
{ "uuids": ["uuid-1", "uuid-2", "uuid-3"] }
```

***

## Get badge issuer configuration

```http theme={null}
GET /institutions/{uuid}/badges/issuers
```

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