Users

The Users API manages the people who have access to your Voisnap tenant — create users, assign roles, send invitations, and manage profiles.

Base path: /api/v1/users

---

User roles

Role	Description	Typical use
Admin	Full access to all tenant resources and settings	Account owner, lead developer
AgencyManager	Can manage all clients and agents within an agency account	Agency operations manager
AgencyTechnicalManager	Agency technical access: API keys, integrations, agent config	Agency developer/tech lead
AgencyAccountManager	Client-facing: can view analytics and manage client accounts	Agency account manager
TenantOwner	Full access to a single tenant	Business owner using the platform
TenantUser	Standard access: view and manage agents and conversations	Team member
ReadOnly	Read-only access to all resources	Stakeholder, auditor

---

User object

{
  "id": "usr_01HXABC123DEF",
  "email": "jane@acme.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "role": "TenantUser",
  "status": "active",
  "mfaEnabled": true,
  "lastLoginAt": "2025-06-16T09:15:00Z",
  "createdAt": "2025-01-20T10:00:00Z",
  "invitedBy": "usr_01HXADMIN...",
  "permissions": {
    "canManageApiKeys": false,
    "canViewBilling": false,
    "canDeleteConversations": false
  }
}

---

List users

GET /api/v1/users

Query parameters: role, status, search, page, pageSize

curl "https://api.voisnap.ai/api/v1/users?role=TenantUser&status=active" \
  -H "Authorization: Bearer vsnp_live_..."

users = client.users.list(role="TenantUser", status="active")
for user in users:
    print(f"{user.email} — {user.role}")

for await (const user of client.users.list({ role: 'TenantUser', status: 'active' })) {
  console.log(`${user.email} — ${user.role}`);
}

---

Get a user

GET /api/v1/users/{userId}

---

Invite a user

POST /api/v1/users/invite

Sends an invitation email to the specified address. The recipient clicks the link to set their password and activate their account.

curl -X POST https://api.voisnap.ai/api/v1/users/invite \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newteammate@acme.com",
    "firstName": "Alex",
    "lastName": "Jones",
    "role": "TenantUser",
    "message": "Welcome to the Acme Voisnap workspace!"
  }'

invitation = client.users.invite(
    email="newteammate@acme.com",
    first_name="Alex",
    last_name="Jones",
    role="TenantUser",
    message="Welcome to the Acme Voisnap workspace!"
)
print(f"Invitation sent: {invitation.id}, expires: {invitation.expires_at}")

const invitation = await client.users.invite({
  email: 'newteammate@acme.com',
  firstName: 'Alex',
  lastName: 'Jones',
  role: 'TenantUser',
});

Response:

{
  "invitationId": "inv_01HXABC...",
  "email": "newteammate@acme.com",
  "role": "TenantUser",
  "status": "pending",
  "expiresAt": "2025-06-23T10:00:00Z",
  "sentAt": "2025-06-16T10:00:00Z"
}

---

Update a user

PATCH /api/v1/users/{userId}

curl -X PATCH https://api.voisnap.ai/api/v1/users/usr_01HXABC123DEF \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "role": "Admin" }'

---

Deactivate a user

POST /api/v1/users/{userId}/deactivate

Deactivated users cannot log in. Their data is preserved. Requires Admin role.

curl -X POST https://api.voisnap.ai/api/v1/users/usr_01HXABC123DEF/deactivate \
  -H "Authorization: Bearer vsnp_live_..."

---

Reactivate a user

POST /api/v1/users/{userId}/reactivate

---

Get current user profile

GET /api/v1/users/me

Returns the profile of the authenticated user.

curl https://api.voisnap.ai/api/v1/users/me \
  -H "Authorization: Bearer vsnp_live_..."

---

Update current user profile

PATCH /api/v1/users/me

curl -X PATCH https://api.voisnap.ai/api/v1/users/me \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "timezone": "America/Los_Angeles",
    "notificationPreferences": {
      "weeklyDigest": true,
      "billingAlerts": true,
      "agentErrors": true
    }
  }'

---

List pending invitations

GET /api/v1/users/invitations

Lists all pending invitations that haven't been accepted or expired.

curl https://api.voisnap.ai/api/v1/users/invitations \
  -H "Authorization: Bearer vsnp_live_..."

---

Revoke an invitation

DELETE /api/v1/users/invitations/{invitationId}