Leads API
The Leads API allows you to manage leads programmatically. Create leads from external forms, sync with marketing tools, or build custom lead management workflows.
Endpoints
| Method | Endpoint | Description |
|---|
GET | /v1/leads | List all leads |
GET | /v1/leads/:id | Get a single lead |
POST | /v1/leads | Create a new lead |
PATCH | /v1/leads/:id | Update a lead |
DELETE | /v1/leads/:id | Delete a lead |
POST | /v1/leads/:id/convert | Convert a lead to a deal |
List Leads
Query Parameters
| Parameter | Type | Description |
|---|
page | integer | Page number (default: 1) |
per_page | integer | Results per page (default: 25, max: 100) |
sort | string | Sort field (prefix with - for descending) |
status | string | Filter by status: new, contacted, qualified, unqualified, converted |
source | string | Filter by lead source |
owner_id | UUID | Filter by assigned user |
team_id | UUID | Filter by team |
created_after | ISO date | Leads created after this date |
created_before | ISO date | Leads created before this date |
search | string | Search across name, email, and company |
Example Request
curl -X GET "https://api.play2sell.com/v1/leads?status=qualified&sort=-created_at&per_page=10" \
-H "Authorization: Bearer YOUR_TOKEN"
Example Response
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Maria Santos",
"email": "maria@example.com",
"phone": "+5511999999999",
"company": "Tech Corp",
"position": "CTO",
"source": "website",
"status": "qualified",
"owner_id": "660e8400-e29b-41d4-a716-446655440001",
"team_id": "770e8400-e29b-41d4-a716-446655440002",
"custom_fields": {
"company_size": "50-200",
"industry": "Technology"
},
"tags": ["enterprise", "inbound"],
"created_at": "2026-03-10T14:30:00Z",
"updated_at": "2026-03-14T09:15:00Z"
}
],
"meta": {
"total": 45,
"page": 1,
"per_page": 10,
"total_pages": 5
}
}
Get a Lead
Example
curl -X GET "https://api.play2sell.com/v1/leads/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer YOUR_TOKEN"
Create a Lead
Request Body
| Field | Type | Required | Description |
|---|
name | string | Yes | Lead’s full name |
email | string | Yes | Email address |
phone | string | No | Phone number |
company | string | No | Company name |
position | string | No | Job title |
source | string | No | How the lead was acquired |
owner_id | UUID | No | Assigned sales rep (null for unassigned) |
custom_fields | object | No | Key-value pairs for custom field values |
tags | array | No | List of tag strings |
Example
curl -X POST "https://api.play2sell.com/v1/leads" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Carlos Silva",
"email": "carlos@example.com",
"phone": "+5511988888888",
"company": "StartupXYZ",
"source": "website",
"custom_fields": {
"company_size": "1-10",
"industry": "SaaS"
},
"tags": ["startup", "inbound"]
}'
Response
Returns the created lead with a 201 Created status.
If a lead with the same email already exists, the API returns a 409 Conflict error. Use the PATCH endpoint to update existing leads.
Update a Lead
Send only the fields you want to update. Fields not included in the request body remain unchanged.
Example
curl -X PATCH "https://api.play2sell.com/v1/leads/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"status": "qualified",
"custom_fields": {
"company_size": "50-200"
}
}'
Delete a Lead
Returns 204 No Content on success.
Deleting a lead is permanent and cannot be undone. Consider changing the status to unqualified instead if you want to keep the data.
Convert a Lead
Convert a qualified lead into a deal in the pipeline:
POST /v1/leads/:id/convert
Request Body
| Field | Type | Required | Description |
|---|
deal_name | string | No | Name for the new deal (defaults to lead name) |
deal_value | number | No | Initial deal value |
stage_id | UUID | No | Initial pipeline stage (defaults to first stage) |
expected_close_date | ISO date | No | Expected closing date |
Example
curl -X POST "https://api.play2sell.com/v1/leads/550e8400-e29b-41d4-a716-446655440000/convert" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"deal_value": 25000,
"expected_close_date": "2026-06-30"
}'
converted) and the newly created deal.
Next Steps
