Integration Concepts
Overview
Section titled “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 all integrations across the suite.
Communication patterns
Section titled “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 fired 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 the institution is informed of events in real time.
Authentication
Section titled “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 defined scope and validity.
Tokens must be refreshed before they expire. The platform rejects requests with invalid or expired tokens.
Environments
Section titled “Environments”The platform provides two isolated environments:
- Sandbox: test environment with synthetic data, provided after contract signing. It replicates the production configuration and enables integration validation 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
Section titled “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
Section titled “Versioning”The API uses path-based versioning. Breaking changes are introduced in new versions. The previous version remains available during a transition period announced in advance.
Webhooks
Section titled “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: selection of the event types the institution wants to receive.
- HMAC secret: shared key used to generate and validate the signature of each notification.
Each module in the suite (ONP, FPP, CMP) has its own set of events. The details for each module are on their respective integration pages.