{
"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": []
}
{
"name": "Enterprise Accounts Q2",
"type": "company",
"icpId": null,
"startDate": "2024-04-01T00:00:00.000Z",
"endDate": "2024-06-30T23:59:59.000Z",
"personIds": [],
"companyIds": ["770e8400-e29b-41d4-a716-446655440001"]
}
{
"name": "New Campaign",
"icpId": null,
"startDate": "2024-01-01T00:00:00.000Z",
"endDate": "2024-12-31T23:59:59.000Z"
}
{
"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": {
"code": "BAD_REQUEST",
"message": "Invalid request body",
"details": [
{
"path": ["name"],
"message": "Required"
}
]
}
}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Unauthorized"
}
}
Lead Lists
Create Lead List
Creates a new lead list for organizing prospecting leads
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": []
}
{
"name": "Enterprise Accounts Q2",
"type": "company",
"icpId": null,
"startDate": "2024-04-01T00:00:00.000Z",
"endDate": "2024-06-30T23:59:59.000Z",
"personIds": [],
"companyIds": ["770e8400-e29b-41d4-a716-446655440001"]
}
{
"name": "New Campaign",
"icpId": null,
"startDate": "2024-01-01T00:00:00.000Z",
"endDate": "2024-12-31T23:59:59.000Z"
}
{
"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": {
"code": "BAD_REQUEST",
"message": "Invalid request body",
"details": [
{
"path": ["name"],
"message": "Required"
}
]
}
}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Unauthorized"
}
}
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
string
required
The display name for the lead list. Should be descriptive of the campaign or
target audience.
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
leadsstring (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.string
required
ISO 8601 date string indicating when the lead list campaign starts.
string
required
ISO 8601 date string indicating when the lead list campaign ends.
array
required
Array of person/lead IDs to include in the list. Used when
type is
"person".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": []
}
{
"name": "Enterprise Accounts Q2",
"type": "company",
"icpId": null,
"startDate": "2024-04-01T00:00:00.000Z",
"endDate": "2024-06-30T23:59:59.000Z",
"personIds": [],
"companyIds": ["770e8400-e29b-41d4-a716-446655440001"]
}
{
"name": "New Campaign",
"icpId": null,
"startDate": "2024-01-01T00:00:00.000Z",
"endDate": "2024-12-31T23:59:59.000Z"
}
Response
Returns the created lead list object with server-generated fields.string (UUID)
required
Unique identifier for the newly created lead list.
string (UUID) | null
required
The ID of the associated Ideal Customer Profile.
string
required
The display name of the lead list.
string
required
The type of leads in this list (
"person" or "company").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 in the list.
array
required
Array of company UUIDs in the list.
array
required
Array of user IDs with access (includes the creator).
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.
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": {
"code": "BAD_REQUEST",
"message": "Invalid request body",
"details": [
{
"path": ["name"],
"message": "Required"
}
]
}
}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Unauthorized"
}
}
Error Codes
| Status Code | Error Code | Description |
|---|---|---|
| 400 | BAD_REQUEST | Request body validation failed. Check the details field for specific issues. |
| 401 | UNAUTHORIZED | User is not authenticated. Ensure a valid session exists. |
| 500 | INTERNAL_ERROR | An unexpected server error occurred. |