Skip to content

Users

Users are agent accounts that can access the TopTickets system, handle tickets, and respond to customers.

Endpoints

Method Endpoint Description Scope Required
GET /v1/users List users users:read
GET /v1/users/{id} Get user users:read
POST /v1/users Create user users:write
PATCH /v1/users/{id} Update user users:write
DELETE /v1/users/{id} Delete user users:delete
POST /v1/users/me/avatar Upload avatar users:write
DELETE /v1/users/me/avatar Delete avatar users:write

The User Object

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "agent@company.com",
  "full_name": "Alice Johnson",
  "role": "agent",
  "is_active": true,
  "avatar_url": "https://storage.supabase.co/avatars/...",
  "employee_type": "permanent",
  "region": "amer",
  "timezone": "America/New_York",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-10T15:30:00Z"
}

Attributes

Field Type Description
id UUID Unique user identifier
email string Email address (unique)
full_name string Display name
role enum admin, read_only_admin, agent, read_only_agent
is_active boolean Whether user can access the system
avatar_url string Profile picture URL (nullable)
employee_type enum permanent, contractor, external, bot
region enum amer, apac, emea, latam, asean
timezone string User's timezone
created_at datetime Creation timestamp
updated_at datetime Last modification timestamp

List Users

Retrieve a paginated list of users in your organization.

GET /v1/users

Query Parameters

Parameter Type Default Description
skip integer 0 Number of records to skip
limit integer 50 Maximum records to return (max: 100)

Examples

curl -X GET "https://api.toptickets.app/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.toptickets.app/v1/users",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

Response

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "agent@company.com",
    "full_name": "Alice Johnson",
    "role": "agent",
    "is_active": true
  },
  {
    "id": "234f5678-e90c-12d3-b456-526714174111",
    "email": "admin@company.com",
    "full_name": "Bob Smith",
    "role": "admin",
    "is_active": true
  }
]

Get User

Retrieve a single user.

GET /v1/users/{user_id}

Path Parameters

Parameter Type Description
user_id UUID The user ID

Examples

curl -X GET "https://api.toptickets.app/v1/users/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

USER_ID = "123e4567-e89b-12d3-a456-426614174000"

response = requests.get(
    f"https://api.toptickets.app/v1/users/{USER_ID}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

Response

Returns the full user object.

Create User

Create a new user account.

POST /v1/users

Request Body

Field Type Required Description
email string Yes Email address (must be unique)
full_name string Yes Display name
role enum No User role (default: agent)
is_active boolean No Active status (default: true)
employee_type enum No Employment type
region enum No Business region
timezone string No Timezone

Examples

curl -X POST "https://api.toptickets.app/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newagent@company.com",
    "full_name": "New Agent",
    "role": "agent"
  }'

import requests

response = requests.post(
    "https://api.toptickets.app/v1/users",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "email": "newagent@company.com",
        "full_name": "New Agent",
        "role": "agent"
    }
)

Response (201 Created)

Returns the created user object.

Update User

Update an existing user.

PATCH /v1/users/{user_id}

Path Parameters

Parameter Type Description
user_id UUID The user ID

Request Body

Field Type Description
full_name string Updated display name
role enum Updated role
is_active boolean Updated active status
employee_type enum Updated employment type
region enum Updated region
timezone string Updated timezone

Examples

curl -X PATCH "https://api.toptickets.app/v1/users/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "region": "emea"
  }'

import requests

USER_ID = "123e4567-e89b-12d3-a456-426614174000"

response = requests.patch(
    f"https://api.toptickets.app/v1/users/{USER_ID}",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "role": "admin",
        "region": "emea"
    }
)

Response

Returns the updated user object.

Self-Deactivation

You cannot deactivate your own user account.

Delete User

Delete a user account.

DELETE /v1/users/{user_id}

Path Parameters

Parameter Type Description
user_id UUID The user ID

Examples

curl -X DELETE "https://api.toptickets.app/v1/users/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

USER_ID = "123e4567-e89b-12d3-a456-426614174000"

response = requests.delete(
    f"https://api.toptickets.app/v1/users/{USER_ID}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

if response.status_code == 204:
    print("User deleted")

Response

Returns 204 No Content on success.

Upload Avatar

Upload a profile picture for the current user.

POST /v1/users/me/avatar

Request

Send the image as multipart/form-data. Supported formats: PNG, JPEG, GIF, WebP. Maximum size: 2MB. Images are automatically converted to WebP.

Examples

curl -X POST "https://api.toptickets.app/v1/users/me/avatar" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/avatar.png"

import requests

with open("/path/to/avatar.png", "rb") as f:
    response = requests.post(
        "https://api.toptickets.app/v1/users/me/avatar",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        files={"file": ("avatar.png", f, "image/png")}
    )

Response

Returns the updated user object with the new avatar_url.

Delete Avatar

Remove the current user's profile picture.

DELETE /v1/users/me/avatar

Examples

curl -X DELETE "https://api.toptickets.app/v1/users/me/avatar" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.delete(
    "https://api.toptickets.app/v1/users/me/avatar",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

Response

Returns the updated user object with avatar_url set to null.

User Roles

Role Description
admin Full access to all features and settings
read_only_admin Can view all data but cannot make changes
agent Can manage tickets, customers, and comments
read_only_agent Can view tickets and customers, cannot modify

See User Roles for detailed permissions.

Employee Types

Type Description
permanent Full-time employee
contractor Contract worker
external External partner
bot Automated system account