Skip to main content
POST
/
api
/
v1
/
entities
/
leadlists
{
  "name": "Q1 2024 Tech Startups",
  "type": "person",
  "icpId": "660e8400-e29b-41d4-a716-446655440001",
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-03-31T23:59:59.000Z",
  "personIds": ["lead_abc123", "lead_def456"],
  "companyIds": []
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "icpId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Q1 2024 Tech Startups",
  "type": "person",
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-03-31T23:59:59.000Z",
  "personIds": ["lead_abc123", "lead_def456"],
  "companyIds": [],
  "userIds": ["user_xyz789"],
  "createdAt": "2024-01-02T10:30:00.000Z",
  "updatedAt": "2024-01-02T10:30:00.000Z"
}
Creates a new lead list for organizing and managing sales prospecting leads. The authenticated user is automatically granted access to the newly created lead list.

​
Authentication

This endpoint requires authentication. The user must be signed in to create lead lists.
The creating user is automatically added to the userIds array, granting them access to the lead list.

​
Request

​
name
string
required
The display name for the lead list. Should be descriptive of the campaign or target audience.
​
type
string
default:"person"
The type of leads this list will contain. Must be one of: - "person" - For individual contact leads (default) - "company" - For company/organization leads
​
icpId
string (UUID) | null
required
The ID of the Ideal Customer Profile (ICP) to associate with this lead list. Pass null if not linking to an ICP.
​
startDate
string
required
ISO 8601 date string indicating when the lead list campaign starts.
​
endDate
string
required
ISO 8601 date string indicating when the lead list campaign ends.
​
personIds
array
required
Array of person/lead IDs to include in the list. Used when type is "person".
​
companyIds
array
Array of company UUIDs to include in the list. Used when type is "company". Defaults to an empty array.

​
Request Examples

{
  "name": "Q1 2024 Tech Startups",
  "type": "person",
  "icpId": "660e8400-e29b-41d4-a716-446655440001",
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-03-31T23:59:59.000Z",
  "personIds": ["lead_abc123", "lead_def456"],
  "companyIds": []
}

​
Response

Returns the created lead list object with server-generated fields.
​
id
string (UUID)
required
Unique identifier for the newly created lead list.
​
icpId
string (UUID) | null
required
The ID of the associated Ideal Customer Profile.
​
name
string
required
The display name of the lead list.
​
type
string
required
The type of leads in this list ("person" or "company").
​
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 in the list.
​
companyIds
array
required
Array of company UUIDs in the list.
​
userIds
array
required
Array of user IDs with access (includes the creator).
​
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.

​
Response Examples

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "icpId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Q1 2024 Tech Startups",
  "type": "person",
  "startDate": "2024-01-01T00:00:00.000Z",
  "endDate": "2024-03-31T23:59:59.000Z",
  "personIds": ["lead_abc123", "lead_def456"],
  "companyIds": [],
  "userIds": ["user_xyz789"],
  "createdAt": "2024-01-02T10:30:00.000Z",
  "updatedAt": "2024-01-02T10:30:00.000Z"
}

​
Error Codes

Status CodeError CodeDescription
400BAD_REQUESTRequest body validation failed. Check the details field for specific issues.
401UNAUTHORIZEDUser is not authenticated. Ensure a valid session exists.
500INTERNAL_ERRORAn unexpected server error occurred.