Get a User — Shilo API Reference

Use this endpoint to retrieve a single user (agent) record from your Shilo organization. You can identify the user with their Shilo UUID, a prefixed UUID, or your own external user ID — whatever aligns with your integration’s data model. This flexibility means you never need to maintain a separate mapping table between your system and Shilo to look up agents.

Endpoint

GET https://api.shilo.ai/api/v1/users/{identifier}

Authentication

Include your API key in the request header:

x-api-key: YOUR_API_KEY

Path Parameters

string

required

The identifier used to look up the user. Three formats are supported:

Format	Example
Plain Shilo UUID	`ee6f2136-b94a-4438-9335-3acf5b2a0d31`
Prefixed Shilo UUID	`id:ee6f2136-b94a-4438-9335-3acf5b2a0d31`
External user ID	`external_user_id:agent-1`

Response

A successful request returns HTTP 200 with a User object.

Response Fields

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.

Example Response

{
  "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"
}

Error Codes

Status	Meaning
`400`	The identifier format is invalid or malformed.
`404`	No user was found matching the provided identifier.

Example Requests

Look up by plain Shilo UUID

curl -X GET "https://api.shilo.ai/api/v1/users/ee6f2136-b94a-4438-9335-3acf5b2a0d31" \
  -H "x-api-key: YOUR_API_KEY"

Look up by prefixed Shilo UUID

curl -X GET "https://api.shilo.ai/api/v1/users/id:ee6f2136-b94a-4438-9335-3acf5b2a0d31" \
  -H "x-api-key: YOUR_API_KEY"

Look up by external user ID

curl -X GET "https://api.shilo.ai/api/v1/users/external_user_id:agent-1" \
  -H "x-api-key: YOUR_API_KEY"

⌘I

Overview

Calls

Appointments

Roleplays

Contacts

Users

Invitations

Metrics

Coaching

Get a User — Shilo API Reference

Endpoint

Authentication

Path Parameters

Response

Response Fields

Example Response

Error Codes

Example Requests

Look up by plain Shilo UUID

Look up by prefixed Shilo UUID

Look up by external user ID

​Endpoint

​Authentication

​Path Parameters

​Response

​Response Fields

​Example Response

​Error Codes

​Example Requests

​Look up by plain Shilo UUID

​Look up by prefixed Shilo UUID

​Look up by external user ID

Endpoint

Authentication

Path Parameters

Response

Response Fields

Example Response

Error Codes

Example Requests

Look up by plain Shilo UUID

Look up by prefixed Shilo UUID

Look up by external user ID