---
title: "Lists of annulled diplomas"
description: "Digiploma lists of annulled diplomas: the signed ListaDiplomasAnulados XML a registrar publishes for each institution, and its public file URL."
canonical: "https://docs.lacunasoftware.com/en-us/articles/digiploma/api/cancellation-lists"
locale: "en"
product: "Digiploma"
last_updated: "2026-10-12"
---

# Lists of annulled diplomas

A registrar must publish the **list of annulled diplomas** (*lista de diplomas anulados*): a signed XML file, in the MEC layout
`ListaDiplomasAnulados`, with the diplomas whose registration it annulled. Digiploma generates, signs and publishes this list for each
[institution](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/institutes) that registers diplomas (of type **Registradora** or **Emissora e Registradora**). Issuer-only institutions
have no list.

## The public file

The latest signed list of an institution is published, with no authentication, at the root of the instance, named after the institution's
MEC code:

```text
https://www.digiploma.com.br/{iesCode}.xml
```

## What the list contains

The list is cumulative: each new list includes every annulment, not only the ones since the previous list. For each diploma annulled by the
institution, with both XML files signed, it has the validation code, the date of the annulment, the reason (`cancellationReason`, as in
*Erro de Fato*) and the note (`reason`). Signed registration requests that were canceled are included too. Temporarily canceled diplomas are
not.

Each list has a sequence number, and the latest date for the next list (`DataMaximaProximaAtualizacao`), 180 days after it is generated.

## When lists are generated

* When a registering institution is created, or an institution becomes a registrar.
* Periodically: a monthly check generates the next list when the latest date of the current one is less than 120 days away, that is, about
  two months after the previous list. On premises, this window is configurable.

Annulling a diploma does not generate a new list immediately: it appears in the next one.

## Signing and statuses

The institution's settings decide how the list is signed:

* **Automatic**: Digiploma signs the list itself, with the institution's e-CNPJ certificate (XAdES, ICP-Brasil AD-RT policy).
* **Manual**: Digiploma sends the list to Lacuna Signer, in the institution's folder, to be signed by the institution's signer.

| `status` | Meaning |
|---|---|
| `Created` | Generated and waiting for the signature in Signer (manual signing). |
| `Signed` | Signed. The latest signed list is the one published. |

## Operations

All operations require the API key, with the `ViewCancellationList` permission.

| Operation | Description |
|---|---|
| `GET /api/cancellation-lists/institute/{instituteId}` | A page of the institution's lists. |
| `GET /api/cancellation-lists/ies-codes/{iesCode}` | The same, by the institution's MEC code. |
| `GET /api/cancellation-lists/institute/{instituteId}/latest` | The latest signed list of the institution. |
| `GET /api/cancellation-lists/institute/{instituteId}/latest/xml`, `…/latest/xml-b64` | Download the latest signed list, as a file or in Base64. |
| `GET /api/cancellation-lists/{id}` | A list. |
| `GET /api/cancellation-lists/{id}/xml`, `…/xml-b64`, `…/xml-ticket` | Download a list, as a file, in Base64 or with a [ticket](https://docs.lacunasoftware.com/en-us/articles/digiploma/api#downloads-and-tickets). |

The list operations take the [paging parameters](https://docs.lacunasoftware.com/en-us/articles/digiploma/api#pagination); `Q` matches the sequence number exactly, and the results are sorted by
sequence number. The `latest` operations need the institution to have a signed list already.

A list (`CancellationListModel`) has `id`, `iesCode`, `iesName`, `sequenceNumber`, `status`, `version`, `creationDate`,
`maximumNextUpdateDate` and, for manual signing, `signerDocumentId` and `signerDocumentUrl`.

## Webhooks

| Event | When |
|---|---|
| `CancellationListCreated` | A list was generated and sent to Signer (manual signing). |
| `CancellationListSigned` | A list was signed. |

They are sent to the institution's webhook settings, or to the organization's. The `CancellationListGenerated` event listed in the API
reference is not sent. See [Webhooks](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/webhooks).