Your First API Call

This guide walks you through the most common API workflow: importing contacts, creating an audience, and triggering a campaign — all programmatically.

Base URLs

Environment	URL
Production	`https://api.oliai.in/v1`
QA / Staging	`https://api.qa.oliai.in/v1`

Authentication

Every request must include your API key in the x-api-key header:

x-api-key: sk_live_your_key_here

Workflow: Contacts → Audience → Campaign

Add Contacts

curl -X POST https://api.oliai.in/v1/contacts/bulk \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "name": "Priya Sharma",
        "phoneNumber": "+919876543210",
        "language": "hi-IN",
        "metadata": { "city": "Mumbai", "tier": "premium" }
      },
      {
        "name": "Ravi Kumar",
        "phoneNumber": "+919123456789",
        "language": "en-IN"
      }
    ]
  }'

Response:

{
  "created": 2,
  "updated": 0,
  "failed": 0,
  "contacts": [
    { "id": "cid_001", "name": "Priya Sharma", "phoneNumber": "+919876543210" },
    { "id": "cid_002", "name": "Ravi Kumar",   "phoneNumber": "+919123456789" }
  ]
}

Create an Audience

curl -X POST https://api.oliai.in/v1/audiences \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mumbai Premium Customers",
    "description": "Hindi-speaking premium tier in Mumbai"
  }'

Response:

{
  "id": "aud_abc123",
  "name": "Mumbai Premium Customers",
  "contactCount": 0
}

Add Contacts to the Audience

curl -X POST https://api.oliai.in/v1/audiences/aud_abc123/contacts \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["cid_001"]
  }'

Get a Flow ID

Before creating a campaign, you need a voice flow ID. List your organization's flows:

curl https://api.oliai.in/v1/flows \
  -H "x-api-key: sk_live_your_key_here"

Note the id of the flow you want to use.

Create and Start a Campaign

curl -X POST https://api.oliai.in/v1/campaigns \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mumbai Outreach - March",
    "audienceId": "aud_abc123",
    "flowId": "flow_xyz789",
    "callsPerMinute": 5,
    "maxConcurrentCalls": 3,
    "maxRetries": 2
  }'

Response:

{
  "id": "camp_def456",
  "name": "Mumbai Outreach - March",
  "status": "DRAFT"
}

Then start it:

curl -X POST https://api.oliai.in/v1/campaigns/camp_def456/start \
  -H "x-api-key: sk_live_your_key_here"

Monitor Progress

curl https://api.oliai.in/v1/campaigns/camp_def456/progress \
  -H "x-api-key: sk_live_your_key_here"

Response:

{
  "status": "IN_PROGRESS",
  "total": 1,
  "pending": 0,
  "inProgress": 1,
  "completed": 0,
  "failed": 0,
  "percentComplete": 0
}

Error Handling

HTTP Status	Meaning
`200` / `201`	Success
`400`	Invalid request body — check the error message
`401`	Missing or invalid API key
`403`	Insufficient permissions
`404`	Resource not found
`429`	Rate limit exceeded — back off and retry
`500`	Server error — contact support

All errors return a JSON body:

{
  "statusCode": 400,
  "message": "phoneNumber must be a valid E.164 phone number",
  "error": "Bad Request"
}

Phone numbers must be in E.164 format — e.g., +919876543210 (include country code, no spaces or dashes).

Creating API Keys Overview