Get User Milestones
Check which of the milestones you name a trader has cleared, stage by stage, using their email.
- Method
- POST
- Path
https://api.returning.ai / v1/ users/ milestones/ - Permission
- getUserData
- Retries
- Read-only; exact retries are safe
When to use this
- Show a trader's milestone progress in your own platform, such as which deposit tiers they've reached.
- Decide whether a trader qualifies for an offer that depends on a milestone you run in Returning.AI.
- Support asks whether a trader has cleared a stage.
Authentication#
- Header
Authorization: Bearer <API_KEY>- Permission
- getUserDataShown in the dashboard as “Get User Data”
This endpoint needs getUserData, shown in the dashboard as Get User Data. Use a Community API key and keep it on your server. The key decides the community: the trader and the milestones are looked up in that community only.
Behaviour#
The trader is looked up first, then the milestones, so an unknown email returns 404 even when the IDs are also wrong. One unknown ID fails the whole request with 400: there's no partial result. A disabled milestone counts as unknown. A trader you removed with Manage User Account is still found by their email.
cleared on a milestone and on each stage reflects the trader's current awards; an award that was taken back doesn't count. Disabled stages are left out of stages.
There's no endpoint that lists milestone IDs. Ask your Returning.AI contact for the IDs of the milestones you want to check.
The published path ends in /, and /v1/users/milestones without it works the same way.
Request#
Headers#
Body#
Send JSON with email and milestones. milestones is one string, such as "<milestoneId1>, <milestoneId2>", not an array.
RuleValid email
Eg"trader@example.com"
RuleNon-empty string, not an array
Eg"<milestoneId1>, <milestoneId2>"
curl --request POST \
--url https://api.returning.ai/v1/users/milestones/ \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"email": "trader@example.com",
"milestones": "<milestoneId1>, <milestoneId2>"
}'
Response#
A 200 returns one entry per milestone ID, in the order you sent them. Branch on the HTTP status, never on message. The body has no code.
Rulesuccess
true when the trader holds the award for the whole milestone.true when the trader holds the award for this stage.{
"status": "success",
"data": {
"milestones": [
{
"id": "<milestoneId1>",
"name": "Balance boosters",
"cleared": false,
"stages": [
{
"name": "USD $0 to $2,000",
"cleared": true
},
{
"name": "USD $2,000 to $5,000",
"cleared": false
}
]
},
{
"id": "<milestoneId2>",
"name": "First trade",
"cleared": true,
"stages": [
{
"name": "Open a first trade",
"cleared": true
}
]
}
]
}
}
Errors#
The 401, 403 and 404 COMMUNITY_NOT_FOUND errors, and 500 AUTHENTICATION_FAILED, come from the API key check and carry the code in meta.code. Other errors from this endpoint have no code, so branch on the HTTP status and read message.
Fix the request03
code. message Milestone not found: <ids> means no enabled milestone in your community has those IDs; it lists every ID that didn't match, so check them and send the request without them. A validation error means email isn't a valid email, or milestones is missing, empty, only commas, or an array; detail names the field.AUTHENTICATION_REQUIREDFix the requestAuthorization: Bearer <API_KEY> with a current Community API key.API_KEY_PERMISSION_DENIEDFix the requestgetUserData, or it is a personal key. Use a Community API key and add the permission in Settings > Integration > API Keys.Fix the data02
User not found: no trader in your community has this email. There is no code. Check the email, or look the trader up with Get User Data.COMMUNITY_NOT_FOUNDFix the dataRetry with backoff02
code; detail holds the reason. Retry the same request with exponential backoff.AUTHENTICATION_FAILEDRetry with backoff{
"status": "error",
"message": "Milestone not found: <milestoneId2>"
}