---
title: "Institutions"
description: "Institutions in Digiploma: higher education institutions identified by MEC code, how to create one and how its supporting documents are signed."
canonical: "https://docs.lacunasoftware.com/en-us/articles/digiploma/api/institutes"
locale: "en"
product: "Digiploma"
last_updated: "2026-10-11"
---

# Institutions

An **institution** (*instituição*) is a higher education institution (IES) registered in the organization, identified by its MEC code. The
institutions are what the [lists of annulled diplomas](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/cancellation-lists) and the [inspection files](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/inspection-files) are produced
for, and each one says how those documents, called **supporting documents** (*documentos auxiliares*), are signed.

## Create an institution

`POST /api/institutes` requires the **Administrador** or **Gerente** role:

```json
{
  "type": "IssuerRegistry",
  "registryData": {
    "nome": "Universidade Exemplo",
    "codigoMEC": 1234,
    "cnpj": "12345678000195",
    "endereco": { … },
    "credenciamento": { … },
    "mantenedora": { … }
  },
  "supportingDocSignatureMode": "Automatic",
  "uploadedCertificate": { "uploadId": "7e2a…", "password": "…" }
}
```

| Field | Description |
|---|---|
| `type` | Required. `Issuer` (Emissora), `Registry` (Registradora) or `IssuerRegistry` (Emissora e Registradora). Only institutions that register diplomas have lists of annulled diplomas. |
| `issuerData` | For `Issuer`: the institution's data, as in `iesEmissora` (name, MEC code, CNPJ, address, accreditation acts and the maintaining entity). |
| `registryData` | For `Registry` and `IssuerRegistry`: the institution's data, as in `iesRegistradora`. When omitted, the registrar data saved in the organization's **Configurações** is used. |
| `supportingDocSignatureMode` | Required. How the supporting documents are signed: `Automatic` or `Manual`. |
| `uploadedCertificate` | For `Automatic`: the institution's e-CNPJ certificate, ICP-Brasil, as a PKCS#12 file (`.pfx`) [uploaded](https://docs.lacunasoftware.com/en-us/articles/digiploma/api#uploads) with `contentType` `application/x-pkcs12`, and its password. Digiploma signs the documents with it (`CertificateIsInvalid` if it is not valid). The uploaded file is deleted afterwards. |
| `supportingDocSigner` | For `Manual`: one signature rule, with `isCompany: true` and `requiredSignatures` 1, with the person who signs the documents in Lacuna Signer with the institution's e-CNPJ. See [Signature flows](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/templates-and-flows#rules-of-each-stage). |

The MEC code must be unique in the instance (`InstituteCodeAlreadyExists`). The response has no body: to get the new institution's id,
search it by its MEC code with `GET /api/institutes?Q={code}`. For a registering institution, the first list of annulled diplomas is
generated right away.

## Other operations

| Operation | Description |
|---|---|
| `GET /api/institutes` | A page of the organization's institutions, sorted by MEC code. `Q` matches the MEC code or the name. |
| `GET /api/institutes/{id}` | An institution, with its data, its signing mode and certificate or signer, the sequence number of its latest list of annulled diplomas and the date of the next one, and its webhook settings. |
| `PUT /api/institutes/{id}` | Changes the institution's `type` and data (`issuerData` or `registryData`, as for creation). The signing mode and the certificate are changed in the web application; the webhook, with the operation below. |
| `POST /api/institutes/{id}/integrations` | Configures the institution's webhook (see below). |
| `GET /api/institutes/{id}/events` | The institution's events, newest first: creation and changes, and the generation of its lists and inspection files, each with `type`, `date` and `details`. |

## Institution webhook

The events of the lists of annulled diplomas and of the inspection files go to the institution's webhook:

```json
{
  "shouldUseSubscriptionWebhookSettings": false,
  "webhook": { "enabled": true, "url": "https://example.edu.br/digiploma/webhooks", "authType": "Bearer", "token": "…" }
}
```

With `shouldUseSubscriptionWebhookSettings` `true`, they go to the organization's webhook instead. With neither, they are not sent. See
[Webhooks](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/webhooks#configure-the-webhook).