---
title: "Get a list of users"
method: GET
path: "/v1/users/"
tags: ["/v1/user"]
---

# Get a list of users

`GET /v1/users/`

## Request

- Base URL: `https://api.counselhealth.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.counselhealth.com/v1/users/`
- Auth: HTTP bearer

Get a paginated list of users. We use cursor-based pagination to encode the pagination state. Results are ordered by when the user was created. Default sort order is descending.

  `pageSize` is 25 by default and accepts 1 to 100.

  Follow `nextPageUrl`, or send `nextPageCursor` back as `cursor`, until it is null. Each page continues from where the last one ended, so a completed walk returns every user exactly once. Descending order starts at the newest user as of your first request; a user created partway through sorts ahead of your position and appears only in a later walk.

  The cursor is opaque. Send it back unchanged and do not store it between walks: one that cannot be decoded is rejected with `400` `invalid_request`, and the walk has to start again from the first page.

  Pass `include=subscription` to embed each user's plan, access, trial, and subscription history — the same object `GET /v1/user/{userId}/subscriptions` returns, so you can read every user's access in one page instead of one request per user. It requires the same organization entitlement as that endpoint, and returns `feature_not_enabled` (400) without it. `nextPageUrl` carries the parameter, so every page of a walk embeds the same fields.

  `subscription` is `null` for a user whose access source carries no plan; the per-user endpoint answers `no_billing_relationship` in that case, which a page of users cannot do without failing everyone else alongside them.

## Query parameters

- `pageSize` integer
- `cursor` string, nullable
- `sort` 'asc' | 'desc'
- `include` 'subscription'

## Response `200`

Default Response

- object
  - `users` object[], required
    - `id` string, uuid, required
    - `created_at` string, date-time, required: datetime in ISO 8601 format
    - `first_name` string, required
    - `last_name` string, required
    - `preferred_name` string, nullable
    - `dob` string, required: date of birth in YYYY-MM-DD format (ISO 8601)
    - `phone` string, nullable: US phone number. Supported formats: 8007006000, 800-700-6000, +1 800-700-6000, +18007006000, +1(800)7006000, (800)700-6000
    - `addresses` object[], nullable
      - `line1` string, required
      - `line2` string
      - `city` string, required
      - `state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' | 'DC', required: US state abbreviation
      - `zip` string, required: US zip code with optional 4 digit extension. Supported formats: 12345, 12345-1234
      - `metadata` object
        - `is_primary` boolean
    - `sex_assigned_at_birth` 'Male' | 'Female', required
    - `gender` 'Male' | 'Female' | 'Other', nullable
    - `body_measurements` object, nullable
      - `height_ft` integer, required
      - `height_in` integer, required
      - `weight_lbs` integer, required
    - `race` string[], nullable
    - `medical_profile` object, required
      - `conditions` string[], required
      - `medications` string[], required
      - `medication_allergies` string[]
      - `surgeries` string[]
      - `family_history` string[]
      - `doctors` object
        - `pcp_name` string
        - `pcp_last_seen` 'Within the last year' | '1-2 years ago' | '2-5 years ago' | 'Longer than that or I do not remember'
        - `specialist_types` string[]
      - `substances` object
        - `tobacco` string[]
        - `alcohol` '0-4' | '5-8' | '9-14' | '15+'
      - `additional_details` object: Pass additional medical profile details
    - `access_expires_at` string, date-time, nullable: datetime in ISO 8601 format
    - `email` string, email, nullable: email address
    - `metadata` object, nullable: Custom key-value metadata for external users. Max 25 keys, each value ≤ 1800 characters. Keys must be alphanumeric with underscores/hyphens only.
    - `onboarded_at` string, date-time, nullable: datetime in ISO 8601 format
    - `external_id` string, nullable: Client-supplied stable identifier for this user, unique within your organization. Can be used in place of the Counsel user ID on GET/PATCH /v1/user/{id}.
    - `id_verified` boolean, nullable: Whether this user's identity has been verified. Sending `true` requires your organization to be granted API identity verification by Counsel support; otherwise the request fails with 403.
    - `consents` object, required: Consent state for this user. Fields are only populated for consents the organization tracks.
      - `hipaa_authorization` boolean: Whether this user has granted HIPAA authorization consent — i.e. waived their right to HIPAA privacy protections so that PHI can be shared back to your organization. Only present when the organization requires HIPAA authorization consent. When false on such an org, API responses redact HIPAA-gated fields and PHI-rich endpoints return 403.
    - `subscription` object, nullable
      - `plan` object, required
        - `id` string, uuid, required
        - `slug` string, required
        - `display_name` string, required
        - `billing_type` 'subscription' | 'fee_for_service' | 'complimentary'
      - `access` object, required
        - `has_access` boolean, required
        - `expires_at` string, date-time, nullable, required: datetime in ISO 8601 format
        - `status` 'active' | 'pending_cancellation' | 'expired' | 'payment_failed' | 'disabled', required
      - `trial` object, nullable
        - `ends_at` string, date-time, required: datetime in ISO 8601 format
        - `status` 'active' | 'converted' | 'expired', required
      - `subscriptions` object[], required
        - `status` 'active' | 'canceled' | 'incomplete' | 'incomplete_expired' | 'past_due' | 'paused' | 'trialing' | 'unpaid', required
        - `plan_id` string, uuid, nullable, required
        - `is_trial` boolean, required
        - `cancel_at` string, date-time, nullable, required: datetime in ISO 8601 format
        - `ended_at` string, date-time, nullable, required: datetime in ISO 8601 format
        - `renews_at` string, date-time, nullable, required: datetime in ISO 8601 format
        - `created_at` string, date-time, required: datetime in ISO 8601 format
  - `nextPageUrl` string, nullable, required
  - `nextPageCursor` string, nullable, required

## Other responses

- `400`: 400 error with a machine-readable `code` for client branching.
- `401`: Standard error body returned for non-2xx responses.
- `403`: Standard error body returned for non-2xx responses.
- `404`: Standard error body returned for non-2xx responses.
- `409`: Standard error body returned for non-2xx responses.
- `413`: Standard error body returned for non-2xx responses.
- `429`: Standard error body returned for non-2xx responses.
- `500`: Standard error body returned for non-2xx responses.
- `502`: Default Response
- `503`: Default Response
- `504`: Default Response

---

[API](https://skmtc.dev/counselhealth/apis/counsel-api.md) - [All operations](https://skmtc.dev/counselhealth/apis/counsel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/counselhealth/apis/counsel-api/revisions/4110a89127e8?raw)