> 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/list-values.md).

# List Values

Reference for reading the values a person's department, office, practice area, level and law school can be set to, so you can match your own values to Flo's before importing people.

**Endpoints**

| Method | Path                    | Purpose                                                                                       |
| ------ | ----------------------- | --------------------------------------------------------------------------------------------- |
| `GET`  | `/users/departments`    | Returns the departments set up in Flo.                                                        |
| `GET`  | `/users/offices`        | Returns the offices set up in Flo, each as one name such as `Dallas, Texas`.                  |
| `GET`  | `/users/practice-areas` | Returns Flo's standard practice areas, plus any custom practice areas when those are enabled. |
| `GET`  | `/users/levels`         | Returns the levels set up in Flo.                                                             |
| `GET`  | `/law-schools`          | Returns Flo's list of law schools, with a stable `id` for each.                               |

None of the endpoints takes a request body.

**Authorization**

* All five endpoints accept your API key or an administrator session.
* Send an API key as `Authorization: Bearer <key>`.
* Send a session as the session cookie returned by the login endpoint, the same scheme as `/members/import-csv`.

**List departments, offices, practice areas and levels**

`GET /users/departments`, `GET /users/offices`, `GET /users/practice-areas` and `GET /users/levels` all work the same way.

**Query parameters**

| Parameter   | Type    | Required | Notes                                                                                                     |
| ----------- | ------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `page_size` | integer | No       | How many values to return in one page. Accepts 1 to 1000. Defaults to 1000.                               |
| `after`     | string  | No       | The `nextCursor` from your previous page of the same list. Omit it to start at the beginning of the list. |

**Paging**

* Values come back in **alphabetical order, ignoring case**.
* Request a page, then pass the `nextCursor` from the response back as `after` to get the next one. Stop when `nextCursor` is `null`.
* Paging through a list returns each value exactly once. A value removed while you are paging does not stop the cursor that follows it from working.
* Treat `nextCursor` as opaque. Its contents are not part of the contract and can change.
* A cursor only works on the list that returned it. Passing it to a different list returns `400` with `code` `INVALID_CURSOR`.
* Most lists come back whole in the first response.

**What each list holds**

* **Departments, offices and levels** are the ones your administrators have set up in Flo.
* **Offices** are each one name made of a city and its state, or a city and its country, such as `Dallas, Texas` or `London, United Kingdom`.
* **Practice areas** are Flo's standard practice areas, plus your own custom practice areas when custom practice areas are enabled. Contact your Flo representative to have custom practice areas enabled.

**Success response**

`200 OK` with:

```json
{
  "data": [
    { "name": "Corporate" },
    { "name": "Litigation" }
  ],
  "nextCursor": null
}
```

| Field        | Type             | Notes                                                                                  |
| ------------ | ---------------- | -------------------------------------------------------------------------------------- |
| `data`       | array of value   | Always present. An empty list is `[]`.                                                 |
| `nextCursor` | string or `null` | Always present. `null` on the last page. Pass it back as `after` to get the next page. |

Each value in `data`:

| Field  | Type   | Notes                                                                                                          |
| ------ | ------ | -------------------------------------------------------------------------------------------------------------- |
| `name` | string | Always present. The value exactly as Flo accepts it for a person, including spelling, punctuation and spacing. |

**List law schools: `GET /law-schools`**

**Query parameters**

The same `page_size` and `after` parameters as the lists above.

**Paging**

The same as the lists above. Law schools come back in alphabetical order, ignoring case.

**What the list holds**

* Flo's list of law schools. It is the same for every Flo customer, and new law schools are added over time.

**Success response**

`200 OK` with:

```json
{
  "data": [
    {
      "id": "3f6c2b1a-8d4e-4a7b-9c2d-1e5f7a8b9c0d",
      "name": "American University Washington College of Law"
    },
    {
      "id": "8a1d4e7c-2b9f-4c3a-a6e5-0f1b2c3d4e5f",
      "name": "Boston University School of Law"
    }
  ],
  "nextCursor": "TEFXX1NDSE9PTDpCb3N0b24gVW5pdmVyc2l0eSBTY2hvb2wgb2YgTGF3"
}
```

| Field        | Type                | Notes                                                                                  |
| ------------ | ------------------- | -------------------------------------------------------------------------------------- |
| `data`       | array of law school | Always present. An empty page is `[]`.                                                 |
| `nextCursor` | string or `null`    | Always present. `null` on the last page. Pass it back as `after` to get the next page. |

Each law school in `data`:

| Field  | Type          | Notes                                                                                                                      |
| ------ | ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `id`   | string (UUID) | Always present. Stable: it does not change when the law school is renamed. Store this against your own records.            |
| `name` | string        | Always present. The law school's name exactly as Flo accepts it for a person, including spelling, punctuation and spacing. |

**Error responses**

Every error is a JSON object in the Problem Details format (RFC 9457), sent with `Content-Type: application/problem+json`. Branch on `code`. `detail` is written for a person reading a log and may change.

```json
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "`page_size` is not usable: Must be between 1 and 1000.",
  "code": "INVALID_PARAMETER",
  "errors": [{ "field": "page_size", "code": "INVALID_PARAMETER", "message": "Must be between 1 and 1000." }]
}
```

| Field    | Notes                                                                                               |
| -------- | --------------------------------------------------------------------------------------------------- |
| `code`   | Stable identifier for the problem. Match on this. New codes may be added, so keep a default branch. |
| `detail` | A sentence explaining this occurrence, for a person reading a log.                                  |
| `errors` | Present only when particular parameters failed. Each entry has `field`, `code` and `message`.       |
| `status` | The HTTP status, repeated. `title` is its reason phrase, and `type` is always `about:blank`.        |

| Status | Endpoint | `code`                | Meaning                                                                                          |
| ------ | -------- | --------------------- | ------------------------------------------------------------------------------------------------ |
| `400`  | All      | `INVALID_PARAMETER`   | `page_size` is outside 1 to 1000 or is not a number.                                             |
| `400`  | All      | `INVALID_CURSOR`      | `after` is not a usable cursor: this endpoint did not issue it.                                  |
| `401`  | All      | `UNAUTHORIZED`        | No valid session or API key.                                                                     |
| `403`  | All      | `FORBIDDEN`           | The session is not an administrator.                                                             |
| `503`  | All      | `SERVICE_UNAVAILABLE` | Requests made with an API key are temporarily unavailable. Retry later; your key is still valid. |
| `500`  | All      | none                  | Unexpected server error. This response is not a Problem Details body.                            |

**Using these lists with the member import**

These are the values the [Members CSV Import](https://docs.joinflo.com/flo-apis/user-api/members-csv-import.md) accepts:

| CSV column                                      | List                        | How the import matches                                                                                                                                                                                                                                                                                        |
| ----------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Department**                                  | `GET /users/departments`    | Exactly, including case.                                                                                                                                                                                                                                                                                      |
| **Office City / Office State / Office Country** | `GET /users/offices`        | The import joins Office City and Office State (or Office Country) with a comma and a space, and matches the result exactly, including case. Split an office name at its first comma and space: the part before goes in Office City, and the rest in Office State for a US office or Office Country otherwise. |
| **Practice Area**                               | `GET /users/practice-areas` | Exactly, including case.                                                                                                                                                                                                                                                                                      |
| **Level**                                       | `GET /users/levels`         | Ignoring case.                                                                                                                                                                                                                                                                                                |
| **Law School**                                  | `GET /law-schools`          | Exactly, including case.                                                                                                                                                                                                                                                                                      |

**Recommended workflow**

1. Before an import, page through each list you need, passing each response's `nextCursor` back as `after`, until `nextCursor` is `null`.
2. Map your own values to Flo's, following the matching rules above.
3. Fetch the lists again before each large import rather than caching them long-term.

**Things to be careful about**

* **Match case.** Departments, offices, practice areas and law schools must match exactly, including case. Only levels ignore case.
* **Lists change.** Administrators add and rename departments, offices, practice areas and levels, and Flo adds law schools over time.
* **Most values are names, not ids.** A renamed department or office has a new name, so store the name and refresh it. Law schools carry a stable `id`; store it against your records.
* **Custom practice areas need to be enabled.** When they are not, only Flo's standard practice areas are listed and accepted.
* **Lists belong to one Flo environment.** Values set up in a test environment may not exist in production.

**Example: curl**

List departments:

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

List law schools, 500 at a time:

```bash
curl -X GET 'https://api.florecruit.com/v1/law-schools?page_size=500' \
  -H 'Authorization: Bearer <your API key>'
```

Get the next page:

```bash
curl -X GET 'https://api.florecruit.com/v1/law-schools?page_size=500&after=<nextCursor from the previous response>' \
  -H 'Authorization: Bearer <your API key>'
```

With an administrator session instead of a key, replace the `-H` line with `-b 'FLOAUTH=<your session token>'`.

**Common pitfalls**

| Symptom                                         | Likely cause                                                                                                |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `400 INVALID_CURSOR` on a page request          | The cursor came from a different list. Pass each list its own `nextCursor`, or start again without `after`. |
| `400 INVALID_PARAMETER` on the first request    | `page_size` is outside 1 to 1000, or is not a number.                                                       |
| `401 UNAUTHORIZED` on every call                | The key or session is missing, revoked or expired, or the key belongs to another Flo environment.           |
| `403 FORBIDDEN` on every call                   | The session is not an administrator.                                                                        |
| A value from the list is rejected by the import | Its case differs from the list, or an office was split into the wrong columns.                              |
| A custom practice area is missing from the list | Custom practice areas are not enabled.                                                                      |
