Campaigns

Manage outreach campaigns in Kayse AI.

Create Campaign

POST/v1/campaigns

Request Body Fields

Field	Required	Type	Description
name	true	String	Campaign name
agent_id	conditional	String	Required unless all runs are messaging_only=true
case_list_id	true	Integer	ID of case list
is_obo	false	Boolean	On behalf of clients
calls_scheduled_externally	false	Boolean	External scheduling
never_ending	false	Boolean	When true, runs won't auto-complete when the contact list is exhausted
concurrency_limit	false	Integer	0 means unlimited
self_healing_disabled	false	Boolean	Disable enrichment/self-healing
form_id	false	Integer	Optional linked form
use_company_hours	false	Boolean	Use campaign-level business hours instead of per-run calling times
business_hours	conditional	Array	Required when use_company_hours=true. Time slots for calling hours
runs	true	Array	Campaign runs (at least one)
report_schedule	false	Object	Optional scheduled report created atomically with campaign

business_hours[] fields

Field	Required	Type	Description
start_time	true	Time (HH:mm)	Slot start time (must be within 08:00–21:00)
end_time	true	Time (HH:mm)	Slot end time (must be within 08:00–21:00, after start_time)

Slots must not overlap and must fall within TCPA-compliant hours (8:00 AM – 9:00 PM).

runs[] fields

Field	Required	Type	Description
client_run_id	false	String	Client-side run identifier for mapping report scope
start_date	true	Date (YYYY-MM-DD)	Run start date
end_date	true	Date (YYYY-MM-DD)	Run end date
start_time	conditional	Time (HH:mm)	Required for non-messaging-only runs
end_time	conditional	Time (HH:mm)	Required for non-messaging-only runs
messaging_only	false	Boolean	If true, call scheduling fields are not allowed
selected_days	false	Array	Optional selected run dates
messages	false	Array	Scheduled message entries

report_schedule fields

Field	Required	Type	Description
name	true	String	Report schedule name
run_client_ids	false	Array[String]	Must match runs[].client_run_id; omit/empty for entire campaign
frequency	true	Enum	daily, weekly, monthly
weekday	conditional	Integer	Required for weekly (0 Sunday ... 6 Saturday)
day_of_month	conditional	Integer	Required for monthly (1-31)
time	true	Time (HH:mm)	Delivery time
recipients	true	Array[String]	Recipient emails
format	false	Enum	csv
date_range	false	Enum	cumulative, today_so_far, previous_day, previous_week, previous_month
filters	false	Object	Optional report filters

Request

curl -X POST 'https://public-api.kayse.ai/v1/campaigns' \
-H 'X-API-KEY: your_api_key' \
-H 'Content-Type: application/json' \
-d '{
  "name": "Outreach Campaign",
  "agent_id": "abc_123",
  "case_list_id": 123,
  "is_obo": false,
  "calls_scheduled_externally": false,
  "runs": [
    {
      "client_run_id": "run-1",
      "start_date": "2026-02-20",
      "end_date": "2026-02-20",
      "start_time": "09:00",
      "end_time": "17:00",
      "messaging_only": false
    }
  ],
  "report_schedule": {
    "name": "Weekly Campaign Report",
    "run_client_ids": ["run-1"],
    "frequency": "weekly",
    "weekday": 2,
    "time": "09:30",
    "recipients": ["reports@firm.com"],
    "format": "csv",
    "date_range": "cumulative",
    "filters": {}
  }
}'

Response

{
  "id": 1
}

Campaign Settings

GET/v1/campaigns/settings

Returns campaign feature status, the company concurrency rate, and default business hours.

Response Fields

Field	Type	Description
is_enabled	Boolean	Whether campaigns are enabled for this company
concurrency_rate	Integer	Outbound call limit percentage (1–100)
business_hours	Array	Default business hour time slots (may be null if none configured)

business_hours[] fields

Field	Type	Description
start_time	Time (HH:mm)	Slot start time
end_time	Time (HH:mm)	Slot end time

Request

curl -X GET 'https://public-api.kayse.ai/v1/campaigns/settings' \
-H 'X-API-KEY: your_api_key'

Response

{
  "is_enabled": true,
  "concurrency_rate": 70,
  "business_hours": [
    { "start_time": "09:00", "end_time": "12:00" },
    { "start_time": "13:00", "end_time": "17:00" }
  ]
}

List Campaigns

GET/v1/campaigns

Query Parameters

Field	Required	Type	Description
key	false	String	Search term for filtering

Request

curl -X GET 'https://public-api.kayse.ai/v1/campaigns?key=outreach' \
-H 'X-API-KEY: your_api_key'

Response

[
  {
    "id": 1,
    "name": "Outreach Campaign",
    "agent_id": "abc_123",
    "case_list_id": 123,
    "origin": "public_api",
    "update_origin": null,
    "stats": {
      "total_calls": 132,
      "success_calls": 85,
      "success_calls_percentage": 70.8,
      "failed_calls": 35,
      "average_sentiment_score": 0.76,
      "conversion_rate": 42.1
    }
  }
]