Add prospects batch (Round Robin)

Overview

Distribute a batch of prospects evenly across multiple campaigns using an intelligent Round Robin load balancing algorithm. This endpoint automatically assigns prospects to campaigns based on their current workload, ensuring optimal distribution and preventing any single campaign from being overloaded.

Use Cases

Multi-Agent Distribution: Spread prospects across multiple LinkedIn agents for faster processing
Load Balancing: Automatically balance workload across multiple campaigns
A/B Testing: Distribute identical prospects across different campaign strategies
Geographic Distribution: Route prospects to region-specific campaigns
Parallel Processing: Scale your outreach by running multiple campaigns simultaneously

Key Features

Smart Load Balancing: Automatically assigns prospects to campaigns with the lowest current workload
Minimum 2 Campaigns: Requires at least 2 campaigns for distribution
Real-time Distribution: Prospects are distributed and processed immediately
Detailed Distribution Report: Returns information about how prospects were assigned
Ownership Verification: Ensures all specified campaigns belong to your team

How It Works

The Round Robin algorithm:

Fetches all campaigns and verifies ownership and existence
Sorts campaigns by current prospect count (ascending - lowest first)
Assigns each prospect to the campaign with the lowest current workload
Updates counts in memory for accurate distribution
Processes prospects asynchronously for each campaign

This ensures an even distribution where no campaign gets overloaded, optimizing your outreach efficiency.

Testing Example

curl -X POST "https://api.kakiyo.com/v1/prospects/batch/round-robin" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignIds": [
      "campaign_12345abcde",
      "campaign_67890fghij",
      "campaign_11223klmno"
    ],
    "prospects": [
      {
        "name": "John Smith",
        "url": "https://linkedin.com/in/johnsmith",
        "additionalFields": [
          {
            "fieldName": "company",
            "fieldValue": "TechCorp Inc"
          },
          {
            "fieldName": "title",
            "fieldValue": "VP of Sales"
          }
        ]
      },
      {
        "name": "Sarah Johnson",
        "url": "https://linkedin.com/in/sarahjohnson",
        "additionalFields": [
          {
            "fieldName": "company",
            "fieldValue": "InnovateTech"
          },
          {
            "fieldName": "title",
            "fieldValue": "Head of Marketing"
          }
        ]
      },
      {
        "name": "Michael Chen",
        "url": "https://linkedin.com/in/michaelchen",
        "additionalFields": [
          {
            "fieldName": "company",
            "fieldValue": "Global Solutions Ltd"
          },
          {
            "fieldName": "title",
            "fieldValue": "CEO"
          }
        ]
      }
    ]
  }'

// JavaScript/Node.js
const addProspectsRoundRobin = async (data) => {
  const response = await fetch('https://api.kakiyo.com/v1/prospects/batch/round-robin', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  return await response.json();
};

// Usage example
const distribution = await addProspectsRoundRobin({
  campaignIds: [
    'campaign_12345abcde',
    'campaign_67890fghij',
    'campaign_11223klmno'
  ],
  prospects: [
    {
      name: 'John Smith',
      url: 'https://linkedin.com/in/johnsmith',
      additionalFields: [
        {
          fieldName: 'company',
          fieldValue: 'TechCorp Inc'
        },
        {
          fieldName: 'title',
          fieldValue: 'VP of Sales'
        }
      ]
    },
    {
      name: 'Sarah Johnson',
      url: 'https://linkedin.com/in/sarahjohnson',
      additionalFields: [
        {
          fieldName: 'company',
          fieldValue: 'InnovateTech'
        },
        {
          fieldName: 'title',
          fieldValue: 'Head of Marketing'
        }
      ]
    },
    {
      name: 'Michael Chen',
      url: 'https://linkedin.com/in/michaelchen',
      additionalFields: [
        {
          fieldName: 'company',
          fieldValue: 'Global Solutions Ltd'
        },
        {
          fieldName: 'title',
          fieldValue: 'CEO'
        }
      ]
    }
  ]
});

console.log('Distribution Result:', distribution);

# Python
import requests

def add_prospects_round_robin(data):
    """Distribute prospects across multiple campaigns using Round Robin"""
    response = requests.post(
        'https://api.kakiyo.com/v1/prospects/batch/round-robin',
        json=data,
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        }
    )
    
    return response.json()

# Usage example
data = {
    'campaignIds': [
        'campaign_12345abcde',
        'campaign_67890fghij',
        'campaign_11223klmno'
    ],
    'prospects': [
        {
            'name': 'John Smith',
            'url': 'https://linkedin.com/in/johnsmith',
            'additionalFields': [
                {
                    'fieldName': 'company',
                    'fieldValue': 'TechCorp Inc'
                },
                {
                    'fieldName': 'title',
                    'fieldValue': 'VP of Sales'
                }
            ]
        },
        {
            'name': 'Sarah Johnson',
            'url': 'https://linkedin.com/in/sarahjohnson',
            'additionalFields': [
                {
                    'fieldName': 'company',
                    'fieldValue': 'InnovateTech'
                },
                {
                    'fieldName': 'title',
                    'fieldValue': 'Head of Marketing'
                }
            ]
        },
        {
            'name': 'Michael Chen',
            'url': 'https://linkedin.com/in/michaelchen',
            'additionalFields': [
                {
                    'fieldName': 'company',
                    'fieldValue': 'Global Solutions Ltd'
                },
                {
                    'fieldName': 'title',
                    'fieldValue': 'CEO'
                }
            ]
        }
    ]
}

result = add_prospects_round_robin(data)
print('Distribution Result:', result)

Request Body

Required Fields

Field	Type	Description
`campaignIds`	`array<string>`	Array of campaign IDs to distribute prospects across. Minimum 2 campaigns required
`prospects`	`array<object>`	Array of prospect objects to be distributed. Minimum 1 prospect required

Prospect Object Structure

Field	Type	Required	Description
`name`	`string`	Yes	Full name of the prospect
`url`	`string`	Yes	LinkedIn profile URL (must include `linkedin.com/in/`)
`ongoing`	`boolean`	No	Whether the prospect conversation is ongoing (default: `false`)
`additionalFields`	`array<object>`	No	Array of custom field objects with additional prospect information

Additional Fields Object

Field	Type	Required	Description
`fieldName`	`string`	Yes	Name of the custom field (e.g., “company”, “title”)
`fieldValue`	`string`	Yes	Value of the custom field

Response Format

Success Response (201 Created)

{
  "message": "Round Robin distribution completed",
  "totalProspects": 3,
  "campaignsCount": 3,
  "distribution": [
    {
      "campaignId": "campaign_12345abcde",
      "campaignName": "Q4 Enterprise Outreach",
      "prospectsAssigned": 1
    },
    {
      "campaignId": "campaign_67890fghij",
      "campaignName": "Tech Startups Campaign",
      "prospectsAssigned": 1
    },
    {
      "campaignId": "campaign_11223klmno",
      "campaignName": "Executive Outreach",
      "prospectsAssigned": 1
    }
  ]
}

Error Responses

400 Bad Request - Invalid Campaigns

{
  "error": "invalid_campaigns",
  "message": "Minimum 2 campaigns required for Round Robin distribution"
}

404 Not Found - Campaign Not Found

{
  "error": "campaign_not_found",
  "message": "Campaign campaign_12345abcde not found"
}

403 Forbidden - No Access

{
  "error": "forbidden",
  "message": "Campaign campaign_12345abcde does not belong to your team"
}

500 Internal Server Error

{
  "error": "internal_error",
  "message": "An internal error occurred"
}

Distribution Algorithm Details

The Round Robin algorithm uses load balancing instead of simple circular distribution:

Traditional Round Robin

Assigns prospects in a circular pattern regardless of existing load:

Campaign A → Campaign B → Campaign C → Campaign A…

Load Balanced Round Robin (Used Here)

Assigns prospects to the campaign with the lowest current workload:

Fetch all campaigns and their current prospect counts
For each prospect:
- Find campaign with lowest prospect count
- Assign prospect to that campaign
- Increment that campaign’s count in memory
Continue until all prospects are assigned

Example Distribution: Starting state:

Campaign A: 10 prospects
Campaign B: 15 prospects
Campaign C: 8 prospects

Adding 5 new prospects:

Prospect 1 → Campaign C (8+1=9)
Prospect 2 → Campaign A (10+1=11)
Prospect 3 → Campaign C (9+1=10)
Prospect 4 → Campaign C (10+1=11)
Prospect 5 → Campaign A (11+1=12)

Final state:

Campaign A: 12 prospects (+2)
Campaign B: 15 prospects (+0)
Campaign C: 11 prospects (+3)

This ensures optimal load distribution across all campaigns.

Best Practices

Campaign Preparation: Ensure all campaigns are properly configured before distribution
Minimum Campaigns: Always provide at least 2 campaigns for meaningful distribution
Campaign Similarity: Use campaigns with similar configurations for consistent prospect experience
Monitor Distribution: Check the distribution report to ensure balanced assignment
Bulk Operations: This endpoint is ideal for large prospect lists (100+ prospects)
Campaign Capacity: Verify campaigns have sufficient agent capacity for assigned prospects
URL Validation: Ensure all LinkedIn URLs are valid and properly formatted

Common Additional Fields

Include relevant information to personalize outreach:

company: Company name
title: Job title
industry: Industry sector
location: Geographic location
employees: Company size
revenue: Company revenue
source: Lead source or origin
notes: Custom research notes
priority: Lead priority level

Integration Examples

Large-Scale Distribution

// Distribute 1000 prospects across 5 campaigns
const distributeAtScale = async (allProspects, campaigns) => {
  // Split into batches if needed
  const batchSize = 100;
  const batches = [];
  
  for (let i = 0; i < allProspects.length; i += batchSize) {
    batches.push(allProspects.slice(i, i + batchSize));
  }
  
  // Process batches sequentially
  for (const batch of batches) {
    const result = await addProspectsRoundRobin({
      campaignIds: campaigns,
      prospects: batch
    });
    
    console.log(`Batch processed: ${result.distribution}`);
    
    // Wait between batches to avoid rate limits
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
};

Geographic Distribution

// Route prospects to region-specific campaigns
const distributeByRegion = async (prospects) => {
  const regionalCampaigns = {
    'North America': ['campaign_na_001', 'campaign_na_002'],
    'Europe': ['campaign_eu_001', 'campaign_eu_002'],
    'Asia': ['campaign_asia_001', 'campaign_asia_002']
  };
  
  // Group prospects by region
  const prospectsByRegion = groupProspectsByRegion(prospects);
  
  // Distribute each region's prospects to their campaigns
  for (const [region, regionProspects] of Object.entries(prospectsByRegion)) {
    await addProspectsRoundRobin({
      campaignIds: regionalCampaigns[region],
      prospects: regionProspects
    });
  }
};

A/B Testing Setup

// Distribute identical prospects across campaigns with different strategies
const setupABTest = async (prospects) => {
  // Create two identical campaigns with different approaches
  const campaignA = 'campaign_strategy_a'; // Friendly approach
  const campaignB = 'campaign_strategy_b'; // Professional approach
  
  const result = await addProspectsRoundRobin({
    campaignIds: [campaignA, campaignB],
    prospects: prospects
  });
  
  console.log('A/B test distribution:', result.distribution);
  // Monitor performance to determine which strategy performs better
};

Performance Considerations

Processing Time: Prospects are processed asynchronously after distribution
Campaign Status: Campaigns must be active to receive prospects
Rate Limits: Respect API rate limits when distributing large batches
Concurrent Requests: Process batches sequentially to ensure accurate distribution
Memory Efficiency: Algorithm uses in-memory counting for optimal performance

Next Steps

After distributing prospects:

Monitor Campaign Performance: Check analytics for each campaign
Balance Adjustments: Add more prospects to underperforming campaigns
Agent Monitoring: Ensure LinkedIn agents are active and processing prospects
Qualification Tracking: Monitor qualification rates across campaigns
Optimize Distribution: Adjust campaign count based on performance metrics

Add Single Prospect - Add individual prospects to a campaign
Add Batch Prospects - Add multiple prospects to a single campaign
List Prospects - View prospects in a campaign
Campaign Stats - Monitor campaign performance

Authorizations

Authorization

string

header

required

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

Body

application/json

Prospects to distribute across campaigns

campaignIds

string[]

required

Minimum array length: 2

Example:

[
  "campaign_12345abcde",
  "campaign_67890fghij",
  "campaign_11223klmno"
]

prospects

object[]

required

Minimum array length: 1

Show child attributes

Response

Prospects distributed successfully

message

string

Example:

"Round Robin distribution completed"

totalProspects

integer

Example:

3

campaignsCount

integer

Example:

3

distribution

object[]

Show child attributes

API Documentation

Analytics

Models

Campaigns

Prospects

Products

Prompts

Agents

Webhooks

Authentication

​Overview

​Use Cases

​Key Features

​How It Works

​Testing Example

​Request Body

​Required Fields

​Prospect Object Structure

​Additional Fields Object

​Response Format

​Success Response (201 Created)

​Error Responses

​400 Bad Request - Invalid Campaigns

​404 Not Found - Campaign Not Found

​403 Forbidden - No Access

​500 Internal Server Error

​Distribution Algorithm Details

​Traditional Round Robin

​Load Balanced Round Robin (Used Here)

​Best Practices

​Common Additional Fields

​Integration Examples

​Large-Scale Distribution

​Geographic Distribution

​A/B Testing Setup

​Performance Considerations

​Next Steps

​Related Endpoints

Authorizations

Body

Response

Overview

Use Cases

Key Features

How It Works

Testing Example

Request Body

Required Fields

Prospect Object Structure

Additional Fields Object

Response Format

Success Response (201 Created)

Error Responses

400 Bad Request - Invalid Campaigns

404 Not Found - Campaign Not Found

403 Forbidden - No Access

500 Internal Server Error

Distribution Algorithm Details

Traditional Round Robin

Load Balanced Round Robin (Used Here)

Best Practices

Common Additional Fields

Integration Examples

Large-Scale Distribution

Geographic Distribution

A/B Testing Setup

Performance Considerations

Next Steps

Related Endpoints