> For the complete documentation index, see [llms.txt](https://docs.joinflo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.joinflo.com/flo-apis/user-api/custom-fields.md).

# Custom Fields

Custom fields are fields your administrators add to the people in your Flo organization, such as a billable-hours target, a practice group or a bar admission date. The Users API lets an integration keep those fields in step with your own system of record, so nobody has to type the values in by hand.

This page walks through a sync from start to finish. The Users API reference has every parameter, field and response in full.

#### How it fits together

1. An administrator creates the field in Flo and sets its update method to **Update Via API**.
2. Your integration reads the field's definition: its id, its type and, for a select field, its options.
3. Your integration matches your people to Flo's people and stores each person's Flo `id`.
4. Your integration sends the values, first as a dry run, then for real.

Once written, a value appears on the person's profile in Flo, where administrators can see it but not edit it. It is also available as a column and a filter in the User List.

#### Before you start

* **An API key or an administrator session.** See Authentication.
* **API access for writing.** Writing values requires API access for your organization; ask your Customer Success Manager to enable it. Reading field definitions and people needs no extra access, so you can build and test the read side first.
* **At least one field set to Update Via API.** An administrator creates it under **Settings > Custom Fields** in Flo Perform. The update method is fixed when the field is created: a field your administrators maintain by hand can never be written through the API, and an API field can never be edited by hand.

#### **Step 1: Read your field definitions with `GET /users/custom-fields`**

Call `GET /users/custom-fields` to list the fields your integration can write. You can use the same API key as the write; reading needs no API access for writing. The response holds every field set to **Update Via API**, in the order your administrators arranged them, with no paging. If none are configured, it's an empty list. Fields maintained by hand are not included.

```bash
curl 'https://api.florecruit.com/v1/users/custom-fields' \
  -H 'Authorization: Bearer <your API key>'
```

```json
[
  {
    "id": "b3f1a2c4-5d6e-4f70-8a91-2b3c4d5e6f70",
    "name": "Billable target",
    "description": "Annual billable hours target agreed at hire.",
    "type": "NUMBER",
    "options": []
  },
  {
    "id": "7e2b9c10-4a5d-4f6e-8b13-c2d4e6f8a0b1",
    "name": "Office",
    "type": "SINGLE_SELECT",
    "options": [
      { "id": "1f0c6b34-7d7a-4b0e-9a1f-3c2f9d0f4a11", "label": "Chicago" },
      { "id": "4a8e2d90-6c1b-4f3a-8e27-9b0d5c4f3a22", "label": "New York" }
    ]
  }
]
```

Keep these values from the response for every field you plan to sync:

| From the response | Use it for                                                                                    |
| ----------------- | --------------------------------------------------------------------------------------------- |
| `id`              | The `fieldId` in your write request (Step 4).                                                 |
| `type`            | Choosing the shape of `value` (see Writing each type of value).                               |
| `options[].id`    | The value you send for `SINGLE_SELECT` and `MULTI_SELECT`. Send option ids, not their labels. |
| `currency`        | The currency of a `MONETARY` amount. Only `MONETARY` fields have it.                          |

Store the `id`, not the `name`. An administrator can rename a field or option without changing its id. Call `GET /users/custom-fields` again before each sync, because options can be renamed or removed. A field that no longer appears has been deleted. If a field is recreated, it gets a new id.

#### Step 2: Match your people

Page through `GET /users` and store the Flo `id` of each person you sync. Every write names people by that `id`.

* Match on email the first time, then keep the `id` against your own record and use it from then on. Email is neither guaranteed unique within your organization nor guaranteed present.
* Refresh the list on each run, or call `GET /users/{id}` for the people you need. A person can drop off the list, so do not assume your whole organization appears.
* A person on the list may have no employment record a value can be recorded against. The write reports them as `EMPLOYMENT_RECORD_NOT_MATCHED`; reconcile them with your Flo administrators rather than retrying.

Paging, filters and every error are on List and Get Users.

#### Step 3: Rehearse with a dry run

Send the write with `dry_run=true` first. Flo runs every check the real write runs and records nothing, and the response has the same shape. `dryRun` is `true`, and `summary.written` is how many values the real write would record.

```bash
curl -X POST 'https://api.florecruit.com/v1/users/custom-field-values?dry_run=true' \
  -H 'Authorization: Bearer <your API key>' \
  -H 'Content-Type: application/json' \
  -d @values.json
```

Fix what the dry run reports, then send the same request without `dry_run`. A clean dry run does not guarantee the real write succeeds: people and fields can change in between.

To record nothing unless every value is accepted, send `on_error=abort`. A rejected value then answers `422` with the same results body a `200` carries, and nothing is recorded. The default, `on_error=continue`, records every accepted value and reports the rest.

#### Step 4: Send the values

One request writes one field, for up to 25,000 people. Send the field's `id` as `fieldId`, and one entry per person in `values`:

```bash
curl -X POST 'https://api.florecruit.com/v1/users/custom-field-values' \
  -H 'Authorization: Bearer <your API key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fieldId": "b3f1a2c4-5d6e-4f70-8a91-2b3c4d5e6f70",
    "values": [
      { "userId": "9c1f6a52-3e4b-4d18-9f77-0a5b2c6d8e30", "value": 1850 },
      { "userId": "2a7d1e88-9b03-4c51-8e6a-71d4f0b9a2c5", "value": null }
    ]
  }'
```

Every entry needs both keys. `value` takes the shape the field's `type` decides (see Writing each type of value), and `null` clears it. A person may appear only once in a request.

```json
{
  "dryRun": false,
  "summary": { "submitted": 2, "written": 1, "failed": 1 },
  "errors": [
    {
      "index": 1,
      "userId": "2a7d1e88-9b03-4c51-8e6a-71d4f0b9a2c5",
      "code": "EMPLOYMENT_RECORD_NOT_MATCHED",
      "message": "No employment record could be matched to this person, so a value cannot be recorded against them. Reconcile this person by email against your own records"
    }
  ]
}
```

**A `200` doesn't mean every value was recorded.** Partial success is the normal outcome. Always read `summary.failed`, and for each entry in `errors`, use `index` to find the value you sent and `code` to decide what to do:

| `code`                          | What to do                                                                                                                                                             |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `USER_NOT_FOUND`                | Refresh your stored ids from `GET /users`. The person may have been removed.                                                                                           |
| `EMPLOYMENT_RECORD_NOT_MATCHED` | Reconcile the person with your Flo administrators. Retrying won't help.                                                                                                |
| `DUPLICATE_USER`                | Send each person once per request. The first value sent for them is the one recorded. Two people who share one employment record in Flo also count as the same person. |
| `INVALID_VALUE`                 | Fix the value for the field's type and limits: text up to 50 characters, numbers up to 15 digits before the decimal point and 4 after.                                 |
| `OPTION_NOT_FOUND`              | Re-read the field's options; one was probably removed or never belonged to this field.                                                                                 |

Match on `code`, not on `message`. The message is written for a person reading a log and may change.

#### Writing each type of value

The field's `type` decides the shape of `value`:

| Type            | Example `value`                                                                    |
| --------------- | ---------------------------------------------------------------------------------- |
| `TEXT`          | `"Chicago office"`                                                                 |
| `NUMBER`        | `1850`                                                                             |
| `MONETARY`      | `175000.00`, in the field's `currency`                                             |
| `BOOLEAN`       | `true`                                                                             |
| `DATE`          | `"2026-03-14"`                                                                     |
| `DATE_TIME`     | `{ "dateTime": "2026-03-14T09:30:00", "timeZone": "America/New_York" }`            |
| `SINGLE_SELECT` | `"1f0c6b34-7d7a-4b0e-9a1f-3c2f9d0f4a11"`, one option id                            |
| `MULTI_SELECT`  | `["1f0c6b34-7d7a-4b0e-9a1f-3c2f9d0f4a11", "4a8e2d90-6c1b-4f3a-8e27-9b0d5c4f3a22"]` |

To **clear** a value, send `null` for any type. An empty or blank string also clears a `TEXT` field, and an empty list clears a `MULTI_SELECT`. Every entry must include the `value` key; leaving it out is an error, not a clear.

#### Running a sync on a schedule

* **Send the full value every time.** Each write replaces the person's whole value for that field, including every selected option on a `MULTI_SELECT`.
* **Retries are safe.** Sending the same request again leaves the same result. If a request fails with `409`, a field option changed while it was being written and nothing was recorded: send it again unchanged. If it fails with `503`, retry later; your key is still valid.
* **Keep your system as the source.** The Users API doesn't return the values you've written. To check what a run would change, use a dry run.
* **Split by field, not by person.** One request carries one field. To sync five fields, send five requests.

#### When a whole request is refused

These responses mean nothing was recorded. Each has a Problem Details body (`Content-Type: application/problem+json`) with a stable `code`. Match on `code`, not on `detail`. When the problem is tied to particular fields, `errors` names each one by its path, such as `values[2].userId`.

| Status | `code`                   | Usual cause                                                                                                      |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `400`  | `INVALID_JSON`           | The body is missing, isn't valid JSON, or has a field of the wrong shape.                                        |
| `400`  | `INVALID_UUID`           | `fieldId` or a `userId` isn't a UUID.                                                                            |
| `400`  | `MISSING_VALUE`          | An entry in `values` leaves out its `value` key. Send `null` to clear a value.                                   |
| `400`  | `INVALID_PARAMETER`      | `dry_run` isn't `true` or `false`, or `on_error` isn't `continue` or `abort`.                                    |
| `401`  | `UNAUTHORIZED`           | No valid API key or session.                                                                                     |
| `403`  | `FORBIDDEN`              | The request isn't allowed, for example your organization doesn't have API access for writing.                    |
| `409`  | `CONFLICT`               | A field option was removed while the values were being written. Send the same request again.                     |
| `415`  | `UNSUPPORTED_MEDIA_TYPE` | The request didn't send `Content-Type: application/json`.                                                        |
| `422`  | `VALIDATION_FAILED`      | `fieldId` or `values` is missing, an entry is `null`, or more than 25,000 values were sent. `errors` says which. |
| `422`  | `FIELD_NOT_FOUND`        | No custom field at your organization has that id.                                                                |
| `422`  | `FIELD_NOT_WRITABLE`     | The field is maintained by hand, so an integration can't write it.                                               |
| `503`  | `SERVICE_UNAVAILABLE`    | Requests made with an API key are temporarily unavailable. Retry later; your key is still valid.                 |

With `on_error=abort`, a rejected value also returns `422`, but the body is the normal results body (`Content-Type: application/json`), so read its `errors` list as you would on a `200`. Tell the two `422` bodies apart by `Content-Type`.

A `500` is an unexpected server error and does not carry a Problem Details body.
