REST API Reference

Quickstart

Make your first API call in under 5 minutes.

Generate an API key

Go to Settings → Integrations → API. Click Regenerate Key. Copy the key — it starts with le_live_.

Make your first request

Fetch your last 50 leads. Replace the key placeholder with your actual key.

bash

curl -X GET "https://api.cratio.com/api/v1/leads?limit=50" \
  -H "Authorization: Bearer le_live_••••••••••••3f7a"

Create a lead

POST a new lead. name + phone (or email) is the minimum.

bash

curl -X POST "https://api.cratio.com/api/v1/leads" \
  -H "Authorization: Bearer le_live_••••••••••••3f7a" \
  -H "Content-Type: application/json" \
  -d '{"name": "Rahul Sharma", "phone": "+91 98765 43210"}'

Authentication

All REST API requests require a Bearer token in the Authorization header.

http

Authorization: Bearer le_live_••••••••••••3f7a

·Keys start with le_live_
·Regenerate or revoke any time from Settings → Integrations → API
·Keys never expire — revoke immediately if compromised

Key permissions

Each key has three independent permission toggles. A key with only Read enabled cannot POST or DELETE.

Read (GET)Pull leads and call logs

Write (POST)Create leads and call logs

Delete (DELETE)Permanently delete leads and call logs

IP whitelist

Optionally restrict a key to specific IPs or CIDR ranges. Leave empty to allow all IPs. Requests from non-whitelisted IPs receive 403 Forbidden.

text

203.0.113.0/24, 198.51.100.1

Linked user

Every key is linked to a Cratio user. API actions are performed as that user — affecting lead assignment, audit logs, and data visibility (row-level security). Link to an Admin for full data access.

Rate limit

100 requests per minute per key. Exceeded requests receive 429 Too Many Requests. The Retry-After header indicates when to retry.

Conventions

Timestamps

All timestamps are ISO 8601 UTC (e.g., 2026-04-22T10:30:00Z). Date filter parameters (from_date, to_date) accept YYYY-MM-DD and are interpreted as IST midnight converted to UTC.

IDs

All resource IDs are UUID v4 strings. Always pass IDs as strings, not integers.

Pagination

List endpoints return { data: [], pagination: { limit, offset, total, has_more } }. Default limit is 50. Maximum is 500. Increment offset by limit to page through results.

Error shape

All errors return { error: { code: string, message: string, field?: string } }. The field key is present when the error is tied to a specific parameter.

json

{
  "error": {
    "code": "INVALID_PARAM",
    "message": "phone must be a valid phone number",
    "field": "phone"
  }
}

Deduplicate on phone/email

POST /api/v1/leads is idempotent on phone + email. If an existing lead shares the same phone or email, the request merges and updates that record and returns 200 (not 201). Check the response code to detect updates vs. creates.

Error Codes

Code	Status	Description
200	OK	Success
201	Created	Lead or call log created
400	Bad Request	Invalid parameters — check the error.field for which param failed
401	Unauthorized	Missing or invalid API key
403	Forbidden	Non-whitelisted IP, or the key lacks the required permission (Read/Write/Delete)
404	Not Found	Resource does not exist or the linked user cannot see it
429	Too Many Requests	Rate limit exceeded (100 req/min). Check Retry-After header.
500	Server Error	Something went wrong on our end. Contact support if it persists.

Leads

GET/api/v1/leads

Retrieve leads with optional filters. Default returns last 30 days, limit 50.

Parameters

Name	Type	Required	Default	Description
from_date	date	optional	30d ago	Leads created on or after this date (YYYY-MM-DD, IST)
to_date	date	optional	today	Leads created on or before this date (YYYY-MM-DD, IST)
status	string	optional	all	Filter by status: New, Contacted, Qualified, Proposal, Won, Lost
source	string	optional	all	Filter by lead source (e.g., Facebook Ads, IVR, API)
priority	string	optional	all	Filter by priority: Low, Medium, High
assigned_to	string	optional	all	Filter by assigned user email
limit	integer	optional	50	Number of results to return. Max 500.
offset	integer	optional	0	Pagination offset. Increment by limit to fetch next page.

Example request

bash

curl -X GET "https://api.cratio.com/api/v1/leads?limit=50&from_date=2026-04-01&status=New" \
  -H "Authorization: Bearer le_live_••••••••••••3f7a"

Example response

json

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Rahul Sharma",
      "email": "rahul@techcorp.in",
      "phone": "+91 98765 43210",
      "company": "TechCorp Solutions",
      "city": "Mumbai",
      "source": "Facebook Ads",
      "status": "New",
      "priority": "High",
      "tags": ["hot-lead", "inbound"],
      "deal_value": 150000,
      "notes": "Interested in Pro plan",
      "assigned_to": "sales@company.com",
      "created_at": "2026-04-22T10:30:00Z",
      "updated_at": "2026-04-22T10:30:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 142,
    "has_more": true
  }
}

POST/api/v1/leads

Create a new lead. If a lead with the same phone or email already exists, the record is merged and updated (200 returned instead of 201).

Requires Write (POST) permission on the API key.

Parameters

Name	Type	Required	Default	Description
name	string	required	—	Full name of the lead
email	string	optional	—	Required if phone is not provided
phone	string	optional	—	Required if email is not provided
company	string	optional	—	Company or organisation name
city	string	optional	—	City
source	string	optional	API	Lead source label (e.g., IVR, Website, Facebook Ads)
status	string	optional	New	Initial status: New, Contacted, Qualified, Proposal, Won, Lost
priority	string	optional	Medium	Priority: Low, Medium, High
tags	string[]	optional	—	Array of string tags
deal_value	number	optional	—	Expected deal value in INR
notes	string	optional	—	Free-text notes
assigned_to	string	optional	—	Assign to a user by their email address

Example request

bash

curl -X POST "https://api.cratio.com/api/v1/leads" \
  -H "Authorization: Bearer le_live_••••••••••••3f7a" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rahul Sharma",
    "phone": "+91 98765 43210",
    "company": "TechCorp Solutions",
    "city": "Mumbai",
    "source": "IVR",
    "status": "New",
    "priority": "High",
    "deal_value": 150000,
    "tags": ["hot-lead", "inbound"],
    "assigned_to": "sales@company.com"
  }'

Example response

json

// 201 Created (new lead) or 200 OK (merged existing)
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Rahul Sharma",
    "phone": "+91 98765 43210",
    "status": "New",
    "created_at": "2026-04-22T10:30:00Z",
    "updated_at": "2026-04-22T10:30:00Z"
  }
}

DELETE/api/v1/leads/{id}

Permanently delete a lead by UUID. This action is irreversible.

Requires Delete (DELETE) permission on the API key.

Permanently deletes the lead and all associated activities, call logs, and notes. This cannot be undone.

Path parameters

Name	Type	Required	Default	Description
id	uuid	required	—	Lead UUID (URL path parameter)

Example request

bash

curl -X DELETE "https://api.cratio.com/api/v1/leads/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer le_live_••••••••••••3f7a"

Example response

json

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "deleted": true
  }
}

Call Logs

GET/api/v1/call-logs

Retrieve call logs. Default returns last 30 days, limit 50.

Parameters

Name	Type	Required	Default	Description
from_date	date	optional	30d ago	Calls on or after this date (YYYY-MM-DD, IST)
to_date	date	optional	today	Calls on or before this date (YYYY-MM-DD, IST)
lead_id	uuid	optional	all	Filter call logs for a specific lead
call_type	string	optional	all	Filter by call type: Inbound, Outbound
limit	integer	optional	50	Number of results to return. Max 500.
offset	integer	optional	0	Pagination offset

Example request

bash

curl -X GET "https://api.cratio.com/api/v1/call-logs?lead_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer le_live_••••••••••••3f7a"

Example response

json

{
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "lead_id": "550e8400-e29b-41d4-a716-446655440000",
      "call_type": "Outbound",
      "duration_seconds": 185,
      "outcome": "Completed",
      "notes": "Discussed pricing. Will send proposal.",
      "called_at": "2026-04-22T10:30:00Z",
      "created_at": "2026-04-22T10:30:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 28,
    "has_more": false
  }
}

POST/api/v1/call-logs

Log a call against a lead. Use duration_seconds: 0 for missed calls.

Requires Write (POST) permission on the API key.

Parameters

Name	Type	Required	Default	Description
lead_id	uuid	required	—	UUID of the lead this call belongs to
call_type	string	required	—	Inbound or Outbound
duration_seconds	integer	required	—	Call duration in seconds. Use 0 for missed calls.
outcome	string	optional	Completed	Outcome: Completed, Busy, No Answer, Voicemail, Missed
notes	string	optional	—	Call notes
called_at	datetime	optional	now	ISO 8601 UTC timestamp of when the call happened. Defaults to now.

Example request

bash

curl -X POST "https://api.cratio.com/api/v1/call-logs" \
  -H "Authorization: Bearer le_live_••••••••••••3f7a" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "550e8400-e29b-41d4-a716-446655440000",
    "call_type": "Outbound",
    "duration_seconds": 185,
    "outcome": "Completed",
    "notes": "Discussed pricing. Will send proposal.",
    "called_at": "2026-04-22T10:30:00Z"
  }'

Example response

json

{
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "lead_id": "550e8400-e29b-41d4-a716-446655440000",
    "call_type": "Outbound",
    "duration_seconds": 185,
    "outcome": "Completed",
    "created_at": "2026-04-22T10:30:00Z"
  }
}

DELETE/api/v1/call-logs/{id}

Permanently delete a call log by UUID.

Requires Delete (DELETE) permission on the API key.

Path parameters

Name	Type	Required	Default	Description
id	uuid	required	—	Call log UUID (URL path parameter)

Example request

bash

curl -X DELETE "https://api.cratio.com/api/v1/call-logs/660e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer le_live_••••••••••••3f7a"

Example response

json

{
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "deleted": true
  }
}

Schemas

Lead

Field	Type	Description
id	uuid	Unique identifier
name	string	Full name
email	string \| null	Email address
phone	string \| null	Phone number
company	string \| null	Company or organisation
city	string \| null	City
source	string	Lead source (e.g., API, IVR, Facebook Ads)
status	enum	New · Contacted · Qualified · Proposal · Won · Lost
priority	enum	Low · Medium · High
tags	string[]	Array of string tags
deal_value	number \| null	Expected value in INR
notes	string \| null	Free-text notes
assigned_to	string \| null	Assigned user email
created_at	datetime	ISO 8601 UTC creation timestamp
updated_at	datetime	ISO 8601 UTC last-modified timestamp

Call Log

Field	Type	Description
id	uuid	Unique identifier
lead_id	uuid	Parent lead UUID
call_type	enum	Inbound · Outbound
duration_seconds	integer	Duration in seconds. 0 = missed.
outcome	enum	Completed · Busy · No Answer · Voicemail · Missed
notes	string \| null	Call notes
called_at	datetime	ISO 8601 UTC timestamp of the call
created_at	datetime	ISO 8601 UTC creation timestamp

Recipes

Common integration patterns, ready to copy and adapt.

Push a lead from IVR

When a caller hits your IVR, immediately create a lead so the sales team can call back. Set priority High and source IVR.

bash

curl -X POST "https://api.cratio.com/api/v1/leads" \
  -H "Authorization: Bearer le_live_••••••••••••3f7a" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "IVR Caller",
    "phone": "+91 98765 43210",
    "source": "IVR",
    "status": "New",
    "priority": "High",
    "notes": "Inbound IVR call — 2026-04-22 14:32 IST"
  }'

Log a missed call from your dialer

Sync missed and completed calls from a third-party dialer into Cratio call logs. Use duration_seconds: 0 for missed.

bash

curl -X POST "https://api.cratio.com/api/v1/call-logs" \
  -H "Authorization: Bearer le_live_••••••••••••3f7a" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "550e8400-e29b-41d4-a716-446655440000",
    "call_type": "Outbound",
    "duration_seconds": 0,
    "outcome": "No Answer",
    "called_at": "2026-04-22T14:32:00Z"
  }'

Nightly export to Google Sheets

Page through all leads created yesterday using offset. Stop when has_more is false.

bash

# Page 1
curl -X GET "https://api.cratio.com/api/v1/leads?from_date=2026-04-21&to_date=2026-04-22&limit=500&offset=0" \
  -H "Authorization: Bearer le_live_••••••••••••3f7a"

# Page 2 (only if pagination.has_more is true)
curl -X GET "https://api.cratio.com/api/v1/leads?from_date=2026-04-21&to_date=2026-04-22&limit=500&offset=500" \
  -H "Authorization: Bearer le_live_••••••••••••3f7a"

What this API won't do (yet)

PATCH / update a leadPOST with the same phone or email merges fields — that is the current update path.

Bulk operationsAll endpoints are single-resource. Loop client-side; stay under 100 req/min.

Outbound webhooks / event streamsWe push leads in via webhooks; we do not push events out yet.

OAuth 2.0Bearer tokens only. OAuth is planned but not on the v1 roadmap.

GraphQLREST only.

Pipeline, tasks, or workflow endpointsLeads and call logs only for now.

Downloads

Import into Postman or generate a typed client from the OpenAPI spec.

Postman Collection v2.1

All 6 endpoints pre-configured. Set the CRATIO_API_KEY environment variable.

cratio-api.postman_collection.json

OpenAPI 3.1 Spec

Machine-readable spec. Use with Redoc, Swagger UI, or any OpenAPI code generator.

cratio-openapi.yaml

Need help?API status →Help centre →Contact support →This is v1. Breaking changes will be released under a new version (/api/v2). v1 will remain supported for a minimum of 12 months after any deprecation notice.