Integration guide

FlowSentry is only as good as the data it receives. This guide explains, at a conceptual level, how your institution's systems connect to FlowSentry: how a data source is registered and approved, how API calls are signed, how files are mapped and loaded, how every row is accounted for, and what FlowSentry sends back out. The detailed request contract — field lists, codes and error responses — is provided to your integration team during implementation.

1. Principles

• Everything traces to a run. Customers, accounts and transactions enter through the signed API or a file run, never by direct database edits. Each record can be traced to the run and source that brought it in.
• Idempotent by design. Every record carries your system's own reference. Sending the same reference again never creates a duplicate, so retries are always safe.
• Nothing is silently dropped. Each row is accepted, recognised as a duplicate, or quarantined with a reason you can see and fix.
• Two people for go-live. A source starts in a test mode and only goes live when a second person approves.
• Money is never a bare number. Every amount carries its currency code; every time is an absolute timestamp.

2. Roles

Task	Integration engineer	Administrator
Connect a source, rotate keys, edit settings	Yes	Yes
Request go-live	Yes	Yes
Approve go-live (step-up, not the requester)	—	Yes
Create and edit mapping templates	Yes	Yes
Approve a mapping template (step-up, not the author)	—	Yes
Upload files and work ingestion runs	Yes	Yes

The Data module in the rail holds Data sources, Mapping studio, Load data and Ingestion runs.

3. What you can send

Data	Typical content
Parties (customers)	Individuals and organisations with identifications, addresses, contacts and relationships such as directors and owners
Accounts	Wallets, savings, current, card, till and securities accounts, with owners and signatories
Transactions	Event type (cash in, cash out, wallet credit and debit, transfer, payment, deposit, withdrawal, reversal and securities events), channel (mobile money, agent, card, bank transfer, ATM, POS, online, branch and others), direction, amount and currency, time, originator and beneficiary, counterparty reference and optional regulatory fields such as countries and purpose
Instruments	For securities firms: instrument codes, ISIN, class, currency and venue

Load parties and accounts before the transactions that reference them. A transaction that references an unknown party or account is rejected whole, so nothing is stored half-linked. Optional regulatory fields — countries of origin and destination, purpose, funds and transaction mode codes — are not required for monitoring, but goAML reports are only as complete as the data behind them.

Corrections arrive as reversal events; transactions are never updated after the fact.

4. Data sources

Every system that sends data is a data source with its own signing key, rate limit and silence SLA.

Connect a source

1. Open Data › Data sources (/integration/sources) and fill in Connect a source: name, description, connector, the data it sends, Rate limit (requests/second) and Silence SLA (minutes) — how long without data before the feed is flagged as silent.
2. Select Connect source and issue key.
3. The signing secret is shown once. Select Copy secret, store it in your secrets vault, and confirm I have stored the secret. FlowSentry stores it encrypted and never shows it again.

Available connectors include REST API (signed JSON), File upload (CSV, XLSX, JSON, XML), ISO 20022 and M-Pesa Daraja C2B.

Lifecycle

State	What the source can do
Testing	Call the validate-only API: payloads are checked against the real validation rules and nothing is stored
Awaiting approval	Same as testing, while a go-live request waits for a second person
Live	Ingest through the API and file runs
Suspended	Nothing; going live again needs a new approval

To go live, open the source and complete the checklist — an active signing key, a dry run over a sample with no errors, a default mapping template for file runs, and a silence SLA — then Request go-live. An administrator who did not make the request selects Approve go-live and completes step-up.

Keys

• Rotate key issues a new key; the old one keeps working for a grace window you choose (none, 1 hour, 24 hours or 7 days) so you can roll it out without downtime.
• Revoke now ends a key immediately (you must rotate first if it is the only active key).
• Both need step-up and are audit-logged.

Warning: Treat a signing secret like a password. Never put it in source code, tickets, e-mail or chat. If one is exposed, rotate it at once and revoke the old key.

5. Signing API requests

Every API call is authenticated by a signature, not a user session:

• Your system computes an HMAC-SHA256 signature with the source's secret over the request method, path, a timestamp, a single-use random value (nonce) and a hash of the body, and sends it with the request alongside the source identifier.
• FlowSentry recomputes the signature and rejects the request if it does not match, if the timestamp is outside a few minutes of FlowSentry's clock, or if the nonce has been seen before. A captured request therefore cannot be replayed.
• Keep your servers' clocks synchronised.

Responses tell you whether a record was accepted, was a duplicate, failed validation (naming the field and rule, never the value you sent), was refused for a bad signature, or was rate-limited. Retry rate-limited and server errors with backoff and a fresh nonce; never retry a signature failure without fixing it. Request bodies and batch sizes are limited, so send large volumes in batches.

6. Mapping templates

A mapping template tells FlowSentry how a file's columns map onto its canonical model.

1. Open Mapping studio (/ingestion/mapping-studio).
2. Paste sample rows with the header line and select Infer and create draft. FlowSentry infers the delimiter, header and column types and suggests matching fields with transforms — dates in a given format, numbers with thousands separators, value maps, defaults, phone number normalisation and more. Or start from a starter layout (for example client master, trade blotter or client-money statement).
3. Adjust the Field mapping, add constants where needed, and Preview up to 50 rows.
4. Submit the template. A different person approves it with step-up; until then, a draft never changes what file runs apply. Every version is kept.

7. File runs

1. Open Load data (/integration/files). Files load only against a live source.
2. Choose the Source, the Kind of data and the Mapping template (only templates with an approved version are listed).
3. Upload the file — CSV, XLSX, JSON or XML, up to 8 MB — and select Run file.
4. Read the Run result: rows in the file, rows accepted, duplicates (already ingested), quarantined rows, and the Control totals comparing the amount in the file with the amount accepted, plus any trailer totals. A reconciled run says so.

Resending the same file is safe: "The same file was run before; nothing was ingested twice."

Quarantined rows

On Ingestion runs (/integration/runs), open a run to see its quarantined rows and why each was refused. You can:

• Correct a row, giving a reason — recorded with your name, with the original values kept;
• Dismiss a row that should not be loaded;
• Replay open rows with the current mapping after fixing a template;
• Export open rows (CSV) to fix them at source.

8. Monitoring feed health

Platform health (/ops/health) shows each source's last data, freshness and lag against its silence SLA. A source that goes quiet is flagged so the owner can investigate before monitoring gaps build up. The Data sources page shows the same health per source.

9. Outbound integrations

• Webhooks: administrators register endpoints in Tenant settings. Each delivery is signed so your receiver can verify it came from FlowSentry; failed deliveries retry with backoff and every attempt is audited.
• Read API: a scoped, field-level read API for alerts, cases, risk, screening and metrics can be enabled for downstream systems; callers only receive the fields their scopes grant.
• Onboarding hand-off: where client onboarding is used, approved customers can be handed to your core system through a signed notification.

10. Go-live checklist

1. Source connected, secret stored in your vault, clocks synchronised.
2. Validate-only calls pass for parties, accounts and transactions.
3. Mapping templates approved for every file kind.
4. Dry run with no errors; go-live approved by a second person.
5. Parties and accounts loaded before transactions; first file runs reconciled.
6. Silence SLA set and visible on Platform health.
7. Key rotation procedure rehearsed.

Related

• Load data with files and the API
• Administrator and integration engineer
• Security and privacy overview