---
title: "Register diplomas (registrar only)"
description: "How registrar institutions handle registration requests in Digiploma: how requests arrive, the diploma XML and signatures collected in Lacuna Signer."
canonical: "https://docs.lacunasoftware.com/en-us/articles/digiploma/api/registrations"
locale: "en"
product: "Digiploma"
last_updated: "2026-10-12"
---

# Register diplomas (registrar only)

This page is for institutions that **register** diplomas issued by other institutions. The organization must be of type **Registradora**
(registrar) or **Emissora e Registradora**.

A **registration request** (*requisição de registro*) is the registrar's side of a diploma. It starts from the **academic documentation XML**
signed by the issuer. The registrar reviews it, fills in the registration data, and Digiploma generates the **diploma XML**, collects the
registrar's signatures in Lacuna Signer, and makes the signed file available to the issuer.

## How requests arrive

There is no operation to create a single request. Requests are created:

* from a [batch](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/batches) of signed academic documentation XML files, sent to you by the issuers;
* automatically, when an issuer in the same Digiploma instance that has a partnership with your organization sends an emission
  (`registrationType` `Subscription`; see [Issue only](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/emissions#how-the-registrar-receives-the-emission));
* automatically, when an issuer on another Digiploma instance integrated with yours sends an emission (`Integration`).

## Statuses

| `status` | Meaning |
|---|---|
| `CreatedAwaitingAcceptance` | Received; waiting to be accepted, when the instance requires acceptance. |
| `Accepted` | Accepted for review. |
| `Created` | Received; waiting for review. |
| `Approved` | The review found the data consistent with the supporting documents. |
| `Rejected` | The review found problems. The request ends here. |
| `Registered` | The registration data was sent; the diploma XML is waiting for signatures. |
| `Signed` | The diploma XML is signed. |
| `SentToIssuer` | The signed diploma XML was delivered to the issuer's instance (`Integration`). |
| `Canceled` | Canceled. |

```text
Created ───────────────────────────────┬─► Approved ─► Registered ─► Signed ─► SentToIssuer
CreatedAwaitingAcceptance ─► Accepted ─┘
```

A request is rejected from `Created`, `CreatedAwaitingAcceptance` or `Accepted`, and canceled from any status.

## Review a request

`GET /api/registrations/{id}/info` returns what you need to check that the student's data matches the supporting documents
(*documentação comprobatória*): the diploma data (`dadosDiploma`), the academic documentation (the student's private data, the statement
of responsibility and the list of supporting documents) and `files`, one entry per supporting document, each with a `ticketUrl` to download
its PDF. The issuer's designation act (*ato de designação*) is also listed, and can be downloaded with
`GET /api/registrations/{id}/responsibility-term-ticket`. `GET /api/registrations/{id}/academic-documentation-ticket` downloads the
academic documentation XML as received.

Then conclude the review:

| Operation | Allowed from | Body | Result |
|---|---|---|---|
| `POST /api/registrations/{id}/acceptance` | `CreatedAwaitingAcceptance` | `{reason}` (optional) | `Accepted`. Fails with `RegistrationDoesNotRequireAcceptance` when the instance does not require acceptance. |
| `POST /api/registrations/{id}/approval` | `Created`, `Accepted` | `{reason}` (optional) | `Approved` (`RegistrationCannotBeApproved` otherwise). |
| `POST /api/registrations/{id}/rejection` | `Created`, `CreatedAwaitingAcceptance`, `Accepted` | `{reason}` | `Rejected` (`RegistrationCannotBeRejected` otherwise). After approval, cancel the request instead. |

`reason` takes up to 1000 characters.

## Register the diploma

`POST /api/registrations/{id}/registration-data` registers an `Approved` request (`RegistrationCannotBeRegistered` otherwise):

```json
{
  "dadosRegistro": {
    "livroRegistro": {
      "livroRegistro": "12",
      "numeroRegistro": "3456",
      "dataColacaoGrau": "2026-07-10",
      "dataExpedicaoDiploma": "2026-08-01",
      "dataRegistroDiploma": "2026-08-15",
      "responsavelRegistro": { "nome": "Ana Ribeiro", "cpf": "12345678909" }
    }
  },
  "documentFlowId": "a71c…"
}
```

| Field | Description |
|---|---|
| `dadosRegistro.livroRegistro` | The registration book data: the book (`livroRegistro`); either the registration number (`numeroRegistro`) or the page and sequence numbers (`numeroFolhaDoDiploma` and `numeroSequenciaDoDiploma`); the optional process number (`processoDoDiploma`); the graduation, issue and registration dates; and the person responsible for the registration (`responsavelRegistro`). |
| `dadosRegistro.iesRegistradora` | The registrar's data. When omitted, it is taken from the organization's settings. |
| `dadosRegistro.assinantes` | Optional. The registrar's representatives who sign `DadosRegistro`. When filled, the signers of the registration stage must be exactly these people. |
| `dadosRegistro.informacoesProcessoJudicial` | Required for a diploma issued by judicial decision. |
| `documentFlowId` / `documentFlow` | The signers: a saved flow of type `Registration`, or `registrationFlow` (the registrar's representatives, e-CPF) and `storageFlow` (one e-CNPJ signature of the registrar). Required only for requests that did not come from a batch, which already has its flow. |
| `newFolderName` / `signerFolderId` | The Signer folder for the document, when the request did not come from a batch. |

Digiploma computes the validation code (`RegistrationInvalidVerificationCode` if another request already has it), generates the diploma
XML, sends it to Signer and sets the request to `Registered`. Signer collects the registration signatures on `DadosRegistro` and then the
archiving signature on the whole file. When the document is concluded, the request becomes `Signed`.

## Deliver the diploma XML

`GET /api/registrations/{id}/xml-ticket` returns a [ticket](https://docs.lacunasoftware.com/en-us/articles/digiploma/api#downloads-and-tickets) to download the signed diploma XML
(`RegistrationNotSigned` until it is signed). For a request that came from a batch, send this file to the issuer, which completes its
emission with it. For `Subscription` and `Integration` requests, Digiploma delivers it automatically.

## Cancel a request

`POST /api/registrations/{id}/cancellation` cancels a request in any status except `Canceled`:

```json
{ "cancellationReason": "ErroDeFato", "reason": "Número de registro duplicado" }
```

If the diploma XML is already signed, this annuls the registration, and `cancellationReason` is required (`CancellationReasonRequired`),
with the same values as for [diplomas](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/degrees#annul-suspend-or-restore-a-diploma). A document still waiting for signatures is deleted
from Signer. For `Subscription` and `Integration` requests, the issuer's emission is canceled too, or, if the diploma already exists there,
the diploma is annulled with the same reason.

## Read and search

* `GET /api/registrations/{id}` returns the request; `GET /api/registrations/{id}/history` returns its status changes, newest first.
* `GET /api/registrations` returns a page of requests. Besides the [paging parameters](https://docs.lacunasoftware.com/en-us/articles/digiploma/api#pagination), it filters by `Status`,
  `BatchId`, creation date (`StartDateUtc` inclusive, `EndDateUtc` exclusive), `IsSigned=true` and `Q` (student's CPF, name or social
  name, or course). Results are sorted by update date.

## Webhooks

| Event | When |
|---|---|
| `RegistrationCreated` | The request was received. |
| `RegistrationAccepted`, `RegistrationApproved`, `RegistrationRejected` | The request was accepted, approved or rejected. |
| `RegistrationRegistered` | The registration data was sent. |
| `RegistrationSigned` | The diploma XML was signed. |
| `RegistrationCanceled` | The request was canceled. |

See [Webhooks](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/webhooks) for the payloads.

## Operation reference

| Operation | Description |
|---|---|
| `GET /api/registrations` | List registration requests |
| `GET /api/registrations/{id}` | Get a request |
| `GET /api/registrations/{id}/info` | Get the data for the review |
| `GET /api/registrations/{id}/history` | Get the status history |
| `POST /api/registrations/{id}/acceptance` | Accept a request |
| `POST /api/registrations/{id}/approval` | Approve a request |
| `POST /api/registrations/{id}/rejection` | Reject a request |
| `POST /api/registrations/{id}/registration-data` | Register the diploma |
| `POST /api/registrations/{id}/cancellation` | Cancel a request |
| `GET /api/registrations/{id}/xml-ticket` | Download the signed diploma XML |
| `GET /api/registrations/{id}/academic-documentation-ticket` | Download the academic documentation XML |
| `GET /api/registrations/{id}/responsibility-term-ticket` | Download the issuer's designation act |