Leads
Endpoints
Available endpoints for managing leads.
| Method | Path | Description |
|---|
GET | /api/leads/ | List leads |
POST | /api/leads/ | Create a lead |
GET | /api/leads/{id}/ | Get a lead |
PATCH | /api/leads/{id}/ | Update a lead |
DELETE | /api/leads/{id}/ | Delete a lead |
POST | /api/leads/{id}/convert/ | Convert lead to contact |
Leads
List Leads
GET /api/leads/
Authorization: Bearer <token>
Retrieve a paginated list of leads with optional filters.
Query Parameters:
| Parameter | Type | Description |
|---|
page | integer | Page number |
limit | integer | Results per page (max: 100) |
status | string | Filter by status |
source | string | Filter by lead source |
assignedTo | string | Filter by assigned user ID |
search | string | Search by name, email, or company |
createdAfter | ISO8601 | Filter by creation date |
{
"count": 88,
"next": "https://api.parsalink.io/api/leads/?page=2",
"previous": null,
"results": [
{
"id": "ld_01HX...",
"firstName": "Marcus",
"lastName": "Rodriguez",
"email": "[email protected]",
"phone": "+15551112222",
"company": "GrowthCo",
"status": "contacted",
"source": "website_form",
"assignedTo": "usr_01HX...",
"leadScore": 7,
"createdAt": "2025-03-10T08:00:00Z",
"updatedAt": "2025-03-12T11:30:00Z"
}
]
}
Creation
Create a Lead
POST /api/leads/
Authorization: Bearer <token>
Content-Type: application/json
Create a new lead with contact and qualification details.
Request body:
{
"firstName": "Dana",
"lastName": "Lee",
"email": "[email protected]",
"phone": "+15553334444",
"company": "Startup IO",
"status": "new",
"source": "referral",
"assignedTo": "usr_01HX...",
"leadScore": 5,
"notes": "Referred by Marcus at GrowthCo"
}
firstName or lastName, email
Response: 201 Created
Lead Details
Get a Lead
GET /api/leads/{id}/
Authorization: Bearer <token>
Retrieve full lead details including status and conversion data.
Response:
{
"id": "ld_01HX...",
"firstName": "Dana",
"lastName": "Lee",
"email": "[email protected]",
"phone": "+15553334444",
"company": "Startup IO",
"status": "new",
"source": "referral",
"assignedTo": "usr_01HX...",
"assignedToName": "Alex Johnson",
"leadScore": 5,
"emailOptOut": false,
"emailBounced": false,
"convertedAt": null,
"convertedContactId": null,
"notes": "Referred by Marcus at GrowthCo",
"createdAt": "2025-03-15T14:00:00Z",
"updatedAt": "2025-03-15T14:00:00Z"
}
Updates
Update a Lead
PATCH /api/leads/{id}/
Authorization: Bearer <token>
Content-Type: application/json
Update lead status, score, or other attributes.
Example — update status:
{
"status": "qualified",
"leadScore": 9
}
200 OK with the updated lead object.
Conversion
Convert a Lead
Convert a lead to a contact, optionally creating a linked account and opportunity.
POST /api/leads/{id}/convert/
Authorization: Bearer <token>
Content-Type: application/json
Convert a lead into CRM records including contact, account, and opportunity.
Request body:
{
"createAccount": true,
"accountName": "Startup IO",
"createOpportunity": true,
"opportunityName": "Startup IO — Enterprise",
"opportunityValue": 12000,
"opportunityStage": "qualification"
}
{
"lead": { "id": "ld_01HX...", "status": "converted", "convertedAt": "2025-03-20T10:00:00Z" },
"contact": { "id": "cnt_02HX...", "firstName": "Dana", "lastName": "Lee" },
"account": { "id": "acc_03HX...", "name": "Startup IO" },
"opportunity": { "id": "opp_04HX...", "name": "Startup IO — Enterprise", "value": 12000 }
}
Deletion
Delete a Lead
DELETE /api/leads/{id}/
Authorization: Bearer <token>
Permanently remove a lead.
Response: 204 No Content
Status
Lead Status Values
| Value | Label |
|---|
new | New |
contacted | Contacted |
qualified | Qualified |
nurturing | Nurturing |
unqualified | Unqualified |
converted | Converted |
lost | Lost |
