CMP Integration

Overview

The Case Management Platform (CMP) is the Guardline Suite module responsible for managing cases that require human analysis. Integrating with the CMP lets external systems open cases programmatically on each analysis desk, follow the outcome, and receive notifications about the relevant lifecycle events.

The model follows a clear separation of responsibilities: the institution’s engine detects and opens the case; Guardline queues, distributes, analyzes and decides. The institution does not need to know about queues, approval authorities or SLAs in order to integrate: it sends the alert with the source identifier and receives the case identifier back.

Desks and entry points

Each CMP desk has its own ingest endpoint. All of them accept JSON over POST and are authenticated by an API token scoped to that desk.

Desk	Typical source	Endpoint	Token scope
Fraude	Fraud prevention engine (FPP or third party)	/api/v1/ingest/fraude	ingest:fraude
MED	Requests from the special refund mechanism (Mecanismo Especial de Devolução)	/api/v1/ingest/med	ingest:med
AML	Money laundering monitoring engine	/api/v1/ingest/pld	ingest:pld
Cadastro PF and Cadastro PJ	Onboarding (ONP or the institution’s own decision engine)	/api/v1/ingest/kyc	ingest:kyc

The onboarding endpoint serves both individuals (KYC, including minors with a legal representative) and legal entities (KYB); the desk is chosen by the journey type declared in the payload.

Compatibility with external engines

The CMP accepts cases from any source. Institutions that use their own decision engine (or a third-party one) send the alerts directly to the corresponding desk, and the CMP operates queues, approval authorities, SLAs, the committee and the audit trail in the same way it does for the cases generated by the other modules of the Guardline Suite.

This lets the institution centralize case management in a single environment, regardless of how many decision engines are in operation.

Integration flow

The typical integration flow with the CMP follows these steps:

1. The CMP administrator creates an API token with the desk scope and delivers it to the source system.
2. The source system (decision engine, FPP, ONP or another) sends the alert to the desk endpoint, providing the identifier of the event in the source system and the context data.
3. The CMP validates the payload, applies idempotency on the source identifier, computes risk and SLA according to the desk policy, and returns the case identifier.
4. The distribution engine assigns the case to an available analyst in the entry queue of the desk.
5. The analyst reviews the case file and records the decision (approve, reject, set pending, escalate, transfer to another desk or convene the committee), always with a justification.
6. The outcome flows back to the source system: through the ONP for onboarding cases; through a signed webhook for the AML desk events.

Authentication

The ingest endpoints require the X-API-Key header with an API token in the form cmp_ followed by 64 hexadecimal characters. Tokens are created by the institution’s administrator in the CMP admin panel, with a scope per desk, a rate limit per time window and an optional expiry. The token value is displayed only once, at creation; the platform stores only the hash.

A missing or invalid credential answers 401; a valid token scoped to another desk answers 403; an exceeded rate limit answers 429. Every rejection is recorded in the audit trail with the source, path and reason. A token can be issued with the generic ingest scope, which serves all four desks; that is the scope applied when no other one is given at creation.

The onboarding endpoint can additionally require an HMAC-SHA256 signature of the request body (headers X-Guardline-Timestamp and X-Guardline-Signature), enabled per instance during integration setup. It is the same signature format used by the ONP webhooks.

Idempotency

Each endpoint deduplicates on a natural key chosen by the source system: external_id on the Fraude desk, alerta_externo_id on the AML desk and the onboarding execution identifier (or case_id) on the Cadastro desks. The MED desk uses the first field present among id, event_id, notification_id and med_id; without any of them, the key becomes a hash of the request body, which does not survive any change in serialization and therefore does not replace sending a real identifier. The first call creates the case and answers 201; resends answer 200 with the identifier of the existing case, without overwriting anything. This makes it safe to repeat the call after a network timeout.

The AML desk has an additional rule: a new alert for a CPF or CNPJ that already has an active case is consolidated into that case instead of opening another one. The exception is the cash operation report (COE, comunicação de operação em espécie): cash movements at or above R$ 50.000,00, when the source system identifies them as a cash operation, always open a case of their own, without consolidation, and skip triage.

Decision feedback

How the analyst’s decision reaches the source system depends on the desk:

• Cadastro PF and Cadastro PJ (onboarding): the CMP returns the terminal decisions, approval and rejection, to the ONP, and the ONP resumes the execution and emits its own onboarding events to the institution. An integrator that uses ONP and CMP together consumes a single webhook stream, the ONP one. Intermediate decisions, such as escalating or requesting additional information, stay in the CMP and produce no ONP event.
• AML: the flow transitions (archiving during triage, committee deliberation, registration, error, rectification and cancellation of the COAF communication) are published by signed webhook to the configured receivers.
• Fraude and MED: the decision, its operational effects and the justification are recorded in the case detail and in the CMP audit trail. Webhook publication for these desks is enabled on demand during integration setup.

Notifications

The CMP outbound webhooks carry a single envelope (event, delivery_id, correlation_key, case_id, attempt, timestamp, payload), are signed with HMAC-SHA256 over the raw body (header X-Webhook-Signature) and identify the event and the delivery in dedicated headers, which allows routing and deduplication without parsing the body. Deliveries without a 2xx response within 10 seconds are retried twice, from a persistent outbox drained every 60 seconds: the second attempt enters the following drain and the third at least 30 seconds after that. Once the three are exhausted, the delivery is closed as failed, and resending is done on request by Guardline operations.

Which events to receive, the target URL and the signing secret are defined during integration setup, as described in the integration concepts.

API reference

The complete contracts (fields of each endpoint, risk and priority derivation rules, examples, error codes, token administration and webhook verification) are in the CMP API reference.