Getting Started

Get up and running with the Floodlight AML API in under 5 minutes.

Prerequisites

A Floodlight AML account (Sign up here)
Your OAuth client credentials (IAM → OAuth Clients in the Dashboard)

URL Placeholders

{AUTH_URL} — Auth API

https://dev.auth-api.scytalesystems.tech (dev) | https://auth-api.scytalesystems.tech (prod)

{AML_CORE_URL} — AML Core API

https://dev.aml-core-api.scytalesystems.tech (dev) | https://aml-core-api.scytalesystems.tech (prod)

Step 1: Get Your Client Credentials

Log into your Dashboard and navigate to IAM → OAuth Clients. Create a new OAuth client and copy the client_id and client_secret — the secret is only shown once.

⚠️ Security Notice: Never expose your client secret in client-side code or public repositories. Use environment variables to store credentials securely.

Step 2: Get an Access Token

Exchange your credentials for a JWT access token via the client login endpoint:

cURL

curl -X POST 'AUTH_URL/auth/api/v1/client-login' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET"
}'

Response:

JSON

{
  "timestamp": "2026-06-01T14:12:22.942100055Z",
  "status": 200,
  "message": "Client authenticated",
  "correlationId": "df6a9da7-156f-466f-845a-d888ca25885c",
  "data": {
    "access_token": "eyJraWQiOiJ...",
    "token_type": "Bearer",
    "expire_in": 3600,
    "roles": ["ROLE_CLIENT"],
    "permissions": ["screen:read", "screen:write"]
  }
}

Use the returned access_token in the Authorization header of all subsequent API calls. See the Authentication guide for details.

Step 3: Make Your First API Call

Use the token to screen a customer:

cURL

curl -X POST AML_CORE/amlcore/api/v1/screen-entity \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "John Smith"
  }'

Step 4: Interpret the Response

All API responses follow a standard structure. Here's how to read them:

Response Format

All endpoints return the standard ApiResponse<T> wrapper on success with data containing the domain object, and application/problem+json on errors with structured error details.

Success Response

Successful requests return a JSON envelope containing the endpoint payload in data:

JSON

{
  "timestamp": "2026-04-14T12:00:00Z",
  "status": 200,
  "message": "Success",
  "correlationId": "fl-abc123",
  "data": {
    "searchId": "srch_a1b2c3",
    "query": {
      "name": "John Smith",
      "alias": null,
      "threshold": 75.0
    },
    "totalMatches": 0,
    "truncated": false,
    "matches": [],
    "screenedAt": "2026-04-14T12:00:01Z"
  }
}

Field	Description
timestamp	UTC time the response was generated
status	HTTP status code (mirrored in the body)
message	Human-readable result description
correlationId	Unique tracing ID for debugging
data	Endpoint-specific payload (varies per call)

Error Response

Don't Retry on 4xx Errors

Client errors (400, 401, 403, 404, 422) indicate a problem with your request. Fix the issue before retrying.

Errors use the RFC 7807 Problem Details format with a correlationId for tracing:

JSON

{
  "type": "https://api.floodlight.local/problems/validation-failed",
  "title": "Bad Request",
  "status": 400,
  "detail": "One or more fields are invalid.",
  "instance": "/amlcore/api/v1/screen-entity",
  "timestamp": "2026-04-14T12:00:00Z",
  "correlationId": "fl-abc123",
  "errors": [
    {
      "field": "fullName",
      "code": "NotBlank",
      "message": "Full name is required"
    }
  ]
}

Always include the correlationId when contacting support — it helps us trace the request across services.

What's Next?

Authentication — Learn about Bearer tokens and OAuth flows
API Reference — Explore all available endpoints

Getting Started

Get up and running with the Floodlight AML API in under 5 minutes.

Prerequisites

A Floodlight AML account (Sign up here)
Your OAuth client credentials (IAM → OAuth Clients in the Dashboard)

URL Placeholders

{AUTH_URL} — Auth API

https://dev.auth-api.scytalesystems.tech (dev) | https://auth-api.scytalesystems.tech (prod)

{AML_CORE_URL} — AML Core API

https://dev.aml-core-api.scytalesystems.tech (dev) | https://aml-core-api.scytalesystems.tech (prod)

Step 1: Get Your Client Credentials

Log into your Dashboard and navigate to IAM → OAuth Clients. Create a new OAuth client and copy the client_id and client_secret — the secret is only shown once.

⚠️ Security Notice: Never expose your client secret in client-side code or public repositories. Use environment variables to store credentials securely.

Step 2: Get an Access Token

Exchange your credentials for a JWT access token via the client login endpoint:

cURL

curl -X POST 'AUTH_URL/auth/api/v1/client-login' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET"
}'

Response:

JSON

{
  "timestamp": "2026-06-01T14:12:22.942100055Z",
  "status": 200,
  "message": "Client authenticated",
  "correlationId": "df6a9da7-156f-466f-845a-d888ca25885c",
  "data": {
    "access_token": "eyJraWQiOiJ...",
    "token_type": "Bearer",
    "expire_in": 3600,
    "roles": ["ROLE_CLIENT"],
    "permissions": ["screen:read", "screen:write"]
  }
}

Use the returned access_token in the Authorization header of all subsequent API calls. See the Authentication guide for details.

Step 3: Make Your First API Call

Use the token to screen a customer:

cURL

curl -X POST AML_CORE/amlcore/api/v1/screen-entity \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "John Smith"
  }'

Step 4: Interpret the Response

All API responses follow a standard structure. Here's how to read them:

Response Format

All endpoints return the standard ApiResponse<T> wrapper on success with data containing the domain object, and application/problem+json on errors with structured error details.

Success Response

Successful requests return a JSON envelope containing the endpoint payload in data:

JSON

{
  "timestamp": "2026-04-14T12:00:00Z",
  "status": 200,
  "message": "Success",
  "correlationId": "fl-abc123",
  "data": {
    "searchId": "srch_a1b2c3",
    "query": {
      "name": "John Smith",
      "alias": null,
      "threshold": 75.0
    },
    "totalMatches": 0,
    "truncated": false,
    "matches": [],
    "screenedAt": "2026-04-14T12:00:01Z"
  }
}

Field	Description
timestamp	UTC time the response was generated
status	HTTP status code (mirrored in the body)
message	Human-readable result description
correlationId	Unique tracing ID for debugging
data	Endpoint-specific payload (varies per call)

Error Response

Don't Retry on 4xx Errors

Client errors (400, 401, 403, 404, 422) indicate a problem with your request. Fix the issue before retrying.

Errors use the RFC 7807 Problem Details format with a correlationId for tracing:

JSON

{
  "type": "https://api.floodlight.local/problems/validation-failed",
  "title": "Bad Request",
  "status": 400,
  "detail": "One or more fields are invalid.",
  "instance": "/amlcore/api/v1/screen-entity",
  "timestamp": "2026-04-14T12:00:00Z",
  "correlationId": "fl-abc123",
  "errors": [
    {
      "field": "fullName",
      "code": "NotBlank",
      "message": "Full name is required"
    }
  ]
}

Always include the correlationId when contacting support — it helps us trace the request across services.

What's Next?

Authentication — Learn about Bearer tokens and OAuth flows
API Reference — Explore all available endpoints