Skip to main content
PATCH
/
api
/
v1
/
entities
/
leadlists
/
{id}
{
  "name": "Q1 2024 Tech Startups - Updated"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "icpId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Q1 2024 Tech Startups - Updated",
  "type": "person",
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-03-31T23:59:59.000Z",
  "personIds": ["lead_abc123", "lead_def456", "lead_ghi789"],
  "companyIds": [],
  "userIds": ["user_xyz789"],
  "createdAt": "2024-01-02T10:30:00.000Z",
  "updatedAt": "2024-01-15T08:45:00.000Z",
  "persons": [
    {
      "id": "lead_abc123",
      "firstName": "Jane",
      "lastName": "Doe",
      "jobTitle": "VP of Engineering",
      "company": {
        "id": "comp_789",
        "name": "Tech Startup Inc"
      }
    }
  ]
}
Updates an existing lead list. You can modify the list name and the associated person or company IDs. The list type is immutable and determines which ID field can be updated.

​
Authentication

This endpoint requires authentication. Only users with access to the lead list (or admin users) can update it.
The type field is immutable. Person-type lists can only update personIds, and company-type lists can only update companyIds. Attempting to update the wrong ID field will result in a validation error.

​
Request

​
id
string (UUID)
required
The unique identifier of the lead list to update.
​
name
string
The new display name for the lead list. If omitted, the name remains unchanged.
​
personIds
array
Array of person/lead IDs to set on the list. Only valid for person-type lists. Replaces the existing person IDs entirely.
​
companyIds
array
Array of company UUIDs to set on the list. Only valid for company-type lists. Must be valid UUIDs. Replaces the existing company IDs entirely.

​
Request Examples

{
  "name": "Q1 2024 Tech Startups - Updated"
}

​
Response

Returns the updated lead list with fully populated persons or companies.

​
Base Fields

​
id
string (UUID)
required
Unique identifier for the lead list.
​
icpId
string (UUID) | null
required
The ID of the associated Ideal Customer Profile.
​
name
string
required
The updated display name of the lead list.
​
type
string
required
The type of leads in this list ("person" or "company"). This field is immutable.
​
startDate
string
required
ISO 8601 timestamp for the campaign start date.
​
endDate
string
required
ISO 8601 timestamp for the campaign end date.
​
personIds
array
required
Array of person/lead IDs (updated if provided for person-type lists).
​
companyIds
array
required
Array of company UUIDs (updated if provided for company-type lists).
​
userIds
array
required
Array of user IDs with access to this lead list.
​
createdAt
string
required
ISO 8601 timestamp of when the lead list was created.
​
updatedAt
string
required
ISO 8601 timestamp of when the lead list was last updated. Updated on each modification.

​
Populated Fields

​
persons
array | undefined
Populated when type is "person". Array of fully hydrated person objects with nested company and Bullhorn client contact data.
​
companies
array | undefined
Populated when type is "company". Array of company objects.

​
Response Examples

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "icpId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Q1 2024 Tech Startups - Updated",
  "type": "person",
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-03-31T23:59:59.000Z",
  "personIds": ["lead_abc123", "lead_def456", "lead_ghi789"],
  "companyIds": [],
  "userIds": ["user_xyz789"],
  "createdAt": "2024-01-02T10:30:00.000Z",
  "updatedAt": "2024-01-15T08:45:00.000Z",
  "persons": [
    {
      "id": "lead_abc123",
      "firstName": "Jane",
      "lastName": "Doe",
      "jobTitle": "VP of Engineering",
      "company": {
        "id": "comp_789",
        "name": "Tech Startup Inc"
      }
    }
  ]
}

​
Error Codes

Status CodeError CodeDescription
400VALIDATION_ERRORRequest body validation failed. Common causes: attempting to update personIds on a company-type list (or vice versa), or providing invalid UUIDs for companyIds.
403FORBIDDENUser does not have access to this lead list. Only users in userIds or admins can update the list.
404NOT_FOUNDNo lead list exists with the specified ID.
500INTERNAL_ERRORAn unexpected server error occurred.

​
Authorization Rules

  • Access Control: Only users whose ID is in the userIds array can update the lead list.
  • Admin Override: Users with the admin role can update any lead list regardless of userIds.
  • Type Immutability: The type field cannot be changed after creation. Attempting to switch between person and company lists will fail.