> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shilo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Users and Invitations Through the Shilo API

> Learn how to list, update, and suspend users, send team invitations, and sync your user data with Shilo using external IDs.

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:

```bash theme={null}
curl "https://api.shilo.ai/api/v1/users" \
  -H "x-api-key: YOUR_API_KEY"
```

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

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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`.

<Warning>
  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.
</Warning>

## 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:

```bash theme={null}
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`:

```bash theme={null}
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

```bash theme={null}
curl "https://api.shilo.ai/api/v1/invitations?sort=desc" \
  -H "x-api-key: YOUR_API_KEY"
```

### Resend an Invitation

```bash theme={null}
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

```bash theme={null}
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:

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

<Note>
  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.
</Note>