POST /distribute_leads • Credits: 0.5 credits per call

Distribute Leads assigns one lead to one owner in a round-robin rotation. Send a POST request with the owner list and the current rotation index. The response holds the assigned owner and the next_index value that the next lead uses, and each call costs 0.5 credits.

What does Distribute Leads do?

Distribute Leads is a round-robin router for lead ownership. A sales team splits a fresh lead list across its reps, and every rep must receive a fair share. Distribute Leads holds no state between calls. You send the owner list and the current rotation position on every call, and the endpoint returns the owner at that position. The lead record itself is never part of the request body. Distribute Leads runs inside RichAPI and calls no external data provider.

Which endpoint does Distribute Leads use?

Method: POST
URL: https://api.richapi.ai/api/v1/distribute_leads
Authentication: x-api-key header
Response: Synchronous JSON
Credits: 0.5 credits per call

How to send a Distribute Leads request

Copy your API key from the RichAPI dashboard.
Set values_associated_with_labels to a comma-separated list of owner values.
Set assignment_labels to the owner names, in the same order and the same count.
Set current_index to 0 for the first lead in your list.
Send a POST request to https://api.richapi.ai/api/v1/distribute_leads.
Send the API key in the x-api-key header.
Read assigned_label and assigned_value, then write both to the lead record.
Set current_index to the next_index value from the response.
Repeat step 5 to step 8 for every lead in your list.

cURL

curl -X POST https://api.richapi.ai/api/v1/distribute_leads   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "assignment_labels": "Dana Reyes,Marcus Lee,Priya Nair",
    "values_associated_with_labels": "[email protected],[email protected],[email protected]",
    "current_index": 0
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/distribute_leads",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "assignment_labels": "Dana Reyes,Marcus Lee,Priya Nair",
        "values_associated_with_labels": "[email protected],[email protected],[email protected]",
        "current_index": 0,
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/distribute_leads", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    assignment_labels: "Dana Reyes,Marcus Lee,Priya Nair",
    values_associated_with_labels:
      "[email protected],[email protected],[email protected]",
    current_index: 0,
  }),
});

const data = await response.json();
console.log(data);

Which parameters does Distribute Leads accept?

Parameter	Type	Required	Default	Description
`values_associated_with_labels`	string	Yes	`""`	A comma-separated list of owner values, one entry for each owner. Distribute Leads trims the spaces around each entry and drops every empty entry. An empty value returns a `400` error.
`assignment_labels`	string	No	`""`	A comma-separated list of owner names, in the same order as `values_associated_with_labels`. The entry count must match. If the value is empty, `assigned_label` repeats `assigned_value`.
`current_index`	integer	No	`0`	The rotation position for this call. Distribute Leads divides the value by the owner count and uses the remainder. The value must be a whole number.

CAUTION: Send current_index as a JSON whole number. A decimal number returns a 400 error. A string or null returns a 500 error. Neither costs credits.

What does the Distribute Leads response look like?

The block below is an example response. It is the result of the request body in the cURL sample above, which holds three owners and current_index: 0.

{
  "assigned_label": "Dana Reyes",
  "assigned_value": "[email protected]",
  "assignment_index": 0,
  "next_index": 1,
  "total_assignments": 3
}

Which fields does the Distribute Leads response hold?

Field	Type	Description
`assigned_label`	string	The owner name at the selected position. It comes from `assignment_labels`. If `assignment_labels` is empty, the value repeats `assigned_value`.
`assigned_value`	string	The owner value at the selected position. It comes from `values_associated_with_labels`.
`assignment_index`	integer	The zero-based position of the assigned owner. The value is `current_index` divided by the owner count, and the remainder is the result.
`next_index`	integer	The position for the next lead. Send this value as `current_index` on your next call. The value wraps to `0` after the last owner.
`total_assignments`	integer	The number of owners that Distribute Leads found in `values_associated_with_labels`.

How does Distribute Leads decide who gets each lead?

Distribute Leads assigns exactly one owner for each call. The endpoint never accepts a lead list and never splits a lead list into buckets. The table below states every rule.

Rule	What Distribute Leads does
Owner list	Splits `values_associated_with_labels` on the comma character. Trims the spaces around each entry. Drops every empty entry. A trailing comma adds no owner.
Order	Keeps the owner order of the request body. The first owner is position `0`.
Selection	Returns the owner at position `current_index` divided by `total_assignments`, where the remainder is the position.
Rotation	Sets `next_index` to `assignment_index` plus `1`, and wraps that value to `0` after the last owner.
Round-robin	Moves one position for each call. Distribute Leads never gives a block of leads to one owner.
Labels	If `assignment_labels` is empty, `assigned_label` repeats `assigned_value`.
Label count	If `assignment_labels` is not empty, its entry count must equal the owner count. A mismatch returns a `400` error.
Duplicate owners	Keeps a repeated owner as a separate position. Two entries for one rep give that rep a double share.
Out-of-range index	Wraps any whole number. With three owners, `current_index: 100` gives `assignment_index: 1`, and `current_index: -1` gives `assignment_index: 2`.
One owner	With one owner, `assignment_index` and `next_index` are both `0` for every call.

A lead count that does not divide by the owner count leaves extra leads. The owners at the start of the list receive those extra leads. Ten leads across three owners give four leads to the first owner and three leads to each other owner.

How to assign a fresh lead list across a sales team

A sales team of three reps receives a list of ten new leads. The owner list is fixed for the whole run.

assignment_labels is Dana Reyes,Marcus Lee,Priya Nair.
values_associated_with_labels is [email protected],[email protected],[email protected].
The first call sends current_index: 0.
Every later call sends the next_index value from the call before it.

The table below shows all ten calls and the exact response of each call.

Lead	`current_index` you send	`assigned_label`	`assigned_value`	`assignment_index`	`next_index`
`[email protected]`	`0`	Dana Reyes	`[email protected]`	`0`	`1`
`[email protected]`	`1`	Marcus Lee	`[email protected]`	`1`	`2`
`[email protected]`	`2`	Priya Nair	`[email protected]`	`2`	`0`
`[email protected]`	`0`	Dana Reyes	`[email protected]`	`0`	`1`
`[email protected]`	`1`	Marcus Lee	`[email protected]`	`1`	`2`
`[email protected]`	`2`	Priya Nair	`[email protected]`	`2`	`0`
`[email protected]`	`0`	Dana Reyes	`[email protected]`	`0`	`1`
`[email protected]`	`1`	Marcus Lee	`[email protected]`	`1`	`2`
`[email protected]`	`2`	Priya Nair	`[email protected]`	`2`	`0`
`[email protected]`	`0`	Dana Reyes	`[email protected]`	`0`	`1`

Ten leads do not divide by three owners, so the split is uneven by one lead.

Owner	Leads	Lead numbers
Dana Reyes	4	1, 4, 7, 10
Marcus Lee	3	2, 5, 8
Priya Nair	3	3, 6, 9

The rotation is one owner at a time. A chunked split gives leads 1 to 4 to Dana Reyes and leads 5 to 7 to Marcus Lee. Distribute Leads never produces that result. The lead order of your list is preserved, because you control the order of the calls.

The last call returns next_index: 1. Store that value. For the next batch of leads, send 1 as current_index, and Marcus Lee receives the first lead of that batch.

The loop below runs the whole list.

import requests

OWNER_NAMES = "Dana Reyes,Marcus Lee,Priya Nair"
OWNER_EMAILS = "[email protected],[email protected],[email protected]"
LEADS = [
    "[email protected]",
    "[email protected]",
    "[email protected]",
    "[email protected]",
]

index = 0
for lead in LEADS:
    response = requests.post(
        "https://api.richapi.ai/api/v1/distribute_leads",
        headers={"x-api-key": "YOUR_API_KEY"},
        json={
            "assignment_labels": OWNER_NAMES,
            "values_associated_with_labels": OWNER_EMAILS,
            "current_index": index,
        },
        timeout=60,
    )
    response.raise_for_status()
    data = response.json()
    print(lead, "->", data["assigned_label"], data["assigned_value"])
    index = data["next_index"]

print("next_index for the following batch:", index)

How much does Distribute Leads cost?

Distribute Leads costs 0.5 credits per call. At $0.02 a credit, the rate on the 1,000 and 5,000 credit packs, one call costs $0.01. Larger packs cost less per credit. One call assigns one lead, so the call count equals the lead count. RichAPI charges the credit on a 200 response only. A 400 response, a 402 response, a 403 response, a 429 response and a 500 response cost no credits.

Calls	Credits	Cost
1	0.5	$0.01
10	5	$0.10
500	250	$5.00
1,000	500	$10.00
10,000	5,000	$100.00

CAUTION: A list of 500 leads needs 500 calls and costs 250 credits. Count the leads, not the owners, before you start a run.

Which errors can Distribute Leads return?

Status	Meaning	What to do
`400`	The request body is missing, the JSON is not valid, `values_associated_with_labels` is absent, empty or not a string, `current_index` is a decimal number, or the label count does not match the owner count.	Read the `error` field, then correct the parameter that it names.
`401`	The API key is missing, wrong or revoked.	Send a valid key in the `x-api-key` header.
`402`	The organization has no credits left, or the team reached its monthly spend limit.	Buy credits in the RichAPI dashboard.
`403`	This API key has no access to this endpoint (`Endpoint not available on your plan`).	Call `GET /api/v1/my-endpoints` to see the endpoints that this key can use. Contact support for access.
`405`	The request used a method other than `POST`.	Send the request again with the `POST` method.
`429`	The request rate is over the limit.	Wait, then send the request again.
`500`	`current_index` is a string or `null`, or the API failed.	Send `current_index` as a JSON whole number. If the failure repeats, contact support.

Every error response holds an error field with a plain-language message. The table below lists the exact 400 messages.

`error` message	Cause
`Request body required`	The request carried no body.
`Invalid JSON`	The body is not valid JSON.
`Request body must be a JSON object`	The body is a JSON array or a JSON scalar.
`Missing required field: values_associated_with_labels`	The parameter is absent or `null`.
`values_associated_with_labels is required`	The value holds only spaces.
`values_associated_with_labels cannot be empty`	The value holds commas but no owner, for example `,,,`.
`Label count (2) must match value count (3)`	The two lists hold a different number of entries.

Frequently asked questions

Does Distribute Leads split a lead list into buckets?

No. Distribute Leads assigns one owner for each call, and it never accepts a lead list. Send one request for each lead, and carry next_index forward as current_index.

Do I send the lead email address to Distribute Leads?

No. The request body holds the owner list and the rotation index only. Your code attaches the returned owner to the lead record, so no lead data reaches the endpoint.

How does Distribute Leads handle an uneven lead count?

The owners at the start of the list receive the extra leads. Ten leads across three owners, from current_index: 0, give four leads to the first owner and three leads to each other owner.

Can I give one sales rep a larger share of the leads?

Yes. Repeat that rep in values_associated_with_labels, and repeat the matching name in assignment_labels. Two entries for one rep double the share of that rep.

What is the difference between assignment_index and next_index?

The assignment_index field is the position of the owner in this response. The next_index field is the position for your next call, and it wraps to 0 after the last owner.

How do I restart the rotation after a lost next_index value?

Send any whole number as current_index, and the rotation restarts from that position. To keep a fair share across batches, store next_index after the last lead of every batch.

Is Distribute Leads synchronous?

Yes. Distribute Leads returns the result in the same response. The endpoint needs no second call, no polling and no webhook.

Distribute Leads API