Users API

Users are the team members in your workspace. Manage invitations, roles, permissions, and user settings through the API.

The User Object

{
  "id": "usr_cuid123456",
  "email": "john@yourcompany.com",
  "name": "John Smith",
  "avatar_url": "https://...",
  "role": "admin",
  "title": "Senior Developer",
  "department": "Engineering",
  "phone": "+1 (555) 123-4567",
  "timezone": "America/New_York",
  "status": "active",
  "capacity": {
    "hours_per_week": 40,
    "billable_target": 75
  },
  "rates": {
    "cost_rate": 75.00,
    "bill_rate": 150.00
  },
  "permissions": {
    "can_see_rates": true,
    "can_approve_time": true,
    "can_manage_invoices": false
  },
  "last_active_at": "2026-01-25T14:30:00Z",
  "created_at": "2025-06-15T10:00:00Z"
}

User Fields

Field	Type	Description
`id`	string	Unique identifier (prefix: `usr_`)
`email`	string	Email address (unique)
`name`	string	Display name
`avatar_url`	string	Profile picture URL
`role`	enum	User role (see below)
`title`	string	Job title
`department`	string	Department/team
`phone`	string	Phone number
`timezone`	string	User’s timezone
`status`	enum	`active`, `invited`, `deactivated`
`capacity`	object	Work capacity settings
`rates`	object	Cost and billing rates
`permissions`	object	Granular permissions
`last_active_at`	datetime	Last activity timestamp
`created_at`	datetime	When user was added

User Roles

Role	Description
`owner`	Full access, billing management, can delete workspace
`admin`	Full access except billing and workspace deletion
`manager`	Can manage team, approve time, view reports
`member`	Standard user, logs time, works on projects
`viewer`	Read-only access (free seat)
`contractor`	External contractor with limited access

List Users

GET/v1/usersList all users

Returns all users in your workspace.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	50	Results per page (max: 100)
`status`	string	`active`	Filter: `active`, `invited`, `deactivated`, `all`
`role`	string		Filter by role
`department`	string		Filter by department
`search`	string		Search by name or email

Request

curl "https://api.govantage.co/v1/users?status=active" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Response

{
  "data": [
    {
      "id": "usr_cuid123456",
      "email": "john@yourcompany.com",
      "name": "John Smith",
      "role": "admin",
      "title": "Senior Developer",
      "status": "active",
      "last_active_at": "2026-01-25T14:30:00Z"
    },
    {
      "id": "usr_cuid789012",
      "email": "jane@yourcompany.com",
      "name": "Jane Doe",
      "role": "member",
      "title": "Designer",
      "status": "active",
      "last_active_at": "2026-01-25T12:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 12
  }
}

Get a User

GET/v1/users/:idRetrieve a user by ID

Query Parameters

Parameter	Type	Description
`include`	string	Comma-separated: `time_entries`, `projects`, `stats`

Request

curl "https://api.govantage.co/v1/users/usr_cuid123456?include=stats" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Response

{
  "data": {
    "id": "usr_cuid123456",
    "email": "john@yourcompany.com",
    "name": "John Smith",
    "role": "admin",
    "title": "Senior Developer",
    "department": "Engineering",
    "timezone": "America/New_York",
    "status": "active",
    "capacity": {
      "hours_per_week": 40,
      "billable_target": 75
    },
    "rates": {
      "cost_rate": 75.00,
      "bill_rate": 150.00
    },
    "stats": {
      "hours_this_week": 32.5,
      "hours_this_month": 142.0,
      "billable_percent": 78,
      "active_projects": 5,
      "open_tickets": 12
    }
  }
}

Get Current User

GET/v1/users/meGet the authenticated user

Returns the user associated with the current API key.

curl "https://api.govantage.co/v1/users/me" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Invite a User

POST/v1/users/inviteInvite a new team member

Sends an invitation email to join your workspace.

Request Body

Field	Type	Required	Description
`email`	string	Yes	Email address
`name`	string	Yes	Display name
`role`	string	Yes	User role
`title`	string	No	Job title
`department`	string	No	Department
`hours_per_week`	integer	No	Weekly capacity (default: 40)
`billable_target`	integer	No	Billable % target (default: 75)
`cost_rate`	decimal	No	Hourly cost rate
`bill_rate`	decimal	No	Default billing rate

Request

curl -X POST "https://api.govantage.co/v1/users/invite" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@yourcompany.com",
    "name": "New User",
    "role": "member",
    "title": "Developer",
    "department": "Engineering",
    "hours_per_week": 40,
    "billable_target": 75
  }'

Response

{
  "data": {
    "id": "usr_cuid345678",
    "email": "newuser@yourcompany.com",
    "name": "New User",
    "role": "member",
    "status": "invited",
    "invitation_sent_at": "2026-01-25T10:30:00Z",
    "invitation_expires_at": "2026-02-01T10:30:00Z"
  }
}

Update a User

PUT/v1/users/:idUpdate a user

Request

curl -X PUT "https://api.govantage.co/v1/users/usr_cuid123456" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Lead Developer",
    "department": "Engineering",
    "capacity": {
      "hours_per_week": 40,
      "billable_target": 80
    },
    "rates": {
      "cost_rate": 85.00,
      "bill_rate": 175.00
    }
  }'

Only admins and owners can update user roles and permissions. Users can update their own profile (name, timezone, etc.).

Deactivate a User

POST/v1/users/:id/deactivateDeactivate a user

Deactivated users cannot log in but their data is preserved for historical reporting.

curl -X POST "https://api.govantage.co/v1/users/usr_cuid123456/deactivate" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Response

{
  "data": {
    "id": "usr_cuid123456",
    "status": "deactivated",
    "deactivated_at": "2026-01-25T10:30:00Z"
  }
}

Reactivate a User

POST/v1/users/:id/reactivateReactivate a user

curl -X POST "https://api.govantage.co/v1/users/usr_cuid123456/reactivate" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Resend Invitation

POST/v1/users/:id/resend-invitationResend invitation email

For users with status: invited who haven’t accepted yet.

curl -X POST "https://api.govantage.co/v1/users/usr_cuid123456/resend-invitation" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Update Permissions

PUT/v1/users/:id/permissionsUpdate user permissions

Available Permissions

Permission	Description
`can_see_rates`	View billing rates and profitability
`can_see_costs`	View cost rates and margins
`can_approve_time`	Approve team time entries
`can_manage_invoices`	Create and send invoices
`can_manage_clients`	Create and edit clients
`can_manage_projects`	Create and edit projects
`can_manage_team`	Invite and manage users
`can_view_reports`	Access reporting
`can_export_data`	Export data to CSV

Request

curl -X PUT "https://api.govantage.co/v1/users/usr_cuid123456/permissions" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "can_see_rates": true,
    "can_approve_time": true,
    "can_manage_invoices": false,
    "can_view_reports": true
  }'

User Time Summary

GET/v1/users/:id/time-summaryGet time summary for a user

curl "https://api.govantage.co/v1/users/usr_cuid123456/time-summary?period=this_month" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Response

{
  "data": {
    "period": {
      "start": "2026-01-01",
      "end": "2026-01-31"
    },
    "hours": {
      "total": 142.0,
      "billable": 110.5,
      "non_billable": 31.5
    },
    "utilization": {
      "target": 75,
      "actual": 78,
      "status": "on_track"
    },
    "by_project": [
      { "project_id": "prj_xxxxx", "project_name": "Website Redesign", "hours": 45.5 },
      { "project_id": "prj_yyyyy", "project_name": "Mobile App", "hours": 65.0 }
    ]
  }
}

Bulk Operations

Bulk Update Department

PUT/v1/users/bulkUpdate multiple users

curl -X PUT "https://api.govantage.co/v1/users/bulk" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["usr_xxxxx", "usr_yyyyy", "usr_zzzzz"],
    "updates": {
      "department": "Product Team"
    }
  }'

Webhooks

Subscribe to user events:

Event	Description
`user.created`	New user accepted invitation
`user.updated`	User details changed
`user.deactivated`	User deactivated
`user.reactivated`	User reactivated
`user.role_changed`	User role changed

Next Steps

Authentication - API keys and permissions
Time Entries API - Track user time
Projects API - Assign users to projects