# Get User Data

Look up one trader in your community by email or platform user ID, and get back their profile, roles, coins, XP and the custom fields you ask for.

- Endpoint: `POST https://api.returning.ai/v1/users/info`
- Section: Users and data / Users
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `getUserData` (Shown in the dashboard as "Get User Data")
- Retries: Read-only; exact retries are safe
- Guide: hand-written
- Verified: live, 2026-09-27
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/users/get-user-data

## When to use this

- Confirm a trader exists after Create User or a registration webhook, and save their `userId`.
- Read a trader's current coins, XP and roles before support changes anything.
- Fetch a broker identifier such as `customerid` before you write user-field values.

**Instead:** Use [Update User Data](https://docs.returning.ai/api-reference/users/update-user-data.md) instead when you need to change a profile, roles or the trader's identifier.

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `getUserData`

Use a Community API key from **Settings > Integration > API Keys** and keep it on your server. The key limits every lookup to its own community, so a trader in another community returns `404 USER_NOT_FOUND`.

## Request

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key with `getUserData`. (`Bearer <API_KEY>`) |
| `Content-Type` | `string` | Yes | Request body format. (`application/json`) |

### Body

Send exactly one of `idOrEmail` or `identifier`. Sending neither or both returns `400`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `idOrEmail` | `string` | one of | The trader's email address or numeric platform user ID. (Email, or decimal digits. Send exactly one of `idOrEmail` or `identifier`.) |
| `customFields` | `string[]` | No | Custom field keys to return in `data.customFields`. Ask only for the fields you need. (Keys configured in your community) |
| `identifier` | `object` | one of | Structured lookup. Send instead of `idOrEmail`. (Send exactly one of `idOrEmail` or `identifier`) |
| `identifier.key` | `string` | Yes | `id` for the platform user ID, or the key of a custom single-line text or numerical user field, usually your broker identifier such as `customerid`. (`id`, or a custom text or number field key) |
| `identifier.value` | `string` | Yes | The identifier value to match. |

### Example request

```bash
curl --request POST \
  --url https://api.returning.ai/v1/users/info \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "idOrEmail": "trader@example.com",
    "customFields": ["customerid"]
  }'
```

## Response

A `200` returns the trader in the `data` object. Branch on the HTTP status and `code`, never on `message`. Save `data.userId` for the next call.

**Note:** Responses also include profile, tier, language, streak and activity fields. Build against the fields listed here.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `status` | `string` | always | Result of the request. (`success`) |
| `code` | `string` | always | Machine-readable result code. (`USER_DATA_RETRIEVED`) |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |
| `data` | `object` | always | The trader. |
| `data._id` | `string` | always | Internal record ID. |
| `data.userId` | `string` | always | Platform user ID. Store it as a string and never do arithmetic on it. (Decimal digits) |
| `data.username` | `string` | always | The trader's username. |
| `data.xp` | `number` | always | Current XP balance. |
| `data.coins` | `number` | always | Current coin balance. |
| `data.roles` | `string[]` | always | Roles the trader holds in this community. |
| `data.highestRole` | `string` | always | The trader's highest role. |
| `data.customFields` | `object` | always | The requested custom fields, keyed by field key. (Only keys you requested) |

### Example response (200)

```json
{
  "status": "success",
  "code": "USER_DATA_RETRIEVED",
  "message": "User data retrieved successfully",
  "data": {
    "_id": "<userObjectId>",
    "userId": "3247779",
    "username": "sample_trader",
    "xp": 0,
    "coins": 0,
    "roles": ["@all"],
    "highestRole": "@all",
    "customFields": {
      "customerid": "<brokerCustomerId>"
    }
  }
}
```

## Errors

401 and 403 responses carry the code in `meta.code`. The `400` for sending neither or both lookups has no code; every other error carries it in `code`.

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | - | You sent neither or both of `idOrEmail` and `identifier`. There is no `code`; `detail.identifier` says which. Send exactly one. |
| 400 | `CUSTOM_FIELD_IDENTIFIER_NOT_FOUND` | No custom user field has this key. Built-in fields such as `country` aren't accepted. Correct the key, or look up by email or platform user ID. |
| 400 | `CUSTOM_FIELD_IDENTIFIER_UNSUPPORTED_TYPE` | The identifier field isn't a single-line text or numerical field. Look up by email or platform user ID instead. |
| 400 | `CUSTOM_FIELD_IDENTIFIER_INVALID_VALUE` | The value is empty, or isn't a number for a numerical field. Correct it and retry. |
| 400 | `INVALID_CUSTOM_FIELDS` | A key in `customFields` is not valid. Check the keys against your community's user fields. |
| 401 | `AUTHENTICATION_REQUIRED` | The key is missing, malformed, invalid or expired. Send `Authorization: Bearer <API_KEY>` with a current key. |
| 403 | `API_KEY_PERMISSION_DENIED` | The key is valid but lacks `getUserData`. Add the permission in Settings > Integration > API Keys. |

### Fix the data

| Status | Code | What to do |
| --- | --- | --- |
| 404 | `USER_NOT_FOUND` | No active trader in this community matches. Check the email or ID; do not retry against other communities. |
| 409 | `CUSTOM_FIELD_IDENTIFIER_DUPLICATE` | More than one trader has that identifier value. Look up by email or platform user ID instead. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | `USER_DATA_RETRIEVAL_FAILED` | Retry the same request with exponential backoff. Keep the identifier and time for support. |
| 503 | `CUSTOM_FIELD_IDENTIFIER_NOT_READY` | Custom identifier lookup is unavailable, for example for a field created in the last few minutes. Use email or platform user ID, or retry with backoff. |

**Retries:** This endpoint is read-only, so retrying the exact same request is safe after a network error or a 5xx. Use bounded exponential backoff and keep the identifier unchanged between retries. Over the [rate limit](https://docs.returning.ai/how-it-works.md#rate-limits), requests return `429`; wait for the window to reset, then retry.

## Next step

- [Update User Data](https://docs.returning.ai/api-reference/users/update-user-data.md): `POST /v1/users/update`. Change a trader's profile, roles or identifier using the `userId` you just read.
- [New trader? Create User](https://docs.returning.ai/api-reference/users/create-user.md): `POST /v1/users`.