Getting Started

Getting Started

Xama is an AML compliance platform. The Xama API lets your application create and manage the client records, contacts, identity verification and screening that sit behind that compliance work, so your users can stay in your product for day-to-day tasks while the detailed AML work happens in Xama.

How Xama models your data

Three terms come up throughout the API, and one of them is a common source of confusion:

Term	What it means
Client	Your Xama customer account. It appears in every path as {clientId}
Account	A client record as your users see it in the Xama interface — a company, individual or trust
Contact	An individual person associated with an account

So what the Xama interface calls a “client”, the API calls an account. The API’s {clientId} is your own tenant, and it is not the same as the OAuth client_id you authenticate with.

Before you start

1. Create an account at platform.xamatech.com
2. Collect your OAuth credentials from the Open API settings page
3. Exchange them for an access token

The Authentication guide covers all three in detail. Start there.

Making a request

All API requests go to:

https://xamahub.xamatech.com

Endpoints live under /api and are scoped to your client:

https://xamahub.xamatech.com/api/clients/{clientId}/[resource]

Once you have a token, this searches across your accounts and contacts and is a good way to confirm everything is wired up:

curl -X GET "https://xamahub.xamatech.com/api/clients/{clientId}/search?q=smith" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access_token}"

The guides

Each guide covers one integration, and they are written to be read on their own. Pick the one that matches what you are building.

Authentication — How to obtain and use an access token, where to find your credentials, and how {clientId} differs from your OAuth client_id. Read this first, whatever you are building.

Practice management integration — A recommended MVP for connecting a practice management system to Xama. Covers linking client records, surfacing risk assessment status in your own interface, and deep-linking users into Xama for the detailed work.

ID verification flow integration — How to collect ID documents, personal details and proof of address from a contact, then run AML screening. Covers onboarding levels, email templates, embedding the verification link in your own product, and reading the results back.

Client portal integration — How to give an account a single link that covers all of its outstanding onboarding tasks, instead of sending separate requests per contact.

API reference

The API Reference is the authoritative description of every public endpoint, generated from the Xama OpenAPI specification. Use the guides to understand a workflow and the reference to confirm exact field names, types and responses.

Not every endpoint in the platform is public. The reference shows the supported surface; anything absent is internal and may change without notice, so please do not build against it.

Conventions worth knowing

A few things that are easy to trip over:

• Everything inside config.parameters is a string. Send "true", not true. Xama returns these values as strings when you read a record back.
• Field names are snake_case, in both requests and responses.
• Report creation is asynchronous. Initiating an onboarding or AML report returns before the work has settled. Re-fetch after a short delay, or subscribe to webhooks, to read the final state.
• Token expiry is in the token, not the response. The token response carries no expiry field; read the exp claim from the JWT, and treat a 401 from any call as a signal to fetch a new token and retry once. See Authentication.