Get Started with the Shilo API in Minutes

This guide walks you through the complete lifecycle of a Shilo API call: generating a key, submitting a recording, and reading back the AI analysis. By the end you will have a working integration pattern you can adapt to any language or framework. The five steps below cover everything from authentication to inspecting the available analysis fields.

Step 1: Generate an API key

In the Shilo dashboard, navigate to Settings > API Keys > Generate API Key and create a read-write key. Copy the key immediately, it is only shown once. Store it as a secret in your environment (for example, SHILO_API_KEY) and never commit it to source control.

Step 2: Prepare a recording URL

Host your call recording at a publicly accessible URL that Shilo can fetch over HTTPS. Common patterns include a signed S3 URL, a Cloudflare R2 public link, or any CDN-hosted audio file. Make sure the URL resolves without additional authentication for the duration of processing.

Step 3: Submit the call

Send a POST to https://api.shilo.ai/api/v1/calls with your API key in the x-api-key header and a JSON body containing every required field.

cURL

curl -X POST https://api.shilo.ai/api/v1/calls \
  -H "x-api-key: $SHILO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recording_id": "rec_2f7a91",
    "recording_url": "https://cdn.example.com/calls/rec_2f7a91.mp3",
    "duration_seconds": 842,
    "ai_category": "sales",
    "external_user_id": "usr_alex_01",
    "user_name": "Alex Rivera",
    "user_email": "alex@example.com",
    "external_contact_id": "cnt_jordan_42",
    "contact_name": "Jordan Lee"
  }'

A successful submission returns 202 Accepted with the queued call event.

202 Accepted

{
  "call_event_id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
  "status": "QUEUED"
}

Step 4: Poll for analysis

Save the call_event_id and poll GET /api/v1/calls/call_event_id:{call_event_id}/analysis using the same API key. Continue polling until progress reaches 100.

cURL

curl https://api.shilo.ai/api/v1/calls/call_event_id:ee6f2136-b94a-4438-9335-3acf5b2a0d31/analysis \
  -H "x-api-key: $SHILO_API_KEY"

progress: 100 means processing is complete. Individual analysis objects can still be absent or null depending on the call’s content and length, so treat each sub-object as optional in your integration.

Step 5: Inspect the analysis

Once processing is complete, read the fields your workflow needs. The analysis response can include:

rating, a numeric quality score for the call.
summary, an AI-generated recap.
coaching, structured coaching feedback for the rep.
disposition, the call outcome classification.
objections, buyer objections detected in the conversation.
action_items, follow-ups surfaced from the discussion.
speakers, AI-resolved user and client names.

Any of these may be missing or null on a given call, so check for presence before accessing nested fields. For deeper coverage of every request and response field, see the Submit Calls and Retrieve Analysis guides.

Next Steps

Submit Calls

Learn all required and optional fields for the call creation endpoint.

Retrieve Analysis

Deep-dive into every analysis field and the polling pattern.

Identifiers

Understand the prefix:value identifier system used across all resources.

Pagination

Page through large result sets with cursor-based pagination.

Get Started

Core Concepts

Guides

Get Started with the Shilo API in Minutes

Step 1: Generate an API key

Step 2: Prepare a recording URL

Step 3: Submit the call

Step 4: Poll for analysis

Step 5: Inspect the analysis

Next Steps

Submit Calls

Retrieve Analysis

Identifiers

Pagination

​Step 1: Generate an API key

​Step 2: Prepare a recording URL

​Step 3: Submit the call

​Step 4: Poll for analysis

​Step 5: Inspect the analysis

​Next Steps

Submit Calls

Retrieve Analysis

Identifiers

Pagination

Step 1: Generate an API key

Step 2: Prepare a recording URL

Step 3: Submit the call

Step 4: Poll for analysis

Step 5: Inspect the analysis

Next Steps