Identifier Patterns for Shilo API Resources

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.

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

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.

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

Get Started

Core Concepts

Guides

Identifier Patterns for Shilo API Resources

The `prefix:value` Pattern

Identifier Reference by Resource

Calls

Contacts

Users

Appointments

Roleplays

Using External IDs Throughout Your Integration

Invalid Identifier Errors

​The prefix:value Pattern

​Identifier Reference by Resource

​Calls

​Contacts

​Users

​Appointments

​Roleplays

​Using External IDs Throughout Your Integration

​Invalid Identifier Errors

The `prefix:value` Pattern

Identifier Reference by Resource

Calls

Contacts

Users

Appointments

Roleplays

Using External IDs Throughout Your Integration

Invalid Identifier Errors