> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kakiyo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add prospects batch (Round Robin)

> Distributes a batch of prospects evenly across multiple campaigns using intelligent load balancing

## Overview

Distribute a batch of prospects across multiple campaigns. Kakiyo assigns prospects to campaigns with the lowest current workload and starts an asynchronous import for each campaign that receives prospects.

Each prospect can include `customData`, a string up to 3000 characters. It is saved on the created chat and available in prompts as `{{customData}}`.

## Request body

| Field         | Type            | Required | Description                                                      |
| ------------- | --------------- | -------- | ---------------------------------------------------------------- |
| `campaignIds` | `array<string>` | Yes      | Campaign IDs to distribute prospects across. Minimum 2 campaigns |
| `prospects`   | `array<object>` | Yes      | Prospects to distribute. Minimum 1 prospect                      |

## Prospect object

| Field        | Type      | Required | Description                                                           |
| ------------ | --------- | -------- | --------------------------------------------------------------------- |
| `name`       | `string`  | Yes      | Prospect full name                                                    |
| `url`        | `string`  | Yes      | LinkedIn profile URL                                                  |
| `ongoing`    | `boolean` | No       | Whether the conversation should start as ongoing. Defaults to `false` |
| `customData` | `string`  | No       | Per-conversation prompt context, max 3000 characters                  |

## Example

```bash theme={null}
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"
    ],
    "prospects": [
      {
        "name": "John Smith",
        "url": "https://linkedin.com/in/johnsmith",
        "customData": "John commented on Liam's LinkedIn post about AI outbound."
      },
      {
        "name": "Sarah Johnson",
        "url": "https://linkedin.com/in/sarahjohnson",
        "customData": "Sarah engaged with a Kakiyo post about sales automation."
      }
    ]
  }'
```

## Response

```json theme={null}
{
  "message": "Round Robin distribution processing started",
  "totalProspects": 2,
  "campaignsCount": 2,
  "successfulCampaignIds": ["campaign_12345abcde", "campaign_67890fghij"],
  "distribution": [
    {
      "campaignId": "campaign_12345abcde",
      "campaignName": "Campaign A",
      "listId": "import_list_id_a",
      "prospectsAssigned": 1
    },
    {
      "campaignId": "campaign_67890fghij",
      "campaignName": "Campaign B",
      "listId": "import_list_id_b",
      "prospectsAssigned": 1
    }
  ]
}
```

Use each returned `listId` with [Prospect Import Status](/api-reference/prospects/import-status). A prospect should be considered confirmed only when its report row has `chatCreated: true`.

## Notes

* All campaigns must belong to your team.
* Campaigns cannot be in `draft`, `disabled`, or already uploading.
* Round-robin processing is asynchronous per campaign.


## OpenAPI

````yaml POST /prospects/batch/round-robin
openapi: 3.1.0
info:
  title: Kakiyo API
  description: API for automating LinkedIn outreach campaigns with AI-powered conversations
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.kakiyo.com/v1
security:
  - bearerAuth: []
paths:
  /prospects/batch/round-robin:
    post:
      summary: Add Prospects Batch (Round Robin)
      description: >-
        Distributes a batch of prospects evenly across multiple campaigns using
        intelligent load balancing
      operationId: addProspectsBatchRoundRobin
      requestBody:
        description: Prospects to distribute across campaigns
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddProspectsBatchRoundRobinRequest'
        required: true
      responses:
        '201':
          description: Prospects distributed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Round Robin distribution processing started
                  totalProspects:
                    type: integer
                    example: 3
                  campaignsCount:
                    type: integer
                    example: 3
                  distribution:
                    type: array
                    items:
                      type: object
                      properties:
                        campaignId:
                          type: string
                          example: campaign_12345abcde
                        campaignName:
                          type: string
                          example: Q4 Enterprise Outreach
                        listId:
                          type: string
                          example: import_list_id
                        prospectsAssigned:
                          type: integer
                          example: 1
        '400':
          description: Invalid request - minimum 2 campaigns required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: invalid_campaigns
                  message:
                    type: string
                    example: Minimum 2 campaigns required for Round Robin distribution
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Campaign does not belong to your team
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: forbidden
                  message:
                    type: string
                    example: Campaign campaign_12345abcde does not belong to your team
        '404':
          description: Campaign not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: campaign_not_found
                  message:
                    type: string
                    example: Campaign campaign_12345abcde not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AddProspectsBatchRoundRobinRequest:
      type: object
      required:
        - campaignIds
        - prospects
      properties:
        campaignIds:
          type: array
          minItems: 2
          items:
            type: string
          example:
            - campaign_12345abcde
            - campaign_67890fghij
            - campaign_11223klmno
        prospects:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - name
              - url
            properties:
              name:
                type: string
                example: John Smith
              url:
                type: string
                format: uri
                example: https://linkedin.com/in/johnsmith
              ongoing:
                type: boolean
                default: false
                example: false
              customData:
                type: string
                maxLength: 3000
                example: John commented on Liam's LinkedIn post about AI outbound.
    Error:
      type: object
      properties:
        error:
          type: string
          example: validation_error
        message:
          type: string
          example: The request parameters failed validation
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                example: name
              message:
                type: string
                example: The name field is required
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````