Integration Concepts

Overview

The Guardline Suite exposes REST APIs for integration with the institution’s internal systems (core banking, ERP, CRM, legacy systems). Communication between the institution and the platform follows well-defined patterns that ensure security, traceability, and consistency across all operations.

This section describes the concepts that apply to every integration in the suite.

Communication Patterns

Integration with Guardline uses two complementary communication patterns:

• Requests from the institution to Guardline: authenticated REST calls with JSON payloads. The institution sends data (creating onboardings, submitting transactions, opening cases) and queries results.
• Notifications from Guardline to the institution: webhooks triggered by the platform when relevant events occur (verification completion, case decision, fraud alert). The institution registers callback URLs and selects which events it wants to receive.

These two patterns complement each other. REST calls are used for operations initiated by the institution, while webhooks eliminate the need for polling and ensure that the institution is informed of events in real time.

Authentication

All API calls require authentication via a Bearer token obtained through the OAuth2 client credentials flow. The institution receives credentials (client ID and client secret) during the contracting process and uses them to obtain access tokens with a defined scope and validity period.

Tokens must be renewed before they expire. The platform rejects requests with invalid or expired tokens.

Environments

The platform provides two isolated environments:

• Sandbox: test environment with synthetic data, made available after the contract is signed. It replicates the production configuration and supports validating the integration before go-live.
• Production: operational environment with real data.

Each environment has its own URLs and credentials. Data created in sandbox does not affect production, and vice versa.

Data Format

• All requests and responses use JSON (Content-Type application/json, UTF-8 encoding).
• Dates follow the ISO 8601 format (example: 2025-01-15T14:30:00Z).
• Identifiers are opaque strings generated by the platform.

Versioning

The API is versioned by path. Breaking changes are introduced in new versions. The previous version remains available for a transition period communicated in advance.

Webhooks

Guardline notifies relevant events via configurable webhooks. Each notification includes an HMAC signature that allows the institution to validate the authenticity and integrity of the message before processing it.

Webhook configuration involves three elements:

• Callback URL: the institution’s endpoint that will receive the notifications.
• Subscribed events: the selection of event types the institution wants to receive.
• HMAC secret: shared secret used to generate and validate the signature of each notification.

Each module of the suite (ONP, FPP, CMP) has its own set of events. The details for each module are on the respective integration pages.