# How it works

Five steps connect your platform to a loyalty program your traders see inside your own portal. You send traders and their activity; we run the program and send the results back to you.

Last updated 26 Sep 2026 API v1

- [01 Register traders, Your platform to Returning.AI](#register)
- [02 Send activity, Your platform to Returning.AI](#activity)
- [03 Calculate coins, tiers and rewards, Returning.AI](#calculate)
- [04 Show it in your portal, Returning.AI to Your platform](#widget)
- [05 Get the data back, Returning.AI to Your platform](#data-back)

Steps 01 and 02 run from your systems. Steps 03 to 05 run on ours. Orange marks your activity data moving into the program.

## Register traders

Every trader needs an account before activity can count. Choose one path.

Path A

### Create User API

Call `POST /v1/users` from your backend when a trader signs up, with `externalId` set to your broker customer ID. Save the returned `userId`.

[Create User reference](https://docs.returning.ai/api-reference/users/create-user.md)

Path B

### Registration webhook

Your backend calls the handshake URL we give you with your API key, reads `data.sessionToken` (valid for 300 seconds), then posts the registration to your workflow webhook URL with the `x-session-token` header.

[Registration webhook guide](https://docs.returning.ai/broker-integrations/workflow-webhooks.md)

`Registration payload`

```json
{
  "eventType": "user.registered",
  "customerId": "<brokerCustomerId>",
  "email": "trader@example.com",
  "firstName": "Sample",
  "lastName": "Trader",
  "occurredAt": "2026-09-26T00:00:00Z"
}
```

## Send activity

Send what traders do on your platform, such as deposits and closed lots. Pick the channel that fits your data.

Push

### SQS queue

Send JSON batches to the queue we set up for you. An accepted send returns HTTP 200 and a `MessageId`: the batch is queued, then processed.

[SQS guide](https://docs.returning.ai/broker-integrations/sqs.md)

Upload

### CSV files

Upload a file to the file ingest endpoint with your `x-api-key` header and the multipart fields `data` and `metadata`. The `trigger_id` query parameter names your trigger.

[CSV files and exports](#file-ingest)

Pull

### Read-only access

Give us read-only credentials and we pull the data ourselves: MT5 Web API or Manager API (Web API enabled and our IPs allowlisted), read-only access to your FXBO SQL database, or your data warehouse such as Databricks.

[MetaTrader read-only guide](https://docs.returning.ai/broker-integrations/metatrader.md)

**File ingest**

POST `https://data-workflow.returning.ai/apis/v1/data-workflows/file-ingests?trigger_id=<triggerId>`

**Header**

`x-api-key`

**Multipart**

`data` `metadata`

`SQS message`

```json
{
  "trigger_id": "<triggerId>",
  "metadata": {
    "source": "broker-dwh",
    "batch_id": "2026-09-26-009"
  },
  "data": [
    {
      "user_id": "<brokerCustomerId>",
      "date": "2026-09-26",
      "deposit_total": 2500.00,
      "closed_lots": 14.25
    }
  ]
}
```

> Note
>
> Rows update on `user_id` + `date`, so send running totals for the day. A repeated `batch_id` is skipped as a duplicate; send corrections with a new `batch_id`.

## We calculate coins, tiers and rewards

The program rules you set in the dashboard turn each batch of activity into coins and XP, move traders through tiers, and unlock rewards in the store. There is nothing to host on your side.

Read the results at any time:

- POST [Get User Data](https://docs.returning.ai/api-reference/users/get-user-data.md) returns a trader's `coins`, `xp` and roles.
- GET [Get Tiers and XP Settings](https://docs.returning.ai/api-reference/gamification/get-tier-configuration.md) (`GET /v1/xp-settings/tiers-info`) returns your tier configuration.

## Show it in your portal

Traders see their coins, tiers, milestones and store inside your portal through the Widget SDK.

1. Install the SDK: `npm install @returningai/widget-sdk`.
2. On your server, exchange your widget access key for a short-lived embed token. Send `accessId`, `accessKey` and `userIdentifiers`; read `data.embedToken` and `data.expiresIn`.

   **Embed token**

   POST `https://api-v2.returning.ai/v2/api/widget-access-keys/token`
3. Pass only the token to the browser. Take the trader's identity from your signed-in session, never from browser input, and never send `accessKey` to the browser.

[Widget SDK guide](https://docs.returning.ai/widget-sdk.md)

`Server: token request body`

```json
{
  "accessId": "<ACCESS_ID>",
  "accessKey": "<ACCESS_KEY>",
  "userIdentifiers": {
    "data-customer-id": "<brokerCustomerId>"
  }
}
```

`Browser: embed`

```html
<rai-custom-widget
  widget-id="<WIDGET_ID>"
  embed-token="<EMBED_TOKEN>"
  bundle-url="https://prod-widgets.returning.ai/custom-widget/bundle/milestones/widget.js"
  domain-key="PROD"
  theme="dark">
</rai-custom-widget>
```

## Get the data back

Every reward, purchase and tier change flows back to you: sent to your systems as it happens, synced to the tools you already use, or read through the API whenever you need it.

Webhooks

### As it happens

We send each event to a URL on your side, so your systems can react straight away.

[Outgoing webhooks](https://dev.returning.ai/events/outgoing-webhooks)

Integrations

### In your tools

Results are synced to the tools your team already uses.

API

### Whenever you need it

Read a trader's balances and activity from your backend at any time.

[API reference](https://docs.returning.ai/api-reference/users/get-user-data.md)

## Rate limits

Rate limits are set per community. Your success manager will confirm yours. A request over the limit returns `429 Too Many Requests`; wait for the window to reset, then retry.

## Make your first call

[Get User Data POST `/v1/users/info` Look up a trader and read their coins, XP and roles.](https://docs.returning.ai/api-reference/users/get-user-data.md) [Register a trader with Create User](https://docs.returning.ai/api-reference/users/create-user.md)