# List user field definitions

List every user field in your community, built-in and custom, with the key, type and default you need before you write values.

- Endpoint: `GET https://api.returning.ai/v1/communities/{communityId}/user-fields`
- Section: Users and data / User fields
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `userFields` (Shown in the dashboard as "User Fields")
- 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/user-fields/list-user-field-definitions

## When to use this

- You are setting up an integration and need the exact key and type of each field, such as `kycstatus`.
- Before you create a field, check that its key or name is not already taken.
- You want to confirm a field's type before you write a trader's value.

**Instead:** Use [Get a user field definition](https://docs.returning.ai/api-reference/user-fields/get-a-user-field-definition.md) instead to read one field by its key.

## Authentication

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

Use a Community API key with the `userFields` permission, and keep it on your server. The key only reads its own community: `communityId` must be the ID of the community that owns the key.

## Behaviour

Every community has built-in fields, such as `email`, `total_xp` and `total_coins`, next to the fields you create. They come first in `data`, with `isCustom: false`; your own fields follow, newest first. The whole list comes back in one response.

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `communityId` | `string` | Yes | Your community's ID. It must be the community that owns your API key. (24 hex characters) |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `isCustom` | `boolean` | No | `true` returns only your custom fields. Omit it, or send `false`, to include built-in fields too. (`true`, `false`, `1` or `0`; default `false`) |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key with `userFields`. (`Bearer <API_KEY>`) |

### Example request

```bash
curl --request GET \
  --url https://api.returning.ai/v1/communities/66f000000000000000000010/user-fields \
  --header 'Authorization: Bearer <API_KEY>'
```

## Response

A `200` returns the definitions in `data`. Branch on the HTTP status and `meta.code`, never on `message`. Save each field's `field` key: it is what value writes and history reads take, and it never changes, while `name` can be renamed.

**Note:** Definitions may also include a `creator` object naming the account that created them. Build against the fields listed here.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `meta` | `object` | always | - |
| `meta.status` | `string` | always | `success` |
| `meta.statusCode` | `integer` | always | `200` |
| `meta.code` | `string` | always | Machine-readable result code. (`USER_FIELDS_LISTED`) |
| `meta.total` | `integer` | always | Number of definitions in `data`. |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |
| `data` | `object[]` | always | Every definition, built-in fields first, then custom fields newest first. Not paginated. |
| `data._id` | `string` | always | The definition's ID. Accepted wherever a field key is. (`^[0-9a-fA-F]{24}$`) |
| `data.name` | `string` | always | Display name shown in the dashboard. It can be renamed, so do not build on it. |
| `data.field` | `string` | always | The field key. Use it in every value write and history read. It never changes. (`a-z`, `0-9`, `_`, `-`; up to 120 chars) |
| `data.type` | `string` | always | The field type. It decides which values you can write. (`single-line-text`, `multi-line-text`, `numerical`, `date`, `time`, `date-time`, `boolean`, `single-select-dropdown`, `multi-select-dropdown`) |
| `data.defaultValue` | `any` | - | The default, in the field's type. `null` or left out when there is none. |
| `data.isCustom` | `boolean` | - | `true` for fields your community created, `false` for built-in fields. |
| `data.createdAt` | `string` | - | When the definition was created. |
| `data.updatedAt` | `string` | - | When the definition last changed. |

### Example response (200)

```json
{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "USER_FIELDS_LISTED",
    "total": 2
  },
  "message": "Read user fields api success.",
  "data": [
    {
      "_id": "66f000000000000000000513",
      "name": "Email",
      "field": "email",
      "type": "single-line-text",
      "isCustom": false,
      "createdAt": "2026-09-01T08:30:00.000Z",
      "updatedAt": "2026-09-01T08:30:00.000Z"
    },
    {
      "_id": "66f000000000000000000510",
      "name": "KYC status",
      "field": "kycstatus",
      "type": "single-line-text",
      "isCustom": true,
      "createdAt": "2026-09-26T08:30:00.000Z",
      "updatedAt": "2026-09-26T08:30:00.000Z"
    }
  ]
}
```

## Errors

Every error carries its code in `meta.code`. An `isCustom` value other than `true`, `false`, `1` or `0` returns `400` with a `detail` object and no code.

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 401 | `AUTHENTICATION_REQUIRED` | The key is missing, invalid or expired. Send `Authorization: Bearer <API_KEY>` with a current Community API key. |
| 403 | `API_KEY_PERMISSION_DENIED` | The key lacks `userFields`. Add the permission in Settings > Integration > API Keys. |
| 403 | `API_KEY_COMMUNITY_MISMATCH` | `communityId` is not the community that owns your key. Use your own community's ID. |

### Fix the data

| Status | Code | What to do |
| --- | --- | --- |
| 404 | `COMMUNITY_NOT_FOUND` | The community this key belongs to no longer exists. Contact Returning.AI support. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | `USER_FIELD_OPERATION_FAILED` | The list could not be read. Retry the same request with exponential backoff. |

**Retries:** This endpoint is read-only, so retrying the exact same request is safe after a network error or a `500`. Use bounded exponential backoff. 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

- [Create a user field definition](https://docs.returning.ai/api-reference/user-fields/create-a-user-field-definition.md): `POST /v1/communities/{communityId}/user-fields`. Missing a field? Create it, then store the key it returns.
- [Write a trader's value with Update a user field value](https://docs.returning.ai/api-reference/user-fields-user-field-history/update-a-user-field-value.md): `POST /v1/communities/{communityId}/users/{userId}/user-fields/{fieldIdOrName}/histories`.