How to Post New Leads/Cases into Kayse

This guide explains the end-to-end setup flow for pushing new leads and cases into Kayse through the Public API. Read it first to understand the sequence before diving into the individual endpoint references.

Overview

Kayse organizes data around three core objects. You create them in order, and each step depends on the ID returned by the previous one.

Step	What you do	Why
1. Create a contact	Post the person's name, phone, email, and external source info	Every lead starts as a contact. Save the returned contact ID.
2. Create a case	Post the case details and link the contact ID from Step 1	A case ties the contact to a case type and status so Kayse knows how to handle them.
3. Create a list	Post a named list	Lists group cases for campaigns and automations. Save the returned list ID.
4. Add contacts to the list	Attach cases or append contacts to the list using the saved IDs	Populates the list so a campaign knows who to reach.
5. Use the list in a campaign	Create a campaign that references the list ID	The AI agent or messaging run reaches every contact on the list.

Important — Save Your IDs

After every successful create call the API returns an id. You must persist the contact ID and the list ID at minimum — they are required in later steps and cannot be looked up by external source alone.

Prerequisites

• An API key from Company Settings > API Keys
• Case types and statuses configured in Kayse — use the Metadata endpoint to retrieve them
• All requests go to https://public-api.kayse.ai/v1 with the X-API-KEY header

---

Step 1 — Create a Contact

Create a contact record for the lead. The API endpoint is /v1/clients (Kayse refers to contacts as "clients" at the API level).

curl -X POST 'https://public-api.kayse.ai/v1/clients' \
  -H 'X-API-KEY: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "Maria",
    "last_name": "Garcia",
    "email": "maria.garcia@example.com",
    "mobile": "+15551234567",
    "external_source": "other",
    "external_source_id": "crm_contact_901"
  }'

Response

{
  "id": 50,
  "first_name": "Maria",
  "last_name": "Garcia",
  "email": "maria.garcia@example.com",
  "mobile": "+15551234567",
  "external_source": "other",
  "external_source_id": "crm_contact_901",
  "origin": "public_api",
  "update_origin": null
}

Save id: 50 — you need this contact ID to create the case in the next step.

See the full Contacts API reference for all available fields.

---

Step 2 — Create a Case Linked to the Contact

Create a case and attach the contact in a single call by passing client_ids.

curl -X POST 'https://public-api.kayse.ai/v1/cases' \
  -H 'X-API-KEY: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "case_number": "PI-2026-042",
    "name": "Garcia - Auto Accident",
    "status": "active",
    "type": "personal_injury",
    "external_source": "other",
    "external_source_id": "crm_case_555",
    "client_ids": [50]
  }'

Response

{
  "id": 200,
  "case_number": "PI-2026-042",
  "name": "Garcia - Auto Accident",
  "status": "active",
  "type": "personal_injury",
  "client_ids": [50],
  "origin": "public_api",
  "update_origin": null
}

The case and contact are now linked. Save the case id if you plan to attach individual cases to the list in Step 4.

INFO

The status and type values must match what is configured in your Kayse account. Use the Metadata endpoint or check Company Settings > Case Types to see available values.

See the full Cases API reference for all available fields.

---

Step 3 — Create a List

Create a list that will hold the cases you want to reach.

curl -X POST 'https://public-api.kayse.ai/v1/case_lists' \
  -H 'X-API-KEY: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Q2 Personal Injury Outreach",
    "description": "PI prospects for the Q2 campaign"
  }'

Response

{
  "id": 10,
  "name": "Q2 Personal Injury Outreach",
  "description": "PI prospects for the Q2 campaign",
  "case_count": 0,
  "origin": "public_api",
  "update_origin": null
}

Save id: 10 — you need this list ID to add contacts and to create the campaign.

TIP

You can also supply a filter object at creation time to build a dynamic list that automatically includes matching cases. See the Case Lists API reference for details.

See the full Case Lists API reference for all available fields.

---

Step 4 — Add or Remove Contacts from the List

With the list created, populate it using one of two approaches.

Option A — Attach specific cases

If you are tracking individual case IDs, attach them directly.

curl -X PATCH 'https://public-api.kayse.ai/v1/case_lists/10/attach' \
  -H 'X-API-KEY: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "include_ids": [200]
  }'

Option B — Append by contact ID

If you want to add all cases belonging to specific contacts in one call, use the client-append endpoint. This is simpler when a contact has multiple cases.

curl -X POST 'https://public-api.kayse.ai/v1/case_lists/10/clients/append' \
  -H 'X-API-KEY: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_ids": [50]
  }'

Response

{
  "action": "append",
  "list_id": 10,
  "client_count": 1,
  "matched_case_count": 1
}

Removing contacts from a list

To detach specific cases:

curl -X PATCH 'https://public-api.kayse.ai/v1/case_lists/10/detach' \
  -H 'X-API-KEY: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{ "include_ids": [200] }'

To remove all cases belonging to specific contacts:

curl -X POST 'https://public-api.kayse.ai/v1/case_lists/10/clients/remove' \
  -H 'X-API-KEY: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{ "client_ids": [50] }'

---

Step 5 — Use the List in a Campaign

Once the list is populated, create a campaign that references it. The campaign tells the AI agent (or messaging run) who to contact, when, and how.

curl -X POST 'https://public-api.kayse.ai/v1/campaigns' \
  -H 'X-API-KEY: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Q2 PI Outreach",
    "agent_id": "your_agent_id",
    "case_list_id": 10,
    "runs": [
      {
        "start_date": "2026-04-01",
        "end_date": "2026-04-30",
        "start_time": "09:00",
        "end_time": "17:00"
      }
    ]
  }'

Response

{
  "id": 1
}

The campaign is now live and the AI agent will begin reaching out to every contact on the list during the scheduled run window.

INFO

agent_id refers to a published AI agent you have configured in the Agent Builder. If you only need SMS or email (no voice calls), set messaging_only: true on the run and omit agent_id.

See the full Campaigns API reference for all run, scheduling, and report options.

---

Bulk Operations

When importing many leads at once, use the bulk endpoints to reduce the number of API calls:

1. Bulk create contacts — POST /v1/clients/bulk with an array of contact objects
2. Bulk create cases — POST /v1/cases/bulk with an array of case objects referencing contact IDs
3. Bulk add to list — PATCH /v1/case_lists/{id}/attach with all case IDs, or POST /v1/case_lists/{id}/clients/append with all contact IDs

See the Contacts, Cases, and Case Lists API references for full bulk endpoint documentation.

---

Quick Reference

Action	Method	Endpoint	Key fields
Create contact	POST	/v1/clients	first_name, last_name, external_source, external_source_id
Create case	POST	/v1/cases	case_number, status, type, client_ids
Create list	POST	/v1/case_lists	name
Attach cases	PATCH	/v1/case_lists/{id}/attach	include_ids
Append contacts	POST	/v1/case_lists/{id}/clients/append	client_ids
Detach cases	PATCH	/v1/case_lists/{id}/detach	include_ids
Remove contacts	POST	/v1/case_lists/{id}/clients/remove	client_ids
Create campaign	POST	/v1/campaigns	name, case_list_id, runs