CRM Leads
The Leads API allows you to manage potential customers in your CRM system. Leads represent individuals or businesses that have shown interest in your products or services but haven’t yet become customers.
Lead Data Structure
A lead contains various properties to help you track and manage potential customers:
- Basic contact information (name, email, phone)
- Company and professional details
- Sales-related information (source, status, process stage)
- CRM metadata (assigned to, notes, last contact)
Account Context
Like other resources in the Pulse API, leads 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 Leads
Listing Leads
GET /leads
Retrieve a paginated list of leads with optional filtering and sorting.
Output:
Query Parameters
- page: Page number (default: 1)
- pageSize: Number of leads per page (default: 10)
- search: Text search across all text fields
- sort: Comma-separated list of fields to sort by, prefix with - for descending order (default: “-createdAt”)
- archived: Filter by archived status (default: false)
- Additional filters: Any lead property can be used as a filter parameter
Examples
Output:
Creating a Lead
POST /leads
Create a new lead with the provided data.
Output:
Getting a Lead by ID
GET /leads/{leadId}
Retrieve a specific lead by its ID.
Output:
Updating a Lead
PATCH /leads/{leadId}
Update an existing lead with new data.
Output:
Deleting a Lead
DELETE /leads/{leadId}
Permanently delete a lead from the system.
Output:
Managing Lead Archives
To maintain a clean database while preserving historical data, you can archive leads instead of deleting them.
Archiving a Lead
POST /leads/{leadId}/archive
Move a lead to the archive state.
Output:
Unarchiving a Lead
DELETE /leads/{leadId}/archive
Restore a lead from the archive state.
Output:
Response Format
When retrieving a list of leads, the response will include pagination details:
{ "data": [ { "id": 1, "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+15555555555", "company": "Acme Inc", "jobTitle": "CTO", "processStage": "Initial Contact", "archived": false, "lastContacted": "2023-06-15T14:30:00Z", "createdAt": "2023-06-01T09:00:00Z", "updatedAt": "2023-06-15T14:30:00Z" } // More leads... ], "totalCount": 142, "totalPages": 8, "currentPage": 1}When retrieving or updating a single lead, the response will be the lead object itself.
Best Practices
-
Pagination: Always use pagination when retrieving multiple leads to improve performance and avoid timeout issues.
-
Filtering: Use specific filters rather than retrieving all leads and filtering client-side.
-
Archiving vs. Deleting: Prefer archiving leads rather than deleting them to maintain historical data.
-
Consistent Updates: When updating leads, only include the fields that actually need to change.
-
Date Handling: For date fields, use ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ) to ensure consistency.
References
For more details, see the API Reference documentation: