Manage Users and Invitations Through the Shilo API

Shilo users represent the agents and team members in your sales organization. The Users API lets you retrieve user records, update profile information, and suspend members who have left your team. The Invitations API handles the onboarding flow for new agents who haven’t yet joined Shilo. Together, these endpoints let you keep your Shilo roster in sync with your own system of record.

Users vs. Contacts

Before diving in, it helps to distinguish the two people-related resources in Shilo:

Users — Your sales agents. They log in to Shilo, receive coaching agendas, and appear in performance metrics.
Contacts — The leads and clients your agents call. They do not log in to Shilo; they exist as subjects of call analysis.

Listing Users

Retrieve a paginated list of all users in your organization:

curl "https://api.shilo.ai/api/v1/users" \
  -H "x-api-key: YOUR_API_KEY"

Filter the list by external ID, email, or name:

# Filter by your system's user ID
curl "https://api.shilo.ai/api/v1/users?external_user_id=agent-123" \
  -H "x-api-key: YOUR_API_KEY"

# Filter by email (case-insensitive exact match)
curl "https://api.shilo.ai/api/v1/users?email=alex%40example.com" \
  -H "x-api-key: YOUR_API_KEY"

# Filter by name (case-insensitive partial match)
curl "https://api.shilo.ai/api/v1/users?name=alex" \
  -H "x-api-key: YOUR_API_KEY"

Retrieving a Single User

Use any of the three supported identifier formats:

# By Shilo UUID
curl https://api.shilo.ai/api/v1/users/ee6f2136-b94a-4438-9335-3acf5b2a0d31 \
  -H "x-api-key: YOUR_API_KEY"

# By Shilo UUID with explicit prefix
curl "https://api.shilo.ai/api/v1/users/id:ee6f2136-b94a-4438-9335-3acf5b2a0d31" \
  -H "x-api-key: YOUR_API_KEY"

# By your system's user ID
curl "https://api.shilo.ai/api/v1/users/external_user_id:agent-123" \
  -H "x-api-key: YOUR_API_KEY"

Updating a User

Send a PUT request with the fields you want to change:

curl -X PUT "https://api.shilo.ai/api/v1/users/external_user_id:agent-123" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alexandra Johnson",
    "timezone": "America/Chicago"
  }'

Updating a User’s Email

Email updates have a dedicated endpoint to prevent accidental overwrites. Both existing_email and updated_email are required: existing_email identifies the current account and updated_email is the new address to assign:

curl -X PUT "https://api.shilo.ai/api/v1/users/external_user_id:agent-123/update_email" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "existing_email": "alex@example.com",
    "updated_email": "alex.new@example.com"
  }'

Suspending a User

When an agent leaves your team, suspend their Shilo membership with a DELETE request:

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

A successful suspension returns 204 No Content.

Suspending a user does not delete their Shilo account or remove their call history. It suspends their membership for your integration only. Their data remains accessible through the API. Additionally, Zillow Flex Advisor users are not affected by this endpoint—their membership is managed separately.

User Signal

Retrieve the latest Shilo Signal for an agent. A Signal is the latest AI-derived behavioral and communication profile for the user, useful for coaching, preparation, and adapting your approach in one-on-ones:

curl "https://api.shilo.ai/api/v1/users/external_user_id:agent-123/signal" \
  -H "x-api-key: YOUR_API_KEY"

Invitations

Use the Invitations API to onboard new agents who haven’t yet accepted a Shilo invite. This is especially useful when provisioning users programmatically during your integration setup.

Create an Invitation

email and external_user_id are required. Exactly one of invited_by_user_id or invited_by_email is also required. name and first_name are optional. role is optional and may only be ADMIN or MEMBER, defaulting to MEMBER:

curl -X POST https://api.shilo.ai/api/v1/invitations \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newagent@example.com",
    "external_user_id": "agent-789",
    "name": "Jordan Smith",
    "first_name": "Jordan",
    "role": "MEMBER",
    "invited_by_email": "manager@example.com"
  }'

Possible responses:

Status	Meaning
`201 Created`	Invitation successfully created and the invitation workflow queued. Status is `PENDING`
`200 OK`	A pending invitation for this email already exists; the existing invitation is returned
`409 Conflict`	A pending invitation exists for this email but with a different `external_user_id`; resolve the conflict before retrying

List Pending Invitations

curl "https://api.shilo.ai/api/v1/invitations?sort=desc" \
  -H "x-api-key: YOUR_API_KEY"

Resend an Invitation

curl -X POST "https://api.shilo.ai/api/v1/invitations/INVITATION_ID/resend" \
  -H "x-api-key: YOUR_API_KEY"

A successful resend returns 202 Accepted.

Cancel an Invitation

curl -X DELETE "https://api.shilo.ai/api/v1/invitations/INVITATION_ID" \
  -H "x-api-key: YOUR_API_KEY"

A successful cancellation returns 204 No Content.

Keeping Users in Sync

Because Shilo supports external_user_id as an identifier, you can build a robust sync without storing Shilo UUIDs in your system:

When a new agent joins your team, POST /api/v1/invitations with their external_user_id.
Once they accept and appear in GET /api/v1/users, reference them with external_user_id:{your-id} in all subsequent calls.
When an agent leaves, DELETE /api/v1/users/external_user_id:{your-id} to suspend their membership.

Write operations (POST, PUT, DELETE) on users and invitations require a read-write API key. A read-only key returns 403 Forbidden on these endpoints.

Get Started

Core Concepts

Guides

Manage Users and Invitations Through the Shilo API

Users vs. Contacts

Listing Users

Retrieving a Single User

Updating a User

Updating a User’s Email

Suspending a User

User Signal

Invitations

Create an Invitation

List Pending Invitations

Resend an Invitation

Cancel an Invitation

Keeping Users in Sync

​Users vs. Contacts

​Listing Users

​Retrieving a Single User

​Updating a User

​Updating a User’s Email

​Suspending a User

​User Signal

​Invitations

​Create an Invitation

​List Pending Invitations

​Resend an Invitation

​Cancel an Invitation

​Keeping Users in Sync

Users vs. Contacts

Listing Users

Retrieving a Single User

Updating a User

Updating a User’s Email

Suspending a User

User Signal

Invitations

Create an Invitation

List Pending Invitations

Resend an Invitation

Cancel an Invitation

Keeping Users in Sync