Load data with files and the API

Customers, accounts and transactions reach FlowSentry in two ways: your systems send them through the API, or you upload a file. Either way, every record traces back to a run, so you can always show where a figure came from. This article explains the concepts; your integration guide covers the technical detail.

Before you start

• You need the Integration engineer or Administrator role. The Data module holds Data sources, Mapping studio, Load data and Ingestion runs.
• An Integration engineer can set up sources and mappings. Going live and activating a mapping need an Administrator who did not make the request.

1. Connect a data source

A data source is one of your systems, such as a core banking, brokerage or mobile-money platform.

1. Open Data sources at /integration/sources.
2. Select Connect a source and fill in the name, description, connector, the data it sends, a Rate limit and a Silence SLA (how many minutes of silence count as a problem).
3. Select Connect source and issue key.
4. The source's signing secret appears once. Select Copy secret, store it in your institution's secret store, then confirm I have stored the secret.

Connectors include a REST API (signed JSON), file upload (CSV, XLSX, JSON, XML), ISO 20022 and M-Pesa Daraja C2B.

Warning: FlowSentry never shows the secret again. Never paste it into email, chat, a ticket or source code. If it may have leaked, rotate it.

2. Test, then go live

A new source starts in Testing, where the API only validates what you send and stores nothing.

1. Send test records and fix any errors.
2. Select Request go-live. The checklist asks for an active signing key, a dry run with no errors, a default mapping template for file runs and a silence SLA.
3. A different Administrator selects Approve go-live and confirms with a fresh second factor.

The source is then Live. It can be Suspended with a reason; going live again needs a new approval.

How API requests are signed

Every request carries a signature made with the source's secret. The signature covers the request method, the path, a timestamp, a single-use value and a fingerprint of the body. FlowSentry checks that:

• the signature is valid, so the request came from your source and was not altered
• the timestamp is within five minutes of the current time
• the single-use value has not been seen before, so a captured request cannot be replayed.

Each record carries your system's own reference. Sending the same reference again never creates a duplicate, so it is always safe to retry.

Responses tell you whether a record was accepted, recognised as a duplicate, rejected for a bad signature, failed validation or was rate-limited. Validation errors name the field and the rule broken, never the value you sent. Request size and the number of rows per batch are limited.

Rotate or revoke a key

On the source page, Rotate key issues a new secret with a grace window (none, one hour, 24 hours or seven days) during which the old one still works. Revoke now stops a key immediately. Both need step-up.

Load a file

1. Make sure a mapping template for the file's layout has an approved version. Build one in Mapping studio (/ingestion/mapping-studio): paste sample rows with the header, select Infer and create draft, adjust the mapping, Preview, then ask a different person to Approve it.
2. Open Load data at /integration/files.
3. Choose the Source, the Kind of data and the Mapping template, then select your file (CSV, XLSX, JSON or XML, up to 8 MB).
4. Select Run file.

The run result accounts for every row: Rows in file, Rows accepted, Duplicates (already ingested) and Quarantined, with control totals comparing the amount in the file with the amount accepted. Running the same file twice is safe: "The same file was run before; nothing was ingested twice."

Fix quarantined rows

1. Open Ingestion runs at /integration/runs and open the run.
2. For each quarantined row, either Correct it, giving a reason, or Dismiss it. Corrections are recorded with your name and the original row is kept.
3. If the mapping was the problem, fix and approve the mapping, then select Replay open rows with the current mapping.
4. To work on rows outside FlowSentry, use Export open rows (CSV).

Tip: Always load customers, accounts and transactions through the API or file runs, never by any other route. That way every record has a traceable origin for auditors.

Related

• Integration guide
• Administrator and Integration engineer
• Check platform health and scheduled jobs