Lead Owner Assignment API

Assign and manage ownership of leads. Owners represent the sales or marketing team member responsible for following up with a lead. Assigning owners helps your team coordinate outreach and avoid duplicate efforts.

POST /leads/{leadID}/owner

Assign or unassign an owner for a single lead. To unassign, send an empty or null owner_id.

When to Use This

• Sales handoff: Assign a lead to a sales rep when they reach a score threshold
• Territory routing: Set ownership based on lead geography or account
• Unassigning: Remove ownership when a rep leaves or lead is reassigned

Request

Parameter	Type	Required	Description
leadID	string (UUID)	Yes	Lead identifier (path parameter)

Request Body

Field	Type	Required	Description
owner_id	string or null	No	User ID of the new owner. Send null or omit to unassign.
owner_name	string or null	No	Display name of the new owner

Assign an owner:

{
  "owner_id": "user_abc123",
  "owner_name": "Jane Smith"
}

Unassign an owner:

{
  "owner_id": null,
  "owner_name": null
}

Response

200 OK

{
  "status": "ok",
  "message": "owner assigned"
}

When unassigning:

{
  "status": "ok",
  "message": "owner unassigned"
}

Example

curl -X POST "https://api.kenbun.io/leads/ld_123/owner" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"owner_id": "user_abc123", "owner_name": "Jane Smith"}'

Common Errors

Status	Meaning	Solution
400	Bad Request	Lead ID is missing or request body is invalid
401	Unauthorized	Check authentication credentials
404	Not Found	Lead does not exist in the active OU

---

POST /leads/bulk-assign-owner

Assign an owner to multiple leads at once. This is useful when routing a batch of leads to a sales rep or reassigning leads in bulk.

Request Body

Field	Type	Required	Description
lead_ids	array of strings	Yes	List of lead IDs to assign. Maximum 500 per request.
owner_id	string or null	No	User ID of the owner. Send null to unassign all.
owner_name	string or null	No	Display name of the owner

{
  "lead_ids": ["ld_001", "ld_002", "ld_003"],
  "owner_id": "user_abc123",
  "owner_name": "Jane Smith"
}

Response

200 OK

{
  "status": "ok",
  "affected": 3
}

Field	Type	Description
status	string	Always "ok" on success
affected	integer	Number of leads that were updated

Example

curl -X POST "https://api.kenbun.io/leads/bulk-assign-owner" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_ids": ["ld_001", "ld_002", "ld_003"],
    "owner_id": "user_abc123",
    "owner_name": "Jane Smith"
  }'

Common Errors

Status	Meaning	Solution
400	Bad Request	lead_ids is empty or exceeds the 500-lead limit
401	Unauthorized	Check authentication credentials

---

Notes

• Owner assignment is OU-scoped to the active Organizational Unit
• Both endpoints create an audit log entry recording the assignment action
• The owner_name field appears in lead list views and can be used for filtering
• Bulk assignment processes all leads in a single transaction for consistency

Related Endpoints

• Leads - List leads with owner information
• Lead Detail - View individual lead details
• Notification Preferences - Configure assignment alerts