Sales / Deals API
The Sales API lets you manage deals (opportunities) in the pipeline programmatically. Create deals, update values, move them between stages, and mark them as won or lost.
Endpoints
| Method | Endpoint | Description |
|---|
GET | /v1/deals | List all deals |
GET | /v1/deals/:id | Get a single deal |
POST | /v1/deals | Create a new deal |
PATCH | /v1/deals/:id | Update a deal |
DELETE | /v1/deals/:id | Delete a deal |
POST | /v1/deals/:id/move | Move a deal to a different stage |
POST | /v1/deals/:id/close | Close a deal as won or lost |
GET | /v1/stages | List pipeline stages |
List Deals
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 (value, created_at, expected_close_date, -value for descending) |
stage_id | UUID | Filter by pipeline stage |
owner_id | UUID | Filter by assigned user |
team_id | UUID | Filter by team |
status | string | open, won, lost |
min_value | number | Minimum deal value |
max_value | number | Maximum deal value |
close_date_after | ISO date | Expected close date after |
close_date_before | ISO date | Expected close date before |
search | string | Search across deal name and contact |
Example Request
curl -X GET "https://api.play2sell.com/v1/deals?status=open&sort=-value&per_page=20" \
-H "Authorization: Bearer YOUR_TOKEN"
Example Response
{
"data": [
{
"id": "880e8400-e29b-41d4-a716-446655440000",
"name": "Tech Corp - Enterprise License",
"value": 75000.00,
"stage": {
"id": "990e8400-e29b-41d4-a716-446655440001",
"name": "Proposal",
"probability": 50
},
"status": "open",
"contact_name": "Maria Santos",
"contact_email": "maria@techcorp.com",
"company": "Tech Corp",
"owner_id": "660e8400-e29b-41d4-a716-446655440001",
"expected_close_date": "2026-04-15",
"priority": "high",
"lead_id": "550e8400-e29b-41d4-a716-446655440000",
"custom_fields": {
"contract_type": "annual",
"decision_maker": "CTO"
},
"tags": ["enterprise", "priority"],
"created_at": "2026-02-20T10:00:00Z",
"updated_at": "2026-03-14T16:45:00Z"
}
],
"meta": {
"total": 89,
"page": 1,
"per_page": 20,
"total_pages": 5
}
}
Create a Deal
Request Body
| Field | Type | Required | Description |
|---|
name | string | Yes | Deal name |
value | number | Yes | Deal value |
stage_id | UUID | No | Initial stage (defaults to first stage) |
contact_name | string | No | Primary contact name |
contact_email | string | No | Primary contact email |
company | string | No | Company name |
owner_id | UUID | No | Assigned sales rep |
expected_close_date | ISO date | No | Expected closing date |
priority | string | No | high, medium, low (default: medium) |
lead_id | UUID | No | Link to source lead |
custom_fields | object | No | Custom field values |
tags | array | No | List of tags |
Example
curl -X POST "https://api.play2sell.com/v1/deals" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "StartupXYZ - Pro Plan",
"value": 12000,
"contact_name": "Carlos Silva",
"contact_email": "carlos@startupxyz.com",
"company": "StartupXYZ",
"expected_close_date": "2026-05-01",
"priority": "medium"
}'
Update a Deal
Send only the fields to update.
curl -X PATCH "https://api.play2sell.com/v1/deals/880e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"value": 85000,
"priority": "high"
}'
Move a Deal
Move a deal to a different pipeline stage:
Request Body
| Field | Type | Required | Description |
|---|
stage_id | UUID | Yes | Target stage ID |
note | string | No | Optional note about the move |
curl -X POST "https://api.play2sell.com/v1/deals/880e8400-e29b-41d4-a716-446655440000/move" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"stage_id": "990e8400-e29b-41d4-a716-446655440002",
"note": "Client approved the proposal, moving to negotiation"
}'
Moving a deal via the API triggers the same gamification points and workflow automations as moving it in the UI.
Close a Deal
Request Body
| Field | Type | Required | Description |
|---|
result | string | Yes | won or lost |
final_value | number | No | Final deal value (for won deals) |
loss_reason | string | Conditional | Required when result is lost |
note | string | No | Closing note |
Close as Won
curl -X POST "https://api.play2sell.com/v1/deals/880e8400-e29b-41d4-a716-446655440000/close" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"result": "won",
"final_value": 82000,
"note": "Signed 12-month contract"
}'
Close as Lost
curl -X POST "https://api.play2sell.com/v1/deals/880e8400-e29b-41d4-a716-446655440000/close" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"result": "lost",
"loss_reason": "Lost to competitor",
"note": "Chose CompetitorX due to lower pricing"
}'
List Pipeline Stages
Returns all configured pipeline stages in order:
{
"data": [
{ "id": "...", "name": "Prospecting", "position": 1, "probability": 10 },
{ "id": "...", "name": "Qualification", "position": 2, "probability": 25 },
{ "id": "...", "name": "Proposal", "position": 3, "probability": 50 },
{ "id": "...", "name": "Negotiation", "position": 4, "probability": 75 },
{ "id": "...", "name": "Closed Won", "position": 5, "probability": 100 },
{ "id": "...", "name": "Closed Lost", "position": 6, "probability": 0 }
]
}
Delete a Deal
Returns 204 No Content on success.
Deleting a deal is permanent. The deal history, notes, and attachments are all removed. Consider closing as lost instead to preserve the data.
Next Steps
