> 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-and-get-users.md).

# List and Get Users

Reference for reading the people at your organization: list them a page at a time, or fetch one person by id.

#### Endpoints

| Method | Path          | Purpose                                                                  |
| ------ | ------------- | ------------------------------------------------------------------------ |
| `GET`  | `/users`      | Returns the people at your organization, a page at a time, oldest first. |
| `GET`  | `/users/{id}` | Returns one person by the `id` that `GET /users` returned for them.      |

Neither endpoint takes a request body.

#### Authorization

* Both endpoints accept your organization's 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`.
* Reading people needs no further access, so you can build and test this side before API access for writing is enabled.

#### List users: `GET /users`

**Query parameters**

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

**Paging**

* People come back **oldest first**, and that order does not change between requests.
* 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 the whole list returns each person exactly once. A person added while you are paging appears on a later page or not at all; nobody you have already seen shifts position.
* Treat `nextCursor` as opaque. Its contents are not part of the contract and can change.
* If the person a cursor points to is removed from your organization before you use it, that cursor stops working and returns `400` with `code` `INVALID_CURSOR`. Start the run again without `after`.

**Who is included**

* Everyone with a user record at your organization, **whether or not they currently have access to a product**. A member removed with `DELETE /members/bulk-remove` keeps their user record and still appears.
* A person can be absent from this list, so do not assume your whole organization appears. Store the `id` of everyone you do match and carry it between runs, rather than rebuilding the mapping from names or emails each time.

**Success response**

`200 OK` with:

```json
{
  "data": [
    {
      "id": "9c1f6a52-3e4b-4d18-9f77-0a5b2c6d8e30",
      "firstName": "Dana",
      "lastName": "Whitfield",
      "email": "dana.whitfield@example.com"
    }
  ],
  "nextCursor": "OWMxZjZhNTItM2U0Yi00ZDE4LTlmNzctMGE1YjJjNmQ4ZTMw"
}
```

| Field        | Type             | Notes                                                                                  |
| ------------ | ---------------- | -------------------------------------------------------------------------------------- |
| `data`       | array of person  | 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 person in `data`:

| Field       | Type          | Notes                                                                                                                                                    |
| ----------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | string (UUID) | Always present. Stable: it does not change when the person is renamed or their email changes. Store this against your own records.                       |
| `firstName` | string        | The person's first name as your administrators see it in Flo. Omitted when the record has no first name.                                                 |
| `lastName`  | string        | The person's last name as your administrators see it in Flo. Omitted when the record has no last name.                                                   |
| `email`     | string        | The person's work email at your organization. Not guaranteed unique within your organization, and not guaranteed present. Omitted when none is recorded. |

#### Get a user: `GET /users/{id}`

**Path parameters**

| Parameter | Type          | Required | Notes                                           |
| --------- | ------------- | -------- | ----------------------------------------------- |
| `id`      | string (UUID) | Yes      | The person's `id`, as returned by `GET /users`. |

**Success response**

`200 OK` with the same person object that `GET /users` returns for them:

```json
{
  "id": "9c1f6a52-3e4b-4d18-9f77-0a5b2c6d8e30",
  "firstName": "Dana",
  "lastName": "Whitfield",
  "email": "dana.whitfield@example.com"
}
```

An `id` that names nobody at your organization returns `404`. That covers an id that was never issued and a person whose user record has since been deleted. The response does not say which.

#### 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": "`id` is not a UUID.",
  "code": "INVALID_UUID",
  "errors": [{ "field": "id", "code": "INVALID_UUID", "message": "Must be a UUID." }]
}
```

| 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`  | `GET /users`      | `INVALID_PARAMETER`   | `page_size` is outside 1 to 1000 or is not a number.                                                        |
| `400`  | `GET /users`      | `INVALID_CURSOR`      | `after` is not a usable cursor: this endpoint did not issue it, or the person it names is no longer listed. |
| `400`  | `GET /users/{id}` | `INVALID_UUID`        | `id` is not a UUID. A request made with an API key gets `403` instead.                                      |
| `401`  | Both              | `UNAUTHORIZED`        | No valid session or API key.                                                                                |
| `403`  | Both              | `FORBIDDEN`           | The session is not an administrator of this organization.                                                   |
| `404`  | `GET /users/{id}` | `NOT_FOUND`           | No person at your organization has that id.                                                                 |
| `503`  | Both              | `SERVICE_UNAVAILABLE` | Requests made with an API key are temporarily unavailable. Retry later; your key is still valid.            |
| `500`  | Both              | none                  | Unexpected server error. This response is not a Problem Details body.                                       |

#### Recommended workflow

1. Page through `GET /users`, passing each response's `nextCursor` back as `after`, until `nextCursor` is `null`.
2. Match each person to your own records, by email on the first run. Store Flo's `id` against each record you match.
3. On later runs, refresh the whole list the same way, or call `GET /users/{id}` for the individual people you need.
4. Treat a `404` from `GET /users/{id}` as "this person is no longer at the organization in Flo", and reconcile that record on your side.

#### Things to be careful about

* **Match on `id` once you have it.** Use email only for the first match, then store and use the `id`. Email is neither guaranteed unique within your organization nor guaranteed present.
* **Missing values are omitted, not `null`.** A person with no first name has no `firstName` key at all. `nextCursor` is the exception: it is always present.
* **Product access is not a filter.** People without access to any product still appear. Use the member import and bulk remove endpoints to manage access.
* **Cursors point at a person.** If that person is removed mid-run, the cursor returns `400` with `code` `INVALID_CURSOR`. Restart from the beginning without `after`.
* **Ids belong to one Flo environment.** An id from a test environment does not exist in production, and returns `404` there.

#### Example: curl

List the first page:

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

Get the next page:

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

Get one person:

```bash
curl -X GET 'https://api.florecruit.com/v1/users/9c1f6a52-3e4b-4d18-9f77-0a5b2c6d8e30' \
  -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 that worked before | The person your cursor pointed to was removed. 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 of your organization.                                         |
| `404` on `GET /users/{id}` for an id you stored             | The person's user record was deleted, or the id came from a different Flo environment.            |
| The same people come back on every page                     | `after` is not being sent, or is not the `nextCursor` from the previous response.                 |
| A person you expected is missing from the list              | Not everyone is guaranteed to appear. Reconcile them by email against your own records.           |
