Skip to content

Round Robin Assignment

Request

Assigns Salesforce objects to users using round-robin logic with pool management.

Overview

The Round Robin Assignment API provides intelligent assignment of Salesforce objects (leads, contacts, opportunities, accounts) to users based on configurable pools and rotation rules. It supports inactive user exclusion, reset rules, and maintains sequence tracking for fair distribution.

Request Body

  • object: Salesforce object type to assign (lead, contact, opportunity, account)
  • sf_id: Salesforce ID of the object to assign
  • pool: Round-robin pool identifier
  • exclude_inactive: Whether to exclude inactive users from assignment
  • reset_rules: Optional reset rules for the assignment

Reset Rules

  • reason: Reason for reset (e.g., 'bad_fit', 'user_request')
  • place_user_at_top: Optional user ID to place at top of rotation

Response Fields

  • success: Boolean indicating request success
  • assigned_to: User ID that was assigned
  • sequence: Current sequence number in the rotation
  • pool_size: Total number of active users in the pool
  • timestamp: ISO timestamp of the assignment
  • credits_consumed: Number of credits used
  • processing_time_ms: Processing time in milliseconds
  • cached: Whether result was from cache

Features

  • Pool Management: Organize users into assignment pools
  • Sequence Tracking: Maintains rotation sequence for fair distribution
  • Inactive User Exclusion: Automatically excludes inactive users
  • Reset Rules: Support for resetting rotation with specific reasons
  • Fair Distribution: Ensures equal distribution across active users
  • Audit Trail: Timestamps and sequence tracking for compliance

Credit Usage

Round Robin assignment consumes credits based on complexity:

  • Basic Assignment: 1 credit per assignment
  • With Reset Rules: +1 credit for reset operations
  • Pool Management: +0.5 credits for pool size calculation
Security
BearerAuth
Bodyapplication/jsonrequired
objectstring(Object)required

Salesforce object type to assign

Enum:"lead""contact""opportunity""account"
sf_idstring(Sf Id)required

Salesforce ID of the object to assign

poolstring(Pool)required

Round-robin pool identifier

exclude_inactiveboolean(Exclude Inactive)

Whether to exclude inactive users from assignment

Default:true
reset_rulesResetRules (object) or null
Any of:

Reset rules for round-robin assignment.

curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/routing/assign \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "object": "lead",
    "sf_id": "string",
    "pool": "string",
    "exclude_inactive": true,
    "reset_rules": {
      "reason": "string",
      "place_user_at_top": "string"
    }
  }'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

assigned_tostring(Assigned To)required

User ID that was assigned

sequenceinteger(Sequence)required

Current sequence number in the rotation

pool_sizeinteger(Pool Size)required

Total number of active users in the pool

timestampstring(Timestamp)required

ISO timestamp of the assignment

Response
{
  "success": true,
  "assigned_to": "005xx0002ABCDE",
  "sequence": 1245,
  "pool_size": 17,
  "timestamp": "2025-09-18T16:12:00Z",
  "credits_consumed": 1,
  "processing_time_ms": 450,
  "cached": false
}