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

# Identifier Patterns for Shilo API Resources

> Shilo supports multiple identifier formats for calls, contacts, and users. Learn the prefix:value pattern and when to use each identifier type.

Most Shilo API endpoints accept an `{identifier}` path parameter rather than a single fixed ID type. This flexible design lets you reference a resource using either its Shilo-generated UUID or an ID from your own system, without needing a separate lookup step first. Understanding which identifier to use—and when—keeps your integration code simple and reduces round trips.

## The `prefix:value` Pattern

Identifiers that are not plain UUIDs use a `prefix:value` format. The prefix tells Shilo which ID namespace you are referencing. For example:

* `call_event_id:ee6f2136-b94a-4438-9335-3acf5b2a0d31` — look up by call event ID
* `external_recording_id:rec-001` — look up by the `recording_id` you provided at submission
* `external_user_id:agent-123` — look up a user by your system's user ID
* `external_contact_id:contact-456` — look up a contact by your CRM's contact ID

A plain UUID without a prefix is always treated as the Shilo internal UUID for that resource.

## Identifier Reference by Resource

### Calls

| Format                           | Example                                | When to use                                                                    |
| -------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------ |
| `{uuid}`                         | `ee6f2136-b94a-4438-9335-3acf5b2a0d31` | You already have the Shilo call UUID                                           |
| `call_event_id:{uuid}`           | `call_event_id:ee6f2136-...`           | Right after submitting a call; use the `call_event_id` from the `202` response |
| `external_recording_id:{string}` | `external_recording_id:rec-001`        | You want to look up a call by the `recording_id` you supplied at creation      |

### Contacts

| Format                         | Example                                | When to use                                      |
| ------------------------------ | -------------------------------------- | ------------------------------------------------ |
| `{uuid}`                       | `ee6f2136-b94a-4438-9335-3acf5b2a0d31` | You already have the Shilo contact UUID          |
| `id:{uuid}`                    | `id:ee6f2136-...`                      | Explicit alternative to the bare UUID format     |
| `external_contact_id:{string}` | `external_contact_id:contact-456`      | You want to reference a contact by your CRM's ID |

### Users

| Format                      | Example                                | When to use                                           |
| --------------------------- | -------------------------------------- | ----------------------------------------------------- |
| `{uuid}`                    | `ee6f2136-b94a-4438-9335-3acf5b2a0d31` | You already have the Shilo user UUID                  |
| `id:{uuid}`                 | `id:ee6f2136-...`                      | Explicit alternative to the bare UUID format          |
| `external_user_id:{string}` | `external_user_id:agent-123`           | You want to reference a user by your system's user ID |

### Appointments

| Format                           | Example                                | When to use                                            |
| -------------------------------- | -------------------------------------- | ------------------------------------------------------ |
| `{uuid}`                         | `ee6f2136-b94a-4438-9335-3acf5b2a0d31` | You already have the Shilo recording UUID              |
| `external_recording_id:{string}` | `external_recording_id:appt-789`       | You want to look up by the `recording_id` you provided |

### Roleplays

| Format                 | Example                                | When to use                                                                |
| ---------------------- | -------------------------------------- | -------------------------------------------------------------------------- |
| `{uuid}`               | `ee6f2136-b94a-4438-9335-3acf5b2a0d31` | You already have the Shilo roleplay UUID                                   |
| `call_event_id:{uuid}` | `call_event_id:ee6f2136-...`           | Right after roleplay submission; use the `call_event_id` from the response |

## Using External IDs Throughout Your Integration

Shilo's external ID support means you can submit a call using your own `recording_id` and later retrieve its analysis without ever storing Shilo's internal UUID. The same principle applies to users and contacts: pass your own IDs at call submission time, and use `external_user_id:` and `external_contact_id:` prefixes everywhere you need to look them up.

```bash theme={null}
# Retrieve a call by the recording_id you chose at submission
curl https://api.shilo.ai/api/v1/calls/external_recording_id:rec-001 \
  -H "x-api-key: YOUR_API_KEY"

# Retrieve analysis using the call_event_id from the 202 response
curl https://api.shilo.ai/api/v1/calls/call_event_id:ee6f2136-b94a-4438-9335-3acf5b2a0d31/analysis \
  -H "x-api-key: YOUR_API_KEY"

# Retrieve the same call by its Shilo UUID (once you have it)
curl https://api.shilo.ai/api/v1/calls/a1b2c3d4-5678-90ab-cdef-111122223333 \
  -H "x-api-key: YOUR_API_KEY"
```

<Note>
  Immediately after submitting a call, use `call_event_id:{uuid}` as the identifier because the Shilo call UUID may not be available yet. Once analysis completes and you have retrieved the full call object, you can switch to the stable Shilo UUID for any subsequent lookups.
</Note>

## Invalid Identifier Errors

If you pass an identifier in an unrecognized format, or if no resource matches the given ID, the API returns:

| Status            | Meaning                                                 |
| ----------------- | ------------------------------------------------------- |
| `400 Bad Request` | The identifier format is invalid or cannot be parsed    |
| `404 Not Found`   | The identifier is valid but no matching resource exists |