Developer Getting Started Guide

AML HQ is a compliance platform for Anti-Money Laundering (AML) and Know Your Customer (KYC) workflows. The API lets you programmatically manage every part of that workflow: creating and maintaining client records, running identity verification, screening for politically exposed persons (PEPs) and sanctions, requesting official company registry data, and building risk assessments.

Base URLs

Use the correct base URL for your region. All paths in this guide are relative to that base.

Swagger Reference Documentation

This guide covers the conceptual model and core workflow. For exhaustive endpoint and model reference, use the interactive Swagger documentation:

Before making any API calls, understand the key entities and how they relate to each other.

Understanding Credits

Some operations consume account credits. Check your balance with GET /user/remainingcredits. Use cost endpoints to estimate before bulk operations:

• PEP / Sanction checks - GET /pepsanctionchecks/cost
• IDV Sessions - GET /idvsessions/getcost/{type}
• Address Verifications - GET /addressverifications/cost

The AML HQ API supports two authentication methods. Both grant the same access - choose based on your integration needs.

Method 1: JWT Bearer Token

Authenticate with username and password to receive a JWT token. Swagger scheme name: jwt_auth (http, Bearer).

POST /user/authenticate
Content-Type: application/json

{
  "username": "your.username",
  "password": "YourPassword1"
}

{
  "token": "eyJhbGci...",
  "tokenExpiryDate": "2025-12-31T23:59:59Z",
  "twoFactorRequired": false,
  "userDetails": { ... }
}

Authorization: Bearer eyJhbGci...

Two-Factor Authentication

If 2FA is enabled, the first call returns twoFactorRequired: true and sends a code. Re-call with the code included:

{ "username": "your.username", "password": "YourPassword1",
   "twoFactorCode": "123456" }

Method 2: API Key Authentication

Designed for server-to-server and programmatic integrations. Send two permanent headers on every request. No POST /user/authenticate call is needed. Swagger schemes: api_key_auth (X-Api-Key) and username_header (X-Username).

GET /clients/search
X-Api-Key: your-api-key-here
X-Username: api.service@yourfirm.com

Requesting an API Key

There are two ways to obtain an API key:

• Contact AML HQ directly - reach out to the team and we will provision a key for your account.
• Via the API - if you already have a valid JWT Bearer token, you can retrieve your account API keys programmatically:

GET /account/apikeys/{keynumber}
Authorization: Bearer eyJhbGci...

// Returns the API key for the given key number on your account
// Use the returned key as the X-Api-Key header value going forward

See the Swagger documentation for full details on the Account API Keys endpoints.

The natural progression for a client onboarding scenario. Each step builds on the previous one - IDs returned become inputs to subsequent calls.

Essential Endpoints at a Glance

A Client is the foundation - create it first. Identify whether the client is a company (isCorporate: true) or individual (isCorporate: false). Full model: POST /clients in Swagger.

POST /clients
Authorization: Bearer {token}  // or X-Api-Key + X-Username headers

{
  "name": "Acme Consulting Ltd",
  "isCorporate": true,
  "jurisdiction": "IE",
  "companyNumber": "123456",
  "engagementType": "BusinessAdvisory",
  "dueDiligenceLevel": "Standard",
  "skipCompanyLookup": false
}
// Response - id: 2001 - keep this

Key Client Fields

skipCompanyLookup

When skipCompanyLookup is set to true, AML HQ will not automatically retrieve information from the official company register (CRO for Ireland, Companies House for the UK, or equivalent). This means:

• The company's registered details will not be auto-populated on the Client record.
• Client Parties such as Directors and PSCs (Persons with Significant Control) will not be automatically retrieved and added to the file.

Use skipCompanyLookup: false (the default) to let AML HQ pull official register data automatically on creation. Use true when you are supplying your own data, the company is not yet registered, or the jurisdiction is not supported for automatic lookup.

Duplicate Check

Check before creating: GET /clients/checkforduplicateclient

GET /clients/checkforduplicateclient?name=Acme+Consulting&jurisdiction=IE

Client Parties are the individuals and entities associated with a Client - directors, UBOs, shareholders, authorised signatories. Compliance checks are attached at the party level. See Client controller in Swagger.

POST /clients/{clientId}/parties

{
  "name": "Jane Smith",
  "clientPartyType": "BeneficialOwner",
  "email": "jane.smith@example.com",
  "dateofBirth": "1980-05-15",
  "nationality": "IE",
  "percentageHolding": "35%",
  "levelOfInterest": "DIRECT"
}
// Response - id: 4001

Valid clientPartyType values from GET /referencedata/clientpartytypes - includes Director, BeneficialOwner, Shareholder, AuthorisedSignatory, UltimateBeneficialOwner.

Linking Checks to Parties

Three types of compliance check: PEP/Sanctions, IDV Sessions, and Address Verification. All follow the same pattern: create - await completion - review and update status.

POST /pepsanctionchecks

{
  "name": "Jane Smith",
  "isCompanyCheck": false,
  "yearOfBirth": 1980,
  "country": "IE",
  "includeOtherChecks": true
}

POST /idvsessions

{
  "idvSessionType": "Standard",
  "name": "Jane Smith",
  "email": "jane.smith@example.com",
  "captureAddress": true,
  "sendEmailLink": true
}
// Response - sessionUrl: share this link with the person

PUT /idvsessions/{id}
{ "status": "Completed", "result": "Pass",
   "resultComment": "Documents verified" }

POST /addressverifications
{ "name": "Jane Smith",
   "address": "10 High Street, London, SW1A 1AA" }

Structured risk questionnaires based on templates. Produces a risk score and level (Low / Moderate / High) that can propagate to the Client. See Assessment controller in Swagger.

GET /assessments/templates        // account templates
GET /assessments/templates/system  // system templates

POST /assessments
{ "templateId": 42, "clientId": 2001,
   "subject": "Acme Consulting Ltd",
   "propagateToClient": true }
// - assessmentId: 7001

GET /assessments/{id}/questions
PUT /assessments/{id}/answers
{ "answers": [{ "questionId": 1, "answer": "Yes" }, ...] }

POST /assessments/{id}/complete
// - riskScore: 24, riskLevel: "Low"
// Client updated if propagateToClient was true

Onboarding Acme Consulting Ltd, screening its beneficial owner, and completing a risk assessment. Follow each step in sequence.

// Option A - JWT
POST /user/authenticate
{ "username": "api.user@yourfirm.com", "password": "P@ssw0rd1" }
// - token: "eyJhbGci..."

// Option B - API Key (no auth call needed)
X-Api-Key: your-api-key
X-Username: api.user@yourfirm.com

POST /clients
{ "name": "Acme Consulting Ltd", "isCorporate": true,
   "jurisdiction": "IE", "companyNumber": "654321",
   "engagementType": "BusinessAdvisory",
   "dueDiligenceLevel": "Standard" }
// - id: 2001

POST /clients/2001/parties
{ "name": "Jane Smith", "clientPartyType": "BeneficialOwner",
   "email": "jane.smith@acme.ie", "dateofBirth": "1980-05-15",
   "percentageHolding": "35%", "levelOfInterest": "DIRECT" }
// - partyId: 4001

POST /pepsanctionchecks
{ "name": "Jane Smith", "isCompanyCheck": false,
   "yearOfBirth": 1980, "country": "IE" }
// - id: 5001, isPep: false, isSanctioned: false
POST /clients/parties/4001/pepsanctionchecks/5001

POST /idvsessions
{ "idvSessionType": "Standard", "name": "Jane Smith",
   "email": "jane.smith@acme.ie", "sendEmailLink": true }
// - idvId: 6001, sessionUrl shared with Jane - awaits completion
PUT  /idvsessions/6001  { "result": "Pass" }
POST /clients/parties/4001/idvsessions/6001

POST /assessments
{ "templateId": 42, "clientId": 2001, "propagateToClient": true }
// - assessmentId: 7001
GET  /assessments/7001/questions
PUT  /assessments/7001/answers  { "answers": [...] }
POST /assessments/7001/complete
// - riskScore: 24, riskLevel: "Low" - client 2001 updated

Many fields use controlled vocabulary - string codes that must match an approved list. Fetch once at startup and cache; values change infrequently. Full controller: ReferenceData in Swagger.

GET /referencedata  // all reference data in one payload

Data Requests and IDV Sessions are processed asynchronously. AML HQ can POST a notification to your system when processing completes.

Configuring a Webhook URL

Supply a webhookUrl at account level via PUT /account, or per-request. The per-request URL overrides the account default.

{
  "id": 9001,
  "eventDate": "2025-06-01T10:30:00Z",
  "eventType": "DataRequestCompleted",
  "dataRequestId": 300,
  "status": "Sent"
}

This section is relevant to partner integrations only. If your account has the Partner role, you can programmatically create new AML HQ accounts on behalf of your clients. A single API call creates both the account and the initial admin user, and returns an API key ready for immediate use.

POST /partner/accounts

Creates a new account and its first admin user in a single call. The response includes the new user's full account details and the account's API Key 1, which can be used immediately to make API calls on behalf of the new account.

POST /partner/accounts
Authorization: Bearer {your-partner-jwt-token}

{
  // Required
  "name": "Smith and Associates Ltd",
  "username": "admin@smithassociates.ie",
  "userFullname": "Jane Smith",
  "userEmail": "admin@smithassociates.ie",
  "userPassword": "Secure1Password",

  // Optional
  "accountType": "Accountancy",
  "countryCode": "IE",
  "billingAddress": "1 Main Street, Dublin 2",
  "billingEmail": "billing@smithassociates.ie",
  "taxId": "IE1234567A",
  "phoneNumber": "+353 1 234 5678",
  "jobTitle": "Managing Partner",
  "autoCreateTasks": false,
  "emailNotificationsEnabled": true,
  "externalEmailNotificationsEnabled": true
}

Request Fields

Response (HTTP 200)

Returns two key pieces of data: the full user profile for the new admin user, and the account's API Key 1.

{
  "userAccountDetails": {
    "username": "admin@smithassociates.ie",
    "fullname": "Jane Smith",
    "accountId": 1042,
    "accountName": "Smith and Associates Ltd",
    "accountType": "Accountancy",
    "isAccountOwner": true,
    "remainingCredits": 0,
    // ... full UserModel fields
  },
  "apiKey": "abc123-your-new-account-api-key"
}

Error Responses

A 400 response indicates a validation error - for example, a username that already exists, a password that does not meet the complexity requirements, or a missing required field.

{ "message": "Username already exists." }

Recommended Order

1. Read this guide fully to understand the conceptual model.
2. Call GET /referencedata to discover valid field values for your account.
3. Run through the end-to-end example against the test environment at https://apitest.amlhq.com.
4. Consult the Swagger documentation for full parameter details on any specific endpoint.
5. If you need an API key for server-to-server integrations, contact AML HQ to request one for your account.

Swagger Reference

Error Handling

{ "message": "Client not found or you do not have access." }

Getting an API Key

Contact the AML HQ team to request an API key for your account. See also Authentication in the Swagger docs.