API Overview
The SalesOS API is a RESTful API that lets you programmatically interact with your SalesOS workspace. Use it to create integrations, sync data with external systems, or build custom applications on top of SalesOS.
Base URL
All API requests are made to:
https://api.play2sell.com/v1
For staging and development environments, use the corresponding base URLs. Contact your administrator for environment-specific URLs.
Authentication
All API requests require a valid JWT bearer token. Include it in the Authorization header:
curl -X GET https://api.play2sell.com/v1/leads \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json"
- All request bodies must be JSON with
Content-Type: application/json
- Query parameters are used for filtering, sorting, and pagination
- URL paths use lowercase and hyphens (e.g.,
/custom-fields)
All responses return JSON. Successful responses follow this structure:
{
"data": { ... },
"meta": {
"request_id": "req_abc123",
"timestamp": "2026-03-15T10:30:00Z"
}
}
{
"data": [ ... ],
"meta": {
"total": 150,
"page": 1,
"per_page": 25,
"total_pages": 6,
"request_id": "req_abc123",
"timestamp": "2026-03-15T10:30:00Z"
}
}
Error Responses
Errors return an appropriate HTTP status code and a JSON body:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "The 'email' field is required.",
"details": [
{
"field": "email",
"message": "This field is required"
}
]
},
"meta": {
"request_id": "req_abc123",
"timestamp": "2026-03-15T10:30:00Z"
}
}
HTTP Status Codes
| Status Code | Meaning |
|---|
200 OK | Request succeeded |
201 Created | Resource created successfully |
204 No Content | Request succeeded with no response body (e.g., DELETE) |
400 Bad Request | Invalid request body or parameters |
401 Unauthorized | Missing or invalid authentication token |
403 Forbidden | Authenticated but lacking permission for this action |
404 Not Found | Resource does not exist |
409 Conflict | Resource conflict (e.g., duplicate email) |
422 Unprocessable Entity | Validation error in the request body |
429 Too Many Requests | Rate limit exceeded |
500 Internal Server Error | Server-side error |
Rate Limits
API requests are rate-limited based on your plan:
| Plan | Rate Limit |
|---|
| Starter | 100 requests/minute |
| Professional | 500 requests/minute |
| Enterprise | 2,000 requests/minute |
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 498
X-RateLimit-Reset: 1710500460
429 status code with a Retry-After header indicating when you can make requests again.
List endpoints support pagination via query parameters:
| Parameter | Default | Description |
|---|
page | 1 | Page number (starts at 1) |
per_page | 25 | Items per page (max 100) |
GET /v1/leads?page=2&per_page=50
Filtering
Most list endpoints support filtering via query parameters:
GET /v1/leads?status=qualified&source=website&created_after=2026-01-01
| Parameter | Type | Description |
|---|
created_after | ISO date | Records created after this date |
created_before | ISO date | Records created before this date |
updated_after | ISO date | Records updated after this date |
owner_id | UUID | Filter by assigned user |
team_id | UUID | Filter by team |
Sorting
Use the sort parameter to order results:
GET /v1/deals?sort=-value # Descending by value
GET /v1/leads?sort=created_at # Ascending by creation date
- for descending order.
Versioning
The API is versioned via the URL path (/v1/). Breaking changes will result in a new version. Non-breaking additions (new fields, new endpoints) may be added to the current version.
Always specify the full versioned URL in your integrations. This ensures your code continues to work even when new API versions are released.
- cURL — Examples throughout this documentation use cURL
- Postman — Import our Postman collection for quick testing
- JavaScript/TypeScript — Use any HTTP client (fetch, axios)
- Python — Use
requests or httpx
Next Steps
