> For the complete documentation index, see [llms.txt](https://docs.griaule.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.griaule.com/gbs/en/gbds-integration/gbds-5-notification-flows.md).

# GBDS 5 Notification Flows

When GBDS performs enrollment, update, deletion, and exception-handling operations, notifications are sent to designated endpoints to report their results. The entity responsible for this flow is called the Notifier.

This document describes the notification flows for enrollment, update, deletion, and exception-handling operations.

{% hint style="info" %}
For more information about notification flows during sequence control and quality control, see the documentation on [sequence control and quality control](https://docs.griaule.com/gbs/en/gbds-integration/qualitycontrol.md).
{% endhint %}

{% hint style="info" %}
All notifications sent by the Notifier are HTTP POST requests to a configured endpoint (`http://<endereço>:<porta>`), containing a JSON object. The JSON model for each notification is shown below.
{% endhint %}

{% hint style="warning" %}
The endpoint that receives the notification **must be implemented individually** for each system.
{% endhint %}

### Transaction Accepted

All asynchronous transactions received are queued. After processing, a notification is sent to report that the operation has been completed.

The notification message will look like the example below:

```json
{
	"operation": "<operação>",
	"tguid": "<tguid>",
	"status": "ENROLLED"
}
```

{% hint style="info" %}
The possible operations at this step are: `ENROLL` (used for both enrollment and update) and `SEARCH`.
{% endhint %}

The Notifier can return different statuses, depending on the type of transaction being performed. The possible **final** statuses are:

| Operation     | Status                                             |
| ------------- | -------------------------------------------------- |
| Enroll/Update | `ENROLLED`, `FAILED`                               |
| Search        | `MATCH`, `NOT_MATCH`, `FAILED`, `PERSON_NOT_FOUND` |

The status `FAILED` occurs whenever a transaction is aborted or cannot be completed.

The status `PERSON_NOT_FOUND` occurs when a 1:1 search is received, but no reference profile exists for the provided key.

#### Additional fields in the `ENROLL`

operation notification `ENROLL` notification may include additional fields, depending on the transaction context:

| Field                                | When it appears                                                                                                                                                        |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pguid`                              | Whenever a reference pguid is associated with the transaction                                                                                                          |
| `update`                             | Indicates whether the transaction is an update (`true`/`false`)                                                                                                        |
| `trusted`                            | Indicates whether the transaction is a trusted transaction (trusted master record)                                                                                     |
| `treatment`                          | Value `BoB` when the transaction resulted from a "Best of Biometrics"                                                                                                  |
| `exceptionGroupTguid`                | Present when the transaction is associated with an exception group (e.g., a new transaction generated by a group treatment or a transaction rejected during treatment) |
| `originalRefusedTguid`               | Present when the transaction is a resubmission of a previously refused transaction (`REFUSED`)                                                                         |
| `externalIDs` / `relatedExternalIDs` | External transaction IDs and related external IDs (inherited from previous transactions)                                                                               |
| `removedKeys`                        | Keys removed due to inconsistency, with the reason, when applicable                                                                                                    |
| `originalInconsistentKeys`           | Original keys considered inconsistent, when applicable                                                                                                                 |
| `newTransactionGUID`                 | Present in failure/rejection notifications when there is a new replacement transaction                                                                                 |
| `gguid`                              | Present when the notification is associated with an exception group                                                                                                    |

Notification example `ENROLL` with additional fields:

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "ENROLLED",
	"pguid": "<pguid>",
	"update": false,
	"trusted": true,
	"treatment": "BoB",
	"exceptionGroupTguid": "<related-gguid>",
	"externalIDs": [{ "name": "<name>", "key": "<value>" }],
	"relatedExternalIDs": [{ "name": "<name>", "key": "<value>" }]
}
```

### Transaction Sent for Manual Review

When GBDS identifies issues related to sequence control or quality control and the transaction is sent for manual review, a notification will be sent indicating that the enrollment is pending, as in the example below:

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "PENDING"
}
```

{% hint style="info" %}
See the MIR (Manual Image Review) Manual for more details about resolving transactions sent for manual review.
{% endhint %}

After the MIR review, the server processes the examiner's decision and sends the corresponding notifications, as described below.

{% stepper %}
{% step %}

#### Transaction Approved Without Changes

Given this decision, GBDS will keep the original transaction unchanged and continue the enrollment process. The TGUID (transaction Global Unique Identifier) will remain the same for both operations (`QUALITY_ANALYSIS` and `ENROLL`).

The first notification will contain the status `APPROVED` for the operation `QUALITY_ANALYSIS`:

```json
{
	"operation": "QUALITY_ANALYSIS",
	"tguid": "<tguid>",
	"status": "APPROVED"
}
```

The second notification will contain the status `ENROLLED` for the operation `ENROLL`:

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "ENROLLED"
}
```

{% endstep %}

{% step %}

#### Transaction Approved with Changes

Given this decision, GBDS will retain the changes made by the examiner (deleted or edited images) and generate a new TGUID for the enrollment.

The notification flow is similar to that for "Transaction Approved Without Changes", with the addition of the new TGUID. The first notification will contain the status `APPROVED` for the operation `QUALITY_ANALYSIS` and will include the field `newTransactionGUID`, pointing to the new TGUID:

```json
{
	"newTransactionGUID": "<new_tguid>",
	"operation": "QUALITY_ANALYSIS",
	"tguid": "<original_tguid>",
	"status": "APPROVED"
}
```

The second notification will contain the status `ENROLLED` for the operation `ENROLL`:

{% hint style="info" %}
The operation `ENROLL` will be performed for the modified transaction, so the TGUID mentioned will be the new TGUID generated by the operation `QUALITY_ANALYSIS`.
{% endhint %}

```json
{
	"operation": "ENROLL",
	"tguid": "<new_tguid>",
	"status": "ENROLLED"
}
```

{% endstep %}

{% step %}

#### Transaction Rejected

Given this decision, GBDS will not continue the enrollment process and will discard the entire transaction. The TGUID will remain the same.

{% hint style="info" %}
The transaction history will be retained, but the profile will not be inserted into the database as an active person record.
{% endhint %}

The first notification will contain the status `REJECTED` for the operation `QUALITY_ANALYSIS`:

```json
{
	"operation": "QUALITY_ANALYSIS",
	"tguid": "<tguid>",
	"status": "REJECTED"
}
```

The result of the operation `QUALITY_ANALYSIS` will be followed by an enrollment notification with the status `FAILED` for the operation `ENROLL`:

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "FAILED"
}
```

{% endstep %}
{% endstepper %}

### Transaction with Biometric Exception

If an exception occurs while processing the transaction, the incoming transaction will be sent to exception handling for analysis. In this case, a notification is sent indicating that the transaction caused an exception, as shown in the example below:

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "EXCEPTION"
}
```

{% hint style="info" %}
Notifications generated by Update operations do not change the `operation`, and the section `"operation": "ENROLL"` will be the same for enrollment and update operations.
{% endhint %}

{% hint style="info" %}
See the Trust Manual for more details about exception handling.
{% endhint %}

#### Trust Group Exception Handling

Exception handling is performed at the **exception group**, through Trust. At the end of handling a group, an operation notification `TREAT_EXCEPTION_GROUP` is sent, followed — when applicable — by the notifications for `ENROLL` reflecting the final outcome of the transaction(s) involved: enrollment completed, update completed, or failure/rejection.

Example of a group treatment notification:

```json
{
	"operation": "TREAT_EXCEPTION_GROUP",
	"tguid": "<tguid>",
	"status": "<target>-<decision>",
	"target": "<target>",
	"gguid": "<gguid>",
	"treatment": "<group decision>",
	"subDecision": "<sub-flow detail>",
	"newTransactionGUID": "<new tguid, if any>",
	"pguid": "<new pguid, if any>",
	"keptTguids": ["<retained tguid 1>", "<retained tguid 2>"]
}
```

| Field                | Description                                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `target`             | Target of the group exception (e.g., biometric, biographic)                                                         |
| `gguid`              | Group exception identifier                                                                                          |
| `treatment`          | Decision made for the group                                                                                         |
| `subDecision`        | Details the treatment sub-flow (e.g., `ENROLL`, `UPDATE_ENTRANT`, `UPDATE_REFERENCE`, `UPDATE_BOTH`, `UPDATE_NONE`) |
| `newTransactionGUID` | Present when the treatment generates a new transaction (trusted enrollment or resubmission)                         |
| `pguid`              | pguid of the new transaction, when applicable                                                                       |
| `keptTguids`         | List of tguids retained during treatment, when the decision is to retain                                            |

Transactions rejected or discarded during group treatment generate `ENROLL` notifications with `status: FAILED`, including the group's `gguid` and, when available, the `newTransactionGUID`:

```json
{
	"operation": "ENROLL",
	"tguid": "<rejected tguid>",
	"status": "FAILED",
	"gguid": "<gguid>",
	"newTransactionGUID": "<new tguid, if any>",
	"exceptionGroupTguid": "<gguid>"
}
```

### Unresolved Latent Match

When searching against an unresolved latent database, any matches found generate reverse latent match notifications containing the UGUID of the matched unresolved latent (UL). The enrollment or update transaction proceeds normally and is compared against the reference database. This regular search may complete normally or generate an exception. The example below shows the notifications received when an unresolved latent match is followed by a successful enrollment:

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "REVERSE_LATENT_MATCH",
	"uguid": "<uguid>"
}
```

```json
{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "ENROLLED"
}
```

### Resubmission of a Refused Transaction

When a refused transaction (`REFUSED`) is automatically resubmitted by GBDS, a notification is sent indicating the resubmission, with the new tguid associated:

```json
{
	"operation": "ENROLL",
	"tguid": "<original tguid>",
	"status": "RESENT_ENROLL",
	"newTransactionGUID": "<nova tguid>"
}
```

### Removal

At the end of the process of removing a person or biometric data from GBDS, a notification is sent with the result of the operation:

```json
{
	"operation": "DELETE",
	"tguid": "<tguid da tarefa>",
	"status": "COMPLETED",
	"pguid": "<pguid>",
	"relatedExternalIDs": [{ "name": "<name>", "key": "<value>" }]
}
```

The status `COMPLETED` is sent for both biometric data removal and person removal, at the end of the task execution.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.griaule.com/gbs/en/gbds-integration/gbds-5-notification-flows.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
