Users API

The Users API manages organization users, including listing, role management, invitations, and user profile operations.

User Object

{
  id: string;                    // UUID
  organization_id: string;       // UUID of the organization
  email: string;                 // User email address
  name?: string;                 // Display name
  role: 'admin' | 'agent' | 'customer';  // User role
  avatar_url?: string;           // Profile avatar URL
  expertise?: string[];          // Expertise tags for routing
  preferences?: object;          // User preferences
  created_at: string;            // ISO timestamp
  updated_at: string;            // ISO timestamp
}

User Roles

List Users

Retrieve all users in the organization. Admin only.

Procedure: users.list

Authentication: Required (Admin)

Input:

{
  role?: 'admin' | 'agent' | 'customer';  // Filter by role
  search?: string;                        // Search by name or email
  limit?: number;                         // 1-100, default: 50
  offset?: number;                        // Pagination offset, default: 0
}

Example:

curl -X GET "https://your-domain.com/api/trpc/users.list?input=%7B%22role%22:%22agent%22,%22limit%22:20%7D" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "users": [
          {
            "id": "uuid",
            "name": "John Smith",
            "email": "john@example.com",
            "role": "agent",
            "avatar_url": "https://example.com/avatar.jpg",
            "expertise": ["billing", "technical"],
            "created_at": "2024-01-01T00:00:00.000Z",
            "updated_at": "2024-01-15T10:00:00.000Z"
          },
          {
            "id": "uuid-2",
            "name": "Jane Doe",
            "email": "jane@example.com",
            "role": "agent",
            "avatar_url": null,
            "expertise": ["sales"],
            "created_at": "2024-01-05T00:00:00.000Z",
            "updated_at": "2024-01-15T10:00:00.000Z"
          }
        ],
        "total": 15,
        "hasMore": false
      }
    }
  }
}

Get User by ID

Retrieve a single user by their ID.

Procedure: users.getById

Authentication: Required

Input:

{
  id: string;  // User UUID
}

Example:

curl -X GET "https://your-domain.com/api/trpc/users.getById?input=%7B%22id%22:%22user-uuid%22%7D" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "name": "John Smith",
        "email": "john@example.com",
        "role": "agent",
        "avatar_url": "https://example.com/avatar.jpg",
        "expertise": ["billing", "technical"],
        "preferences": {
          "theme": "dark",
          "notifications": true
        },
        "created_at": "2024-01-01T00:00:00.000Z",
        "updated_at": "2024-01-15T10:00:00.000Z"
      }
    }
  }
}

Update User Role

Change a user's role. Admin only.

Procedure: users.updateRole

Authentication: Required (Admin)

Input:

{
  userId: string;                        // Target user UUID
  role: 'admin' | 'agent' | 'customer';  // New role
}

Example:

curl -X POST "https://your-domain.com/api/trpc/users.updateRole" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "userId": "user-uuid",
      "role": "admin"
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "name": "John Smith",
        "email": "john@example.com",
        "role": "admin",
        "updated_at": "2024-01-15T11:00:00.000Z"
      }
    }
  }
}

Notes:

• Admins cannot change their own role
• Role change is logged in the events table

Update User Expertise

Update a user's expertise tags for skill-based routing.

Procedure: users.updateExpertise

Authentication: Required

Input:

{
  userId: string;        // Target user UUID
  expertise: string[];   // Array of expertise tags
}

Permissions:

• Users can update their own expertise
• Admins can update any user's expertise

Example:

curl -X POST "https://your-domain.com/api/trpc/users.updateExpertise" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "userId": "user-uuid",
      "expertise": ["billing", "technical", "enterprise"]
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "name": "John Smith",
        "expertise": ["billing", "technical", "enterprise"],
        "updated_at": "2024-01-15T11:00:00.000Z"
      }
    }
  }
}

Invite User

Send an invitation email to add a new user. Admin only.

Procedure: users.invite

Authentication: Required (Admin)

Input:

{
  email: string;                         // Email address
  role?: 'admin' | 'agent' | 'customer'; // Default: 'agent'
  name?: string;                         // Optional display name
}

Example:

curl -X POST "https://your-domain.com/api/trpc/users.invite" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "email": "newuser@example.com",
      "role": "agent",
      "name": "New User"
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true,
        "invitation": {
          "id": "invitation-uuid",
          "email": "newuser@example.com",
          "role": "agent",
          "expires_at": "2024-01-22T10:30:00.000Z"
        }
      }
    }
  }
}

Notes:

• Invitation expires after 7 days
• User receives an email with a signup link
• If user already exists, returns CONFLICT error

Deactivate User

Deactivate a user account (soft delete). Admin only.

Procedure: users.deactivate

Authentication: Required (Admin)

Input:

{
  userId: string;  // User UUID to deactivate
}

Example:

curl -X POST "https://your-domain.com/api/trpc/users.deactivate" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"userId":"user-uuid"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true
      }
    }
  }
}

Notes:

• Admins cannot deactivate themselves
• User is downgraded to customer role
• Deactivation is logged in the events table

Get Agents

Get a list of agents for assignment dropdowns. Returns admins and agents only.

Procedure: users.getAgents

Authentication: Required

Input: None

Example:

curl -X GET "https://your-domain.com/api/trpc/users.getAgents" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "id": "uuid",
          "name": "John Smith",
          "email": "john@example.com",
          "avatar_url": "https://example.com/avatar.jpg",
          "expertise": ["billing", "technical"]
        },
        {
          "id": "uuid-2",
          "name": "Jane Doe",
          "email": "jane@example.com",
          "avatar_url": null,
          "expertise": ["sales"]
        }
      ]
    }
  }
}

Notes:

• Used for ticket assignment UI
• Sorted alphabetically by name
• Includes expertise for skill-based assignment

Use Cases

Team Management Page

// List all team members
const { users, total } = await trpc.users.list.query({
  limit: 50,
})

// Filter by role
const agents = await trpc.users.list.query({
  role: 'agent',
})

// Search users
const results = await trpc.users.list.query({
  search: 'john',
})

Invite Team Members

// Send invitation
await trpc.users.invite.mutate({
  email: 'newagent@company.com',
  role: 'agent',
  name: 'New Agent',
})

Skill-Based Routing

// Get agents with specific expertise
const agents = await trpc.users.getAgents.query()
const billingAgents = agents.filter(a =>
  a.expertise?.includes('billing')
)

Error Codes