CRM Lead Assignment and Auto Rotation

The Lead Rotations API allows you to set up automatic lead assignment systems that rotate through your team members. This feature helps distribute leads fairly and ensures that each sales representative gets an equal opportunity to work with new leads.

Lead Rotation Data Structure

A lead rotation configuration consists of:

Name: Identifier for the rotation (using “default” creates a fallback rotation)
Status: Can be “active”, “archived”, or “queued”
User Rotation Array: Ordered list of user emails to assign leads to
Current Rotation Index: Tracks the current position in the rotation
Optional Team Association: Link rotation to specific teams

Account Context

Like other resources in the Pulse API, lead rotations are associated with a specific account. Your primary account will be used unless you include the desired account in your requests using the X-Account-Id header.

Managing Lead Rotations

Creating a Default Lead Rotation

POST /lead-rotations

Create a default lead rotation that will be used when no team-specific rotation exists. The default rotation is identified by setting the name to “default”.

Output:

Creating a Team-Specific Rotation

POST /lead-rotations

For organizations with multiple teams, you can create separate rotation systems for each team.

Output:

Adding Users to the Rotation

Before setting up lead rotations, ensure you have users in your account to include in the rotation. Here’s how to create a new user:

POST /users

Output:

Updating a Lead Rotation

PATCH /lead-rotations/{rotationId}

You can update an existing lead rotation to add new users, change the order, or modify other properties.

Output:

Changing a Rotation’s Status

PATCH /lead-rotations/{rotationId}/status

You can activate, pause, or deactivate a lead rotation by updating its status.

Output:

Available Status Options:

active: Currently in use for lead assignments
archived: Archived and not in use, but preserved for historical purposes
queued: the next lead rotation to use once the current active rotation is complete

Manually Getting the Next User

GET /lead-rotations/{rotationId}/next-user

If you need to manually check who would be next in line, use this endpoint:

Output:

Testing Lead Assignment

Creating a Lead with Automatic Assignment

Let’s create some leads to see the automatic assignment in action. When you create a lead without specifying an assignedTo value, the system will use the appropriate lead rotation.

POST /leads

Output:

Advanced Lead Rotation Features

Queued Rotations

You can create a queued rotation that will automatically activate once the current active rotation completes a full cycle.

POST /lead-rotations

Output:

Listing Lead Rotations

GET /lead-rotations

View all your lead rotations with optional filtering by status:

Output:

Query Parameters

page: Page number (default: 1)
pageSize: Number of rotations per page (default: 10)
status: Filter by status (active, archived, queued)
teamId: Filter by associated team
sort: Comma-separated list of fields to sort by, prefix with - for descending order (default: “-createdAt”)

Assignment Logic

When a new lead is created:

If assignedTo is specified in the lead data, that assignment is used
Otherwise, if the lead has a teamId:
- The system looks for an active rotation for that team
- If found, the next user in that rotation is assigned
If no team-specific rotation applies:
- The system looks for a default rotation (name=“default”)
- If found, the next user in the default rotation is assigned
If no rotation applies, the lead remains unassigned

Lead Rotation Response Format

When retrieving a list of lead rotations, the response will include:

{
  "data": [
    {
      "id": 1,
      "account_id": "acc_12345",
      "name": "default",
      "status": "active",
      "teamId": null,
      "currentRotationIndex": 2,
      "userRotationArray": [
        "user1@example.com",
        "user2@example.com",
        "user3@example.com"
      ],
      "createdBy": "admin@example.com",
      "updatedBy": "admin@example.com",
      "createdAt": "2023-06-01T09:00:00Z",
      "updatedAt": "2023-06-15T14:30:00Z"
    }
    // More rotations...
  ],
  "totalCount": 3,
  "totalPages": 1,
  "currentPage": 1
}

Best Practices

Create a Default Rotation: Always set up a default rotation as a fallback for leads without team-specific assignments.
Balance Team Skills: Ensure your rotation order considers skill levels and specialties to provide quality service.
Regular Audits: Periodically review rotation assignments to ensure they’re balanced and effective.
Status Management: Use the status field to temporarily archive rotations during team absences or holidays.
Team-Specific Teams: For multi-team organizations, create dedicated rotations for each team to ensure leads are handled by specialists.
Queued Rotations: Plan ahead by setting up queued rotations for upcoming team changes.
Monitor Lead Distribution: Regularly check lead assignments to ensure the rotation is working as expected.

References

For more details, see the API Reference documentation:

GET /lead-rotations

POST /lead-rotations

GET /lead-rotations/{rotationId}

PATCH /lead-rotations/{rotationId}

DELETE /lead-rotations/{rotationId}

PATCH /lead-rotations/{rotationId}/status

POST /lead-rotations/{rotationId}/next-user