List Users — Shilo API Reference

Use this endpoint to retrieve all users (agents) in your Shilo organization. Results are paginated and can be filtered by external user ID, email address, or name. Pass the cursor value from the pagination object into your next request to walk through large teams page by page.

Endpoint

GET https://api.shilo.ai/api/v1/users

Authentication

Include your API key in the request header:

x-api-key: YOUR_API_KEY

Query Parameters

number

default:"50"

Maximum number of users to return per page. Accepted range is 1–100.

string

Pagination cursor returned by a previous response. Pass this value to retrieve the next page of results.

string

Sort order by created date. Accepted values: asc, desc.

string

Filter by your system’s user ID. Exact match only.

string

Filter by email address. Case-insensitive exact match.

string

Filter by user name. Case-insensitive partial match — useful for search-as-you-type UIs.

Response

A successful request returns HTTP 200 with a UsersResponseDto object.

Response Fields

array

An array of User objects matching your query filters.

Show User object

string

The Shilo-assigned UUID for this user.

string

The user ID from your external system.

string

Full display name of the user.

string

Primary email address of the user.

string

The user’s configured timezone in IANA format (e.g. America/New_York).

string

URL of the user’s profile picture, if set.

string

ISO-8601 timestamp indicating when this user was created in Shilo.

object

Pagination metadata for the current response.

Show Pagination object

boolean

true if additional pages of results exist beyond the current page.

string | null

Cursor value to pass in your next request to retrieve the following page. null when no further pages are available.

Example Response

{
  "data": [
    {
      "id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
      "external_user_id": "agent-1",
      "name": "Alex User",
      "email": "alex@example.com",
      "timezone": "America/New_York",
      "picture": "https://cdn.shilo.ai/avatars/ee6f2136.png",
      "created_date": "2024-01-15T09:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

Error Codes

Status	Meaning
`401`	Missing or invalid API key.

Example Request

curl -X GET "https://api.shilo.ai/api/v1/users?limit=50&sort=asc" \
  -H "x-api-key: YOUR_API_KEY"

Filter by name

curl -X GET "https://api.shilo.ai/api/v1/users?name=alex" \
  -H "x-api-key: YOUR_API_KEY"

Paginate with a cursor

curl -X GET "https://api.shilo.ai/api/v1/users?limit=50&cursor=NEXT_CURSOR_VALUE" \
  -H "x-api-key: YOUR_API_KEY"

Overview

Calls

Appointments

Roleplays

Contacts

Users

Invitations

Metrics

Coaching

List Users — Shilo API Reference

Endpoint

Authentication

Query Parameters

Response

Response Fields

Example Response

Error Codes

Example Request

Filter by name

Paginate with a cursor

​Endpoint

​Authentication

​Query Parameters

​Response

​Response Fields

​Example Response

​Error Codes

​Example Request

​Filter by name

​Paginate with a cursor

Endpoint

Authentication

Query Parameters

Response

Response Fields

Example Response

Error Codes

Example Request

Filter by name

Paginate with a cursor