FT AML Platform
Developer Portal

Introduction

This Developer Portal is the integration reference for the FT AML Platform. It's written for three audiences: customers connecting their own core banking or onboarding systems to FT AML, partners building on top of the platform on a customer's behalf, and Fyscaltech implementation teams delivering a go-live. Wherever a detail depends on your specific deployment — credentials, exact payload schemas, rate limits — this guide says so explicitly rather than guessing, and points you to the Fyscaltech integration team who confirms it during onboarding.

What FT AML does

FT AML is an Anti-Money Laundering (AML) platform that helps financial institutions detect suspicious activity, screen customers against regulatory watchlists, monitor transactions, manage investigations, and comply with AML/CTF regulations. The Developer Portal covers the integration surface of that platform — getting your data in, and getting screening results and alerts back out — rather than the compliance-analyst console itself.

There are three ways data moves between your systems and FT AML

• Bulk CSV via S3 — for loading or refreshing large volumes of Customer, Customer Account, and Customer Transaction records.
• Customer Ingestion API — for pushing or updating individual customer records from your own systems as they change.
• Screening API — for screening a specific customer record on demand, by full name.

Who does what

Quick Start

If you're an external developer integrating FT AML into your own systems for the first time, this is the one section to read start to finish — everything else in this portal is reference material you'll come back to as you go.

The fastest path from zero to a working integration follows the same six steps regardless of which integration method you end up using day to day.

1. Request API credentials — contact the Fyscaltech integration team (see Support) to start onboarding. They'll confirm which integration method(s) fit your use case.
2. Receive sandbox access — where a sandbox/test environment applies to your chosen method, credentials and connection details are issued as part of onboarding (see Testing & Sandbox).
3. Upload a sample customer — load a small test file via Bulk CSV (50–100 rows is plenty), or a single record via the Customer Ingestion API, to confirm your data format is accepted.
4. Call the Screening API — submit a customer's full name to /screen and confirm a result comes back in the response.
5. Check the delivery mechanism for ingestion-triggered screening — if you plan to rely on name_screening_enabled during ingestion instead of calling the Screening API directly, confirm with Fyscaltech how that result reaches you before building against it.
6. View the screening result — check the FT AML console (Alert Manager, or Name Screening) to see the same result reflected on the platform side.

Platform & Architecture

FT AML sits alongside your core banking and customer-facing systems, receiving data through the integration methods in this portal and returning screening results and alerts.

Core Concepts & Data Models

A few ideas come up across all three integration methods. Understanding these up front makes the rest of this portal easier to follow.

Data models

Confirmed field names below come directly from the Customer Ingestion API and CSV bulk-upload formats — where a model isn't backed by data received from the technical team yet, that's noted rather than guessed at.

Integration Methods

The three ways data moves between your systems and the FT AML Platform, in detail.

Which one should I use?

Bulk data ingestion (CSV via S3)

For loading or refreshing data in volume, the platform reads CSV files you upload to a dedicated Amazon S3 location. Fyscaltech provisions this bucket for you during onboarding — you'll receive the bucket name and a client id (a short code, e.g. acme-bank) that scopes every path below to your own data.

Getting access

Two access options — tell your Fyscaltech contact which fits your team:

• Browser (AWS Console) — best if a person uploads files manually, a few times a month. No setup beyond a sign-in.
• Command line / automation — an access key and secret key for the AWS CLI or any S3 library, best if a scheduled job on your side produces the files without a person involved.

aws configure          # one-time setup, using the access key and secret key we send you
aws s3 cp customers_20260729.csv s3://<bucket>/<client-id>/inbox/customer/

Where to upload

• Name files with a sortable date — customers_20260729.csv, not 29-07-2026 — since if more than one file is waiting, the platform processes whichever name sorts first, and only one file per run.
• Upload customers before accounts. An account belongs to a customer, so if you're sending both at once, the customer file needs to land first — accounts referencing a customer we haven't seen yet are skipped and reported back to you.

Once a file is read, it's moved out of the inbox — an empty inbox means processing is done, not that something went wrong:

Choosing your ingestion schedule

You control when the platform looks for your files, from the back-office application — no ticket or code change needed. Set a Frequency (every day, or every N days) and one or more Run times (e.g. 02:00 and 14:00); at each of those times the inbox is checked, and an empty inbox simply means nothing runs until the next check. The schedule can also be paused while you're making changes.

File format rules (both files)

• CSV, UTF-8 encoded, with a header row first
• The header row must match exactly — same column names, spelling, order, all capitals. This is the one thing that gets the whole file rejected rather than individual rows.
• Every row must have the same number of columns as the header, even when values are empty (A,,C)
• Leave optional columns blank rather than writing NULL, N/A, or - — those are treated as real values and usually rejected
• Wrap a value in double quotes if it contains a comma: "Smith, John"
• Dates: 2026-07-29, 2026/07/29, 29-07-2026, 29/07/2026, or 20260729 — pick one form and stay consistent
• Timestamps (date + time columns): 2026-07-29T14:30:00Z is recommended (UTC)
• Yes/no columns accept true/false/1/0/Y/N/yes/no, any case
• Country and currency columns use short codes (IN, SG, AE; INR, USD) — some columns are too narrow for full names

Customer file — 52 columns

Copy this header line exactly:

CUSTOMER_ID,CUSTOMER_TYPE,CUSTOMER_NAME,STATUS_CODE,CUSTOMER_SEGMENT_CODE,CUSTOMER_SEGMENT_NAME,RISK_LEVEL,RISK_SCORE,KYC_LEVEL,KYC_LEVEL_DESCRIPTION,PEP_FLAG,SANCTIONS_STATUS,SOURCE_OF_FUNDS,KYC_AUTHORIZED_SIGNATORY_NAME,ONBOARDING_DATE,ONBOARDING_CHANNEL,STREET,CITY,PROVINCE_REGION,ADDRESS_COUNTRY,POSTAL_CODE,CITIZENSHIP_COUNTRY,RESIDENCE_OPERATION_COUNTRY,BIRTH_INCORPORATION_COUNTRY,CUSTOMER_CONTACT_NO,ACCOUNT_TYPE,ACCOUNT_OPEN_DATE,ACCOUNT_AGE_DAYS,EXPECTED_MONTHLY_SPEND,EXPECTED_MONTHLY_SPEND_CURRENCY,EXPECTED_TXN_FREQUENCY,PURPOSE_OF_ACCOUNT,FIRST_NAME,MIDDLE_NAME,LAST_NAME,GENDER,DATE_OF_BIRTH_OR_INCORPORATION,CUSTOMER_AGE,CUSTOMER_ALIASES,CUSTOMER_ID_NO,CUSTOMER_ID_TYPE,CUSTOMER_ID_EXPIRY_DATE,CUSTOMER_ID_ISSUE_DATE,CUSTOMER_ID_COUNTRY,DESIGNATION,EMPLOYER_NAME,DECLARED_INCOME,INCOME_CURRENCY,NATURE_OF_BUSINESS,COUNTRY_OF_OPERATIONS,CREATED_AT,UPDATED_AT

These six must always have a value — a row missing any of them is rejected:

Fixed-value columns (anything else is rejected): CUSTOMER_TYPE (INDIVIDUAL/CORPORATE/BUSINESS), RISK_LEVEL (LOW/MEDIUM/HIGH), GENDER (MALE/FEMALE/OTHER).

Four cross-field rules worth knowing, since these catch inconsistent records: an INDIVIDUAL requires FIRST_NAME and DATE_OF_BIRTH_OR_INCORPORATION; a CORPORATE requires NATURE_OF_BUSINESS; if DECLARED_INCOME is set, INCOME_CURRENCY must be too; and if both CUSTOMER_AGE and a date of birth are given, they must agree within one year.

Account file — 13 columns

ACCOUNT_NUMBER,CUSTOMER_ID,ACCOUNT_TYPE,ACCOUNT_NAME,ACCOUNT_CURRENCY_CODE,ACCOUNT_BANK_NAME,ACCOUNT_BANK_COUNTRY,ACCOUNT_STATUS,ACCOUNT_HOLDING_TYPE,SIGNATORY_CUSTOMER_ID,SIGNATORY_NAME,CREATED_AT,UPDATED_AT

Seven required: ACCOUNT_NUMBER (unique across all your accounts, not just per-customer, max 128 chars), CUSTOMER_ID (must match a customer already received, or the account is skipped), ACCOUNT_TYPE (SAVINGS/CURRENT/WALLET/FIXED_DEPOSIT/LOAN), ACCOUNT_STATUS (ACTIVE/INACTIVE/CLOSED/FROZEN), ACCOUNT_HOLDING_TYPE (SOLE/JOINT/TRUST/CUSTODIAL), CREATED_AT, and UPDATED_AT timestamps.

If ACCOUNT_HOLDING_TYPE is JOINT, TRUST, or CUSTODIAL, SIGNATORY_CUSTOMER_ID becomes required too — a shared account needs a second party. UPDATED_AT can never be earlier than CREATED_AT.

The remaining six columns are optional: ACCOUNT_NAME and ACCOUNT_BANK_NAME (free text, max 255 chars), ACCOUNT_CURRENCY_CODE and ACCOUNT_BANK_COUNTRY (short codes only — max 16 characters, so a full name like "United Arab Emirates" won't fit and is rejected; use AE instead), and SIGNATORY_CUSTOMER_ID/SIGNATORY_NAME for an additional signatory.

Common problems

Customer Ingestion API

Service: datahub (Go / Gin)

Ingests or updates a single customer's information from your own system — the API equivalent of a bulk Customer Record upload, but for one record at a time and in near real time as your data changes. Ingestion is asynchronous: the endpoint validates the payload and publishes an event, then returns immediately — persistence happens moments later via a background consumer, not within the request itself.

Request payload

All fields are flat — no nesting. Only customer_id and customer_name are required; every other field is optional (omit it and it's treated as null). The field set mirrors the CSV Customer Record columns above, just in snake_case JSON:

{
  "customer_id": "CUST-1001",              // REQUIRED, string
  "customer_name": "Jane Doe",             // REQUIRED, string
  "customer_type": "Individual",          // "Individual" | "Corporate"; blank defaults to "Individual"

  // KYC / status
  "status_code": "ACTIVE",
  "customer_segment_code": "RETAIL",
  "risk_level": "LOW",
  "risk_score": 12.5,                     // float
  "pep_flag": false,                      // bool
  "sanctions_status": "CLEAR",

  // Onboarding
  "onboarding_date": "2025-01-15",        // YYYY-MM-DD or RFC3339
  "onboarding_channel": "BRANCH",

  // Address
  "street": "...", "city": "...", "address_country": "AE",

  // Personal
  "first_name": "Jane", "last_name": "Doe",
  "gender": "F",
  "date_of_birth_or_incorporation": "1990-05-01",

  // Identity document
  "customer_id_no": "...", "customer_id_type": "PASSPORT",

  // Screening control — omitted defaults to true
  "name_screening_enabled": true                // bool
}

Response

{ "code": "00000", "message": "success" }

Returned with 202 Accepted. There's no result field — nothing is persisted synchronously, so there's nothing to hand back yet.

Validation rules

• Request body is required and must be valid JSON
• customer_id and customer_name — trimmed, must be non-empty
• customer_type — blank defaults to Individual; any other value is accepted as-is
• No format, length, or enum checks are enforced on the remaining fields

Error responses

Shape: { "code": "<code>", "message": "<message>" }

Flow

POST /customer → controller (bind → validate → map) → PublishCustomerIngestionEvent publishes to SNS/SQS → returns 202. Consumers later upsert the record into Postgres and ClickHouse — neither database is written to synchronously within the request.

Screening API

Service: be-aml-name-screening (Python / FastAPI)

Screens a customer against watchlists and returns matches, synchronously — the result comes back in the same response. Two endpoints exist:

Use the main /screen endpoint for real onboarding/monitoring checks that should raise alerts when warranted. Use /bo/screen when you want to see what a screening result would look like — e.g. previewing a match — without it creating an alert.

Request payload

/screen accepts a free-form JSON object — extra fields are allowed and preserved. customer_name is required; customer_type must be "Individual" or "Entity" (defaults to Individual); everything else is optional. The field set mirrors the Customer Ingestion API payload — status_code, risk_level, risk_score, pep_flag, address fields, personal/identity/employment fields, and so on — so a record you've already ingested can largely be re-sent as-is to screen it. Only a subset actually drives matching: customer_name, date_of_birth_or_incorporation, street, city, province_region, citizenship_country, customer_type, gender. If customer_id is omitted, a temporary TMP<uuid> is generated for that request.

{
  "customer_name": "Jane Doe",                    // REQUIRED
  "customer_id": "CUST-1001",
  "customer_type": "Individual",
  "gender": "F",
  "date_of_birth_or_incorporation": "1990-05-01",
  "citizenship_country": "IN",
  "street": "...", "city": "...", "address_country": "AE"
}

/bo/screen takes the same shape, but only customer_name is accepted/required — everything else is ignored for matching purposes on this read-only endpoint.

Response envelope

{ "code": "00000", "message": "Success", "data": { /* result */ } }

Exactly three fields — code, message, data. There's no result or pagination field. Success code is 00000.

/screen result — trimmed, public

{
  "data": {
    "meta": { "entity_key": "...", "screening_id": "...", "timestamp": "..." },
    "screening_result": { "alert_score": 87.5, "alert_category": "HIGH" },  // score 0–100
    "alert_details": { "alert_code": "...", "alert_status": "..." },
    "watchlist_records_matched": [   // top 10, or null
      { "UID": 12345, "full_name": "Jane Doe", "match_score": 91.2 }
    ]
  }
}

/bo/screen result — richer, raw

Same meta/score/category fields, but alert_code and alert_status are always null (no alerting on this endpoint), plus a full raw_matches array (up to 50) with per-attribute detail — each matched attribute (name, country, date of birth, entity type, address) carries its own weight and contribution score, so you can see exactly why a match scored the way it did rather than just the final number.

Each entry in raw_matches also carries record-level detail beyond the scored attributes: match_id, watchlist_mongo_id (the underlying watchlist record's own id), risk_level, record_version, updated_date, and a soft-delete pair — is_deleted / deleted_at — showing whether the matched watchlist record has since been retired at the source.

Validation rules

• /screen — customer_name required, customer_type must be Individual/Entity, numeric fields are coerced, unknown fields are allowed and preserved
• /bo/screen — additionally rejects an empty customer_name with entity name required

Error responses

Shape: { "code": "<code>", "message": "<message>", "data": <optional> }

Flow

POST /screen → handler validates → service loads config from Redis/Mongo → FuzzySearchEngine.screen_user matches against sanctions/watchlist data → maps to response. On /screen it also records the screening run in Postgres and, when the result scores as an alert, creates alerts and publishes events. /bo/screen skips all of that alerting — it's read-only end to end.

Authentication

Access is confirmed for one of the three integration methods so far:

• Bulk CSV via S3 — Fyscaltech provisions the S3 bucket location your files are uploaded to, along with the AWS access credentials needed to write to it. Keep these credentials on your backend or automation only, never in client-side code, and store them in a secrets manager rather than source control.

Integration Workflows

There are two distinct request patterns depending on which APIs you use — a synchronous flow where the screening result comes back in the same response, and an asynchronous flow where it's delivered later to your webhook.

Flow A — synchronous (Screening API called directly)

Flow B — asynchronous (ingestion-triggered screening)

The Customer Ingestion API accepts a name_screening_enabled field (defaulting to true when omitted), so ingesting a customer can trigger screening as a side effect rather than requiring a separate call to the Screening API. What isn't yet confirmed in this documentation is the exact delivery mechanism for that result back to your system — likely a webhook, but confirm the specifics with your Fyscaltech integration contact before building against it.

Bulk CSV — batch (sits outside both flows)

Bulk CSV uploads are for getting Customer, Customer Account, and Customer Transaction data into the platform in volume, rather than triggering an immediate screening result back to your system. Screening or monitoring against that data happens on the platform's own schedule (see Name Screening's Batch and Delta Screening, and Transaction Monitoring's execution intervals) rather than as a direct response to the upload.

Choosing sync vs. async

Webhooks & Events

A webhook would only be relevant if you're using the Customer Ingestion API's name_screening_enabled flag to trigger screening as part of ingesting a customer record, rather than calling the Screening API directly. Whether delivery actually happens via webhook — versus some other mechanism — isn't confirmed yet; the pattern below is the expected shape, not a confirmed spec.

How it works (expected pattern, not yet confirmed)

• Unlike Bulk CSV, a webhook endpoint would be hosted and owned by you, not Fyscaltech
• Fyscaltech would provide the request format and signature-verification guidelines once finalized

Errors, Limits & Best Practices

Both the Customer Ingestion API and Screening API return the business error codes below alongside their HTTP status.

Business error codes

Business-level error codes sit alongside the HTTP status and identify the specific validation or business rule that failed. Confirmed codes so far, from Customer Ingestion API and Screening API:

Both APIs share a similar response envelope shape (code + message, with Screening additionally carrying a data field) — check code first for programmatic handling, and treat message as human-readable detail rather than something to match against in logic.

Best practices

Testing & Sandbox

For bulk CSV ingestion, the same S3 location and console feedback (Data Ingestion job status) apply regardless of whether you're testing or in production, so start with a small file to confirm your CSV format is accepted before uploading your full population.

Troubleshooting & FAQ

Common issues

Frequently asked questions

Glossary

Terms and field names used throughout this Developer Portal, defined for anyone integrating for the first time.

Developer Community

A space for developers integrating with FT AML to ask questions, share patterns, and hear from each other — not just from Fyscaltech directly.

Resources & Changelog

Downloadable and reference materials to speed up integration work. Anything not yet available will be published soon once received from technical team.

Changelog & versioning

As the Customer Ingestion and Screening APIs move from onboarding-provided specifications toward a stable published reference, changes will be communicated directly by the Fyscaltech integration team. If you're integrated against either API, keeping a point of contact with the team (see Support) is the most reliable way to hear about upcoming changes before they land.

Support

• In-app: Homepage > Help & Support
• Email: hello@fyscaltech.com
• Phone: +65 8080 5424
• Headquarters: Singapore · 68 Circular Road
• Account-level issues (API key provisioning, permissions) — contact your organization's Admin

What to include when you contact us

To help us resolve integration issues quickly, please include: the environment (sandbox/production), the endpoint and HTTP method, the X-Request-Id from the response headers if available, and a timestamp of when the issue occurred.

Thank you for building on FT AML.