{
"name": "Q1 2024 Tech Startups - Updated"
}
{
"personIds": ["lead_abc123", "lead_def456", "lead_ghi789"]
}
{
"companyIds": [
"770e8400-e29b-41d4-a716-446655440001",
"880e8400-e29b-41d4-a716-446655440002"
]
}
{
"name": "Enterprise Accounts - Final",
"companyIds": ["770e8400-e29b-41d4-a716-446655440001"]
}
{
"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": {
"code": "VALIDATION_ERROR",
"message": "Cannot update personIds on a company-type list. Use companyIds instead."
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid uuid"
}
}
{
"error": {
"code": "FORBIDDEN",
"message": "You do not have access to this lead list"
}
}
{
"error": {
"code": "NOT_FOUND",
"message": "LeadList with id 'invalid-id' not found"
}
}
Lead Lists
Update Lead List
Updates a lead list’s name and/or associated leads
PATCH
/
api
/
v1
/
entities
/
leadlists
/
{id}
{
"name": "Q1 2024 Tech Startups - Updated"
}
{
"personIds": ["lead_abc123", "lead_def456", "lead_ghi789"]
}
{
"companyIds": [
"770e8400-e29b-41d4-a716-446655440001",
"880e8400-e29b-41d4-a716-446655440002"
]
}
{
"name": "Enterprise Accounts - Final",
"companyIds": ["770e8400-e29b-41d4-a716-446655440001"]
}
{
"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": {
"code": "VALIDATION_ERROR",
"message": "Cannot update personIds on a company-type list. Use companyIds instead."
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid uuid"
}
}
{
"error": {
"code": "FORBIDDEN",
"message": "You do not have access to this lead list"
}
}
{
"error": {
"code": "NOT_FOUND",
"message": "LeadList with id 'invalid-id' not found"
}
}
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
string (UUID)
required
The unique identifier of the lead list to update.
string
The new display name for the lead list. If omitted, the name remains
unchanged.
array
Array of person/lead IDs to set on the list. Only valid for person-type
lists. Replaces the existing person IDs entirely.
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"
}
{
"personIds": ["lead_abc123", "lead_def456", "lead_ghi789"]
}
{
"companyIds": [
"770e8400-e29b-41d4-a716-446655440001",
"880e8400-e29b-41d4-a716-446655440002"
]
}
{
"name": "Enterprise Accounts - Final",
"companyIds": ["770e8400-e29b-41d4-a716-446655440001"]
}
Response
Returns the updated lead list with fully populated persons or companies.Base Fields
string (UUID)
required
Unique identifier for the lead list.
string (UUID) | null
required
The ID of the associated Ideal Customer Profile.
string
required
The updated display name of the lead list.
string
required
The type of leads in this list (
"person" or "company"). This field is
immutable.string
required
ISO 8601 timestamp for the campaign start date.
string
required
ISO 8601 timestamp for the campaign end date.
array
required
Array of person/lead IDs (updated if provided for person-type lists).
array
required
Array of company UUIDs (updated if provided for company-type lists).
array
required
Array of user IDs with access to this lead list.
string
required
ISO 8601 timestamp of when the lead list was created.
string
required
ISO 8601 timestamp of when the lead list was last updated. Updated on each
modification.
Populated Fields
array | undefined
Populated when
type is "person". Array of fully hydrated person objects
with nested company and Bullhorn client contact data.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": {
"code": "VALIDATION_ERROR",
"message": "Cannot update personIds on a company-type list. Use companyIds instead."
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid uuid"
}
}
{
"error": {
"code": "FORBIDDEN",
"message": "You do not have access to this lead list"
}
}
{
"error": {
"code": "NOT_FOUND",
"message": "LeadList with id 'invalid-id' not found"
}
}
Error Codes
| Status Code | Error Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Request body validation failed. Common causes: attempting to update personIds on a company-type list (or vice versa), or providing invalid UUIDs for companyIds. |
| 403 | FORBIDDEN | User does not have access to this lead list. Only users in userIds or admins can update the list. |
| 404 | NOT_FOUND | No lead list exists with the specified ID. |
| 500 | INTERNAL_ERROR | An unexpected server error occurred. |
Authorization Rules
- Access Control: Only users whose ID is in the
userIdsarray can update the lead list. - Admin Override: Users with the admin role can update any lead list regardless of
userIds. - Type Immutability: The
typefield cannot be changed after creation. Attempting to switch between person and company lists will fail.