FT AML Platform
Developer Portal

Cover Page

The formal front matter for this Developer Guide, provided for enterprise procurement, audit, and archival purposes. This section does not affect the technical content below — skip to Introduction to start integrating.

Document Control

Version history, review, and approval tracking for this guide. Populated as the guide moves through formal review cycles.

Version history

Reviewers & approvers

Change log

A running log of substantive content changes to this guide (distinct from the API/product changelog, which tracks changes to the platform itself).

Table of Contents

A linear index of every section in this guide, generated from the sidebar navigation on the left. Use the sidebar for day-to-day navigation — this section exists for printed/exported copies where the sidebar isn't available.

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

System Requirements

FT AML is delivered as a hosted (SaaS) platform — Fyscaltech operates the servers, databases, and runtime. Most items in a typical "system requirements" section therefore apply to Fyscaltech's infrastructure rather than yours. What follows separates what you, as an integrating developer, actually need to have ready, from platform-side detail that is not applicable to a hosted deployment.

What you need on your side

Platform-side (Fyscaltech-operated)

Provided for completeness and audit purposes — you do not need to provision or manage any of the following:

Firewall & SSL requirements

• Allow outbound HTTPS (443) from your integration servers to the FT AML API host(s) — exact hostnames/IP ranges: TODO — Information Required (to be provided by Product Team)
• If using Bulk CSV via S3, allow outbound HTTPS to the AWS S3 endpoint for the bucket's region
• FT AML's public endpoints are expected to present a valid, trusted TLS certificate; certificate pinning is not documented as required or supported

Prerequisites

Everything you should have in place — or in progress with your Fyscaltech contact — before you start building against any of the three integration methods.

Accounts & access

• Onboarding relationship with Fyscaltech — API access is provisioned during onboarding, not self-service sign-up. Start with your Fyscaltech integration contact (see Support).
• Organization Admin on the FT AML console side, for anyone who needs to manage API-key-adjacent permissions or view ingestion/screening results in the console (Alert Manager, Name Screening, Data Ingestion).
• AWS IAM identity (if using Bulk CSV) — either a human AWS Console sign-in, or an access key/secret key pair for automation. See Bulk data ingestion (CSV via S3).

Certificates, tokens & API keys

Network & DNS

• No DNS records need to be created on your side to call FT AML — you resolve and connect to Fyscaltech-provided hostnames using standard public DNS.
• If you plan to receive webhooks (see Webhooks & Events), you will need a publicly reachable HTTPS endpoint with a valid DNS name and TLS certificate of your own.
• Confirm outbound firewall rules per System Requirements.

Database

No database provisioning is required on your side for any of the three integration methods — all persistence (Postgres, MongoDB, ClickHouse, Redis) is operated by Fyscaltech. See Database Configuration for what is documented about platform-side storage.

SMTP / notifications

Third-party software

• AWS CLI or an S3-compatible SDK — only if you choose the automation path for Bulk CSV (see Bulk data ingestion (CSV via S3))
• An HTTP client capable of TLS 1.2+ — for the Customer Ingestion API and Screening API. No proprietary client library is required; both are plain JSON over HTTPS.
• Postman (optional) — useful for manual testing once a collection is published; see Resources & Changelog.

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. This section documents what is confirmed about the platform's internal architecture from the services already described in Integration Methods — it is not a full architecture specification.

Components & services

Two backend services are confirmed by name, language, and framework so far:

Data flow

Confirmed data flow, end to end, for each integration method:

Database & storage

Four data stores are confirmed as in active use across the two documented services — see Database Configuration for what's documented about each:

• PostgreSQL — the screening ledger (every screening run), written synchronously by /screen
• MongoDB — watchlist/reference data matched against during screening
• ClickHouse — analytical store, upserted by the ingestion consumer alongside Postgres
• Redis — configuration cache, loaded on each screening request

Messaging & workflow orchestration

• SNS/SQS — the Customer Ingestion API publishes an ingestion event here rather than writing synchronously; a background consumer performs the actual persistence
• Temporal — orchestrates the Bulk CSV workflow/queue pipeline (file detection, validation, row-level processing, error reporting)

External integrations

• Amazon S3 — the transport mechanism for Bulk CSV (see Bulk data ingestion (CSV via S3))
• Watchlist data provider — sanctions/PEP/adverse-media source data used by the Screening API. Provider name and refresh cadence: TODO — Information Required (to be provided by Product Team)

Deployment architecture

Communication flow summary

At a glance: your systems talk to FT AML over HTTPS (API calls) or S3 (bulk file transport) only — you never call the internal services (datahub, be-aml-name-screening) or data stores (Postgres, MongoDB, ClickHouse, Redis) directly. Those are internal implementation detail, documented here only so you understand what's happening after your request leaves your system.

Installation Guide

FT AML is a hosted (SaaS) platform — there is no server software for you to download and install. This section documents the closest equivalent for each integration method: the one-time setup that gets your side ready to send its first request.

Step 1 — Request access

Objective: obtain the credentials needed for your chosen integration method(s).

1. Contact the Fyscaltech integration team (see Support).
2. Confirm which of the three Integration Methods apply to your use case.
3. Receive credentials — S3 bucket name + client id (Bulk CSV), and/or API access detail once confirmed for the Ingestion/Screening APIs.

Expected output: a bucket name, client id, and/or API access confirmation from Fyscaltech.

Validation: you can name the exact <client-id> folder path you were given, per Bulk data ingestion (CSV via S3).

Step 2 — Set up the AWS CLI (Bulk CSV path only)

Objective: get a working, authenticated AWS CLI (or S3 SDK) able to write to your inbox path.

Commands:

aws configure          # one-time setup, using the access key and secret key we send you

Expected output: the CLI stores your credentials locally; no error is printed.

Validation:

aws s3 ls s3://<bucket>/<client-id>/

A successful listing (even if empty) confirms your credentials are valid and scoped correctly.

Step 3 — Confirm API reachability (Customer Ingestion / Screening APIs)

Objective: confirm your network can reach the API host over HTTPS before writing integration code.

curl -i -X POST https://<host>/riskradar/core/api/v1/bo/screen \
  -H "Content-Type: application/json" \
  -d '{"customer_name": "Test User"}'

Expected output: an HTTP response with a JSON body shaped like { "code": "00000", "message": "Success", "data": {...} } — see Screening API for the full response shape. Use the read-only /bo/screen endpoint for this check so no alert is created by a connectivity test.

Troubleshooting: a connection timeout suggests a firewall/network issue (see System Requirements); a 4xx/5xx with a JSON body means you reached the service — check the error code against Business error codes.

Step 4 — Verification checklist

• AWS CLI (or SDK) authenticates and can list your client-id path — Bulk CSV only
• A test HTTPS call to the Screening API's read-only endpoint returns a valid JSON envelope
• Your Fyscaltech contact has confirmed which environment (sandbox/production) the above credentials belong to

Continue to Configuration Guide once every applicable item above is checked off.

Configuration Guide

Configuration that is set on the platform side (via the FT AML console) but directly affects how your integration behaves. There are no client-side configuration files to edit — FT AML has no local install — so this section documents the console-side settings you'll want your team to be aware of.

Bulk CSV ingestion schedule

Purpose: controls when the platform checks your S3 inbox for new files. Location: FT AML console → Data Ingestion. Properties:

CSV file format rules

Full column-level reference lives under Bulk data ingestion (CSV via S3); the cross-cutting rules that apply to both the Customer and Account files are summarized there under "File format rules (both files)."

Screening control on ingestion

Purpose: the name_screening_enabled field on the Customer Ingestion API payload controls whether ingesting a customer also triggers a screening run as a side effect. Default value: true when omitted. Recommended value: leave at the default unless you are deliberately deferring screening to a separate, explicit Screening API call (Flow A) — see Integration Workflows for the two supported patterns.

Environment variables

Not applicable on the platform side (no client-installed component). On your own side, the values you'll typically hold as environment/secret configuration are the S3 credentials and, once confirmed, the API credential for the Ingestion/Screening APIs — see Security Best Practices → Secrets management.

Database Configuration

FT AML's databases are fully managed by Fyscaltech — you never connect to them directly, provision schemas, or run migrations yourself. This section documents what is confirmed about platform-side storage, for architectural awareness only.

Confirmed data stores

Schema & tables

Connection, migration, backup & restore

Not applicable to you as an integrating developer — these are operated internally by Fyscaltech. If you require attestation of backup/restore or disaster-recovery practices for a vendor security review, request this directly from your Fyscaltech contact; it is not published in this guide.

Performance & indexes

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.

Module-wise Integration Guide

FT AML's console has many modules (Case Manager, Alert Manager, Name Screening, Transaction Monitoring, STR Listing, and more — see the FT AML User Guide). This section tracks which of them currently have a documented integration surface (an API or file-based method you can call from your own systems), versus modules that are today accessed only through the console UI.

Module: Bulk Data Ingestion

Module: Customer Ingestion (API)

Module: Name Screening (API)

Console-only modules (no documented integration surface yet)

The following FT AML modules are used through the console UI only, as of this guide. If your use case requires programmatic access to any of them, raise it with your Fyscaltech contact — this table will be updated as new integration surfaces are confirmed.

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

Deployment Guide

FT AML itself is deployed and operated entirely by Fyscaltech — you never deploy the platform. This section instead covers how your own integration typically progresses across environments, and what changes (or doesn't) between them.

Environments

Docker / Kubernetes / your own runtime

Not applicable to FT AML itself. If your own integration code runs in Docker, Kubernetes, or behind IIS/Nginx/Apache, there is nothing FT AML-specific required in that layer beyond outbound HTTPS access (see System Requirements) — treat calling FT AML the same as calling any other external HTTPS API from your existing deployment pipeline.

CI/CD

• Keep S3 credentials and any API credentials in your CI/CD secrets store, never committed to source control — see Security Best Practices → Secrets management
• Consider a CI smoke test that calls the read-only /bo/screen endpoint on each deploy, to catch connectivity regressions before they reach production — see Testing Guide
• If your pipeline generates and uploads CSV files, validate the header row programmatically before upload — a single malformed header rejects the whole file (see Bulk CSV)

Testing & Sandbox

How to validate your integration before it touches real customer data, and a starting set of test cases for each integration method.

Sandbox availability

For Bulk CSV, the same S3 location and console feedback (Data Ingestion job status) apply whether you're testing or in production — there is no separate sandbox bucket documented today, so start with a small file (50–100 rows) to confirm your CSV format is accepted before uploading your full population.

Unit & integration testing (your code)

• Unit tests — mock the three HTTPS/S3 calls in your own test suite; there is no FT AML-provided mock server yet, so assert against the request/response shapes documented under Integration Methods.
• Integration tests — run against real FT AML endpoints using the read-only /bo/screen path and a disposable test S3 prefix/file, so tests don't create alerts or pollute production-like data unnecessarily.

Smoke testing

A minimal smoke test that exercises all three integration methods end to end:

1. Upload a small test CSV file and confirm it moves from inbox/ to processed/ — see Bulk CSV.
2. Call POST /datahub/ingestion/v1/customer with a test record and confirm a 202 Accepted.
3. Call POST /riskradar/core/api/v1/bo/screen with a known test name and confirm a scored result comes back.

API test cases

Regression testing

Re-run the API test cases above after any change to your own request-building code, and after Fyscaltech communicates an API change via Changelog & versioning. There is no automated regression suite published by Fyscaltech today — building your own from the test cases above is recommended.

Validation Checklist

After completing setup for any integration method, work through the relevant checks below before considering the integration production-ready.

General

• ✓ Services reachable — a test call to /bo/screen returns 200 with a valid JSON envelope
• ✓ Database connected — not directly checkable by you; inferred from a successful /screen call returning a screening_id, which requires the Postgres ledger write to succeed
• ✓ APIs working — see API test cases, all pass
• ✓ Authentication successful — TODO — Information Required until application-level auth is confirmed, see Authentication
• ✓ Console accessible — an Admin user can log in and see ingested/screened records reflected (Data Ingestion, Alert Manager, Name Screening)
• ✓ Logs generated — TODO — Information Required, see Logging
• ✓ Monitoring active — TODO — Information Required

Per integration method

Logging

What's confirmed today about tracing and diagnosing a request, from your side as an external developer.

Request tracing

Responses include an X-Request-Id header — capture and log this on your side for every call. It's the fastest way for Fyscaltech support to locate your specific request in their own logs; see Support → What to include.

Log locations, levels & rotation (platform-side)

What to log on your side

• Every request's X-Request-Id, timestamp, endpoint, and HTTP status
• The business error code (not just HTTP status) from any error response — see Business error codes
• For Bulk CSV, the filename and upload timestamp of every file you send, so you can correlate against the console's Data Ingestion job history

Security Best Practices

Practices to follow on your side when integrating with FT AML. General security guidance below is presented as standard practice recommendations, not as a description of FT AML's own internal controls unless explicitly stated as confirmed.

Secrets management

• Store AWS access keys and any API credentials in a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault) rather than source control or environment files checked into a repository
• Keep credentials on your backend or automation only — never embed them in client-side/browser code, since Bulk CSV credentials and any future API keys are bearer-style secrets
• Rotate credentials periodically and immediately upon suspected exposure; contact Fyscaltech to reissue

Transport & certificates

• Use TLS 1.2 or higher for every call to FT AML endpoints and S3 — see System Requirements
• Validate the server certificate normally (don't disable certificate verification in your HTTP client, even for testing)

Data handling

• Treat customer records (names, addresses, identity numbers, financial data) as personal data throughout your own pipeline, not only within FT AML
• Never send data files by email or shared drive — use only the designated S3 paths (see Bulk CSV)
• Apply the logging guidance under Logging → What to log on your side to avoid persisting personal data in plaintext logs unnecessarily

Access control & least privilege

• Scope AWS IAM policies to the minimum required — your own <client-id> prefix only, not the whole bucket (this is enforced by Fyscaltech-issued credentials by default)
• Limit who on your team can manage API-key-adjacent permissions to your organization's Admins in the FT AML console

Vulnerability reporting

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.

Appendix

Reference material collected in one place: acronyms, configuration templates, and sample payloads — each cross-referenced back to its full documentation elsewhere in this guide rather than duplicated in full.

Acronyms

Glossary

The full term-by-term glossary lives in its own section — see Glossary for every field name and platform term used throughout this guide.

References & external links

• FT AML product page
• FT AML User Guide — the console/end-user reference, as distinct from this Developer Guide
• Fyscaltech integration team — see Support

Configuration templates

Copy-paste-ready header rows for Bulk CSV — full column-level reference is under Bulk data ingestion (CSV via S3).

Customer file header (52 columns):

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

Account file header (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

Sample requests & responses

Customer Ingestion API — full reference at Customer Ingestion API:

POST /datahub/ingestion/v1/customer
Content-Type: application/json

{ "customer_id": "CUST-1001", "customer_name": "Jane Doe", "customer_type": "Individual" }

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

Screening API — full reference at Screening API:

POST /riskradar/core/api/v1/screen
Content-Type: application/json

{ "customer_name": "Jane Doe", "customer_type": "Individual" }

200 OK
{ "code": "00000", "message": "Success", "data": { "screening_result": { "alert_score": 87.5, "alert_category": "HIGH" } } }

Documentation standards used in this guide

• Confirmed technical detail is stated directly; anything not yet confirmed by the technical team is marked with a "Will be published soon" callout or a TODO — Information Required tag, rather than guessed at.
• Existing screenshots and diagrams from the original guide are preserved as-is; new diagrams use the same flow-box/flow-arrow visual pattern already established in Integration Workflows.
• Every numbered procedure includes an objective, the exact commands, expected output, and a validation step, consistent with Installation Guide.