List campaign prospects

Returns all prospects associated with a campaign

GET /prospects/campaign/{campaignId}

List Campaign Prospects

cURL

curl --request GET \
  --url https://api.kakiyo.com/v1/prospects/campaign/{campaignId} \
  --header 'Authorization: Bearer <token>'

200

[
  {
    "id": "chat_12345abcde",
    "status": 2,
    "qualification": "inProgress",
    "paused": false,
    "lastMessage": "2023-06-15T15:30:00Z",
    "prospect": {
      "id": "prospect_12345abcde",
      "name": "John Smith",
      "url": "https://linkedin.com/in/johnsmith",
      "headline": "VP of Sales at Acme Inc",
      "currentCompanyName": "Acme Inc",
      "currentJobTitle": "VP of Sales",
      "currentCompanyWebsite": "https://www.acme.com",
      "currentCompanyLinkedInUrl": "https://www.linkedin.com/company/acme"
    }
  }
]

Overview

List prospects for a specific campaign. The endpoint reads campaign conversation state from Appwrite and hydrates prospect profile details from PlanetScale.

The response body remains a plain array for compatibility with existing integrations. Pagination metadata is returned in response headers.

Each prospect object includes current company data when available: currentCompanyName, currentJobTitle, currentCompanyWebsite, and currentCompanyLinkedInUrl.

Response Fields

prospect.currentCompanyName · string | null

Current company name from prospect enrichment.

prospect.currentJobTitle · string | null

Current job title from prospect enrichment.

prospect.currentCompanyWebsite · string | null

Current company’s website URL when available.

prospect.currentCompanyLinkedInUrl · string | null

Current company’s LinkedIn page URL when available.

Query Parameters

limit · number · default: "25"

Maximum number of prospects to return. The maximum supported value is 100.

offset · number · default: "0"

Number of prospects to skip when using offset pagination. Ignored when cursor is provided.

cursor · string

Opaque cursor from the X-Next-Cursor response header. Use this for stable pagination through large campaigns.

status · number

Filter by conversation status. Use 4 to retrieve prospects who replied.

isPaused · boolean

Filter paused or active campaign conversations.

hasResponded · boolean

Filter conversations with or without a recorded last message timestamp. Use status=4 when you specifically need replied prospects.

Conversation Status Values

Status	Meaning
0	Not started
1	Invitation sent
2	Invitation accepted
3	Contacted
4	Replied
5	Qualified
6	Unqualified
7	Skipped
502	Invites disabled
503	Unreachable
504	No longer in network
505	Invite cooldown

Pagination Headers

Header	Description
X-Limit	Applied page size
X-Offset	Applied offset when offset pagination is used
X-Has-More	true when another page is available
X-Next-Cursor	Opaque cursor to pass as cursor for the next page

Examples

List campaign prospects

curl "https://api.kakiyo.com/v1/prospects/campaign/{campaignId}?limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

List replied prospects

curl "https://api.kakiyo.com/v1/prospects/campaign/{campaignId}?status=4&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

List paused replied prospects

curl "https://api.kakiyo.com/v1/prospects/campaign/{campaignId}?status=4&isPaused=true&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Continue with cursor pagination

curl "https://api.kakiyo.com/v1/prospects/campaign/{campaignId}?limit=100&cursor={nextCursor}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

campaignId · string · required

ID of the campaign

Response

200

application/json

List of prospects

id · string

Example:

"chat_12345abcde"

status · enum<integer>

Available options: 0, 1, 2, 3, 4, 5

Example:

2

qualification · enum<string>

Available options: unqualified, needVerification, inProgress, qualified

Example:

"inProgress"

paused · boolean

Example:

false

lastMessage · string<date-time>

Example:

"2023-06-15T15:30:00Z"

prospect · object

Show child attributes