# Get a user field definition

Read one user field's definition by its key or ID, to check its name, type and default before you write values.

- Endpoint: `GET https://api.returning.ai/v1/communities/{communityId}/user-fields/{fieldIdOrName}`
- 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/get-a-user-field-definition

## When to use this

- Before you write a trader's value, confirm the field's type so the value suits it.
- After you create or update a field, read it back to check what was saved.
- Your integration stores field keys and you want to check that one still exists.

**Instead:** Use [List user field definitions](https://docs.returning.ai/api-reference/user-fields/list-user-field-definitions.md) instead to see every field in your community at once.

## 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

This returns the field's definition, not any trader's value. It works for built-in fields, such as `email` or `total_xp`, as well as your own. Look the field up by its key or by its `_id`; the display name is not accepted.

## 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) |
| `fieldIdOrName` | `string` | Yes | The field key, or the definition's `_id`. Not the display name. Capitals and spaces are cleaned up as on create, so `KYCStatus` finds `kycstatus`. (Field key or 24-character ID) |

### 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/kycstatus \
  --header 'Authorization: Bearer <API_KEY>'
```

## Response

A `200` returns the definition in `data`. Branch on the HTTP status and `meta.code`, never on `message`. Check `type` before you write a value, and `isCustom` before you try to update the field: built-in fields can't be changed.

**Note:** The definition may also include a `creator` object naming the account that created it. 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_FIELD_RETRIEVED`) |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |
| `data` | `object` | always | The field's definition. |
| `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` | always | `true` for fields your community created, `false` for built-in fields. Only custom fields can be updated. |
| `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_FIELD_RETRIEVED"
  },
  "message": "Read user field api success.",
  "data": {
    "_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`, except a `fieldIdOrName` that isn't a valid key or ID: that returns `400` with a `detail` object and no code. A `404` means the key doesn't exist in your community.

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | - | `fieldIdOrName` isn't a valid key or ID: after cleanup it must be 1-120 characters of `a-z`, `0-9`, `_` and `-`. `detail` names the problem. This error has no code. |
| 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 | `USER_FIELD_NOT_FOUND` | No field in your community has this key or ID. Check the key with List user field definitions before you create a field with it. |
| 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 field 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

- [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`. Write a trader's value that suits the field's `type`.
- [Rename it or change its type with Update a user field definition](https://docs.returning.ai/api-reference/user-fields/update-a-user-field-definition.md): `PUT /v1/communities/{communityId}/user-fields/{fieldIdOrName}`.