Users API
The Users API lets you manage user accounts, roles, and team assignments programmatically. Useful for syncing with your HR system or building admin tools.
Endpoints
| Method | Endpoint | Description |
|---|
GET | /v1/users | List all users |
GET | /v1/users/:id | Get a single user |
POST | /v1/users | Create (invite) a new user |
PATCH | /v1/users/:id | Update a user |
DELETE | /v1/users/:id | Deactivate a user |
GET | /v1/users/:id/stats | Get user performance stats |
GET | /v1/teams | List all teams |
List Users
Query Parameters
| Parameter | Type | Description |
|---|
page | integer | Page number |
per_page | integer | Results per page (max 100) |
role | string | Filter by role: admin, manager, sales_rep |
team_id | UUID | Filter by team |
status | string | active, invited, deactivated |
search | string | Search by name or email |
Example
curl -X GET "https://api.play2sell.com/v1/users?role=sales_rep&status=active" \
-H "Authorization: Bearer YOUR_TOKEN"
Response
{
"data": [
{
"id": "660e8400-e29b-41d4-a716-446655440001",
"name": "Ana Costa",
"email": "ana@company.com",
"phone": "+5511977777777",
"avatar_url": "https://api.play2sell.com/avatars/ana.jpg",
"role": "sales_rep",
"team": {
"id": "770e8400-e29b-41d4-a716-446655440002",
"name": "Enterprise Sales"
},
"status": "active",
"ranking_tier": "gold",
"total_points": 2350,
"created_at": "2025-06-15T08:00:00Z",
"last_active_at": "2026-03-15T09:30:00Z"
}
],
"meta": {
"total": 32,
"page": 1,
"per_page": 25,
"total_pages": 2
}
}
Get a User
Returns the full user profile including all fields and team information.
Create (Invite) a User
Creating a user sends an invitation email. The user must accept the invitation to set their password and activate their account.
Request Body
| Field | Type | Required | Description |
|---|
name | string | Yes | User’s full name |
email | string | Yes | Email address (invitation sent here) |
role | string | Yes | admin, manager, or sales_rep |
team_id | UUID | No | Assign to a team |
phone | string | No | Phone number |
Example
curl -X POST "https://api.play2sell.com/v1/users" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Pedro Oliveira",
"email": "pedro@company.com",
"role": "sales_rep",
"team_id": "770e8400-e29b-41d4-a716-446655440002"
}'
Creating a user via the API counts toward your plan’s user limit, just like inviting from the UI.
Update a User
Updatable Fields
| Field | Type | Description |
|---|
name | string | User’s name |
phone | string | Phone number |
role | string | Change the user’s role |
team_id | UUID | Move to a different team |
curl -X PATCH "https://api.play2sell.com/v1/users/660e8400-e29b-41d4-a716-446655440001" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"role": "manager",
"team_id": "770e8400-e29b-41d4-a716-446655440003"
}'
Changing a user’s role takes effect immediately. The user’s permissions update on their next page load or API request.
Deactivate a User
This deactivates the user rather than permanently deleting them. Deactivated users cannot log in, but their data (deals, leads, notes) is preserved.
Returns 204 No Content on success.
To permanently delete a user and their data, add the ?permanent=true query parameter. This action is irreversible.
Get User Stats
Query Parameters
| Parameter | Type | Description |
|---|
period | string | today, week, month, quarter, year, all_time |
Example
curl -X GET "https://api.play2sell.com/v1/users/660e8400-e29b-41d4-a716-446655440001/stats?period=month" \
-H "Authorization: Bearer YOUR_TOKEN"
Response
{
"data": {
"user_id": "660e8400-e29b-41d4-a716-446655440001",
"period": "month",
"points": 450,
"ranking_position": 3,
"deals_created": 8,
"deals_won": 3,
"deals_lost": 1,
"revenue_closed": 47000,
"leads_created": 15,
"leads_qualified": 6,
"conversion_rate": 0.75,
"average_deal_size": 15667,
"average_sales_cycle_days": 22,
"badges_earned": 1,
"activities_logged": 42
}
}
List Teams
Returns all teams in the organization:
{
"data": [
{
"id": "770e8400-e29b-41d4-a716-446655440002",
"name": "Enterprise Sales",
"leader_id": "660e8400-e29b-41d4-a716-446655440005",
"member_count": 8,
"parent_team_id": null
}
]
}
Next Steps
