Help Scout User Management API Guide

Auth method: OAuth 2.0 (client credentials or authorization code flow)

Setup steps

1. Log in to Help Scout and navigate to Your Profile > My Apps.
2. Click 'Create My App' and provide an app name and redirect URL.
3. Note the generated App ID (client_id) and App Secret (client_secret).
4. For server-to-server (client credentials): POST to https://api.helpscout.net/v2/auth/token with grant_type=client_credentials, client_id, and client_secret.
5. Receive an access_token (Bearer token) valid for 48 hours; include it as Authorization: Bearer on all requests.

Required scopes

List Users

• Method: GET
• URL: https://api.helpscout.net/v2/users
• Watch out for: Returns only active (non-deleted) users. Deleted users are not included.

Request example

GET /v2/users?page=1 HTTP/1.1
Authorization: Bearer <token>

Response example

{
  "_embedded": {
    "users": [{"id":123,"firstName":"Jane","lastName":"Doe","email":"jane@example.com","role":"user"}]
  },
  "page": {"size":25,"totalElements":1,"totalPages":1,"number":1}
}

Get User by ID

• Method: GET
• URL: https://api.helpscout.net/v2/users/{userId}
• Watch out for: Returns 404 if the user has been deleted or does not belong to the authenticated account.

Request example

GET /v2/users/123 HTTP/1.1
Authorization: Bearer <token>

Response example

{
  "id": 123,
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "role": "user",
  "createdAt": "2023-01-15T10:00:00Z"
}

Get Authenticated User (Me)

• Method: GET
• URL: https://api.helpscout.net/v2/users/me
• Watch out for: For client_credentials tokens, this returns the app/bot user, not a human user.

Request example

GET /v2/users/me HTTP/1.1
Authorization: Bearer <token>

Response example

{
  "id": 456,
  "firstName": "App",
  "lastName": "Bot",
  "email": "app@example.com",
  "role": "admin"
}

List Users by Team

• Method: GET
• URL: https://api.helpscout.net/v2/teams/{teamId}/members
• Watch out for: Requires knowing the teamId; retrieve team IDs via GET /v2/teams first.

Request example

GET /v2/teams/10/members HTTP/1.1
Authorization: Bearer <token>

Response example

{
  "_embedded": {
    "members": [{"id":123,"firstName":"Jane","lastName":"Doe"}]
  }
}

• Rate limits: Help Scout enforces a rate limit of 400 requests per minute per access token. Exceeding the limit returns HTTP 429.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: Response headers X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset are returned. On 429, respect Retry-After header before retrying.
• Pagination method: offset
• Default page size: 25
• Max page size: 50
• Pagination pointer: page

• Webhooks available: Yes
• Webhook notes: Help Scout supports webhooks for various mailbox events. User-specific lifecycle events (e.g., user created/deleted) are not explicitly listed as webhook event types in the public documentation; webhooks primarily cover conversation and customer events.
• Alternative event strategy: Poll GET /v2/users periodically to detect user changes, or use SCIM provisioning for lifecycle events via an IdP.
• Webhook events: convo.created, convo.updated, convo.deleted, convo.assigned, convo.moved, convo.merged, convo.status, convo.tags, convo.customerEmailChanged, customer.created, satisfaction.ratings

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Pro

• Endpoint: https://api.helpscout.net/v2/scim

• Supported operations: GET /Users (list users), GET /Users/{id} (get user), POST /Users (create user), PUT /Users/{id} (replace user), PATCH /Users/{id} (update user), DELETE /Users/{id} (deactivate/delete user), GET /Groups (list groups/teams), POST /Groups (create group), PATCH /Groups/{id} (update group membership), DELETE /Groups/{id} (delete group)

Limitations:

• SCIM is only available on the Pro plan ($65/user/month billed annually).
• SSO must be configured before enabling SCIM provisioning.
• Supported IdPs include Okta, Microsoft Entra ID (Azure AD), and OneLogin; Google Workspace is not officially supported.
• Group provisioning maps to Help Scout Teams; not all team attributes may be writable via SCIM.
• SCIM token is a long-lived bearer token generated in Help Scout settings, separate from OAuth tokens.

Three integration patterns cover the majority of identity graph use cases against the Help Scout API.

For a full user sync, authenticate via client credentials, then paginate GET /v2/users starting at page=1. Capture totalPages from the response's page object and iterate all pages - max page size is 50, so large teams require many round trips. Map id, firstName, lastName, email, role, and createdAt to your directory schema; store updatedAt to detect changes on subsequent runs. GET /v2/users returns only active users; deactivated users are excluded from results.

For email-to-ID resolution to support identity graph lookups, there is no server-side email filter parameter on GET /v2/users. Filtering must be done client-side after fetching all pages - retrieve the full user list and match on the email field locally. For SCIM-based provisioning and deprovisioning via Okta or Entra ID, the base URL is https://api.helpscout.net/v2/scim with a long-lived bearer token generated separately from OAuth tokens in Help Scout Admin > Authentication. Unassigning a user in the IdP triggers DELETE /Users/{id}, which deactivates the user; their conversation history is retained and must be manually reassigned.

Sync all active users from Help Scout into an external directory

1. Authenticate via POST /v2/auth/token with client_credentials to obtain a Bearer token.
2. GET /v2/users?page=1 and capture totalPages from the page object in the response.
3. Iterate pages 1..totalPages, collecting all user objects.
4. Map id, firstName, lastName, email, role, createdAt fields to your directory schema.
5. Store updatedAt to detect changes on subsequent syncs.

Watch out for: Max page size is 50; with large teams, expect many round trips. Cache the token for up to 48 hours to avoid re-authenticating on every sync run.

Provision and deprovision users via SCIM from Okta

1. Ensure the Help Scout account is on the Pro plan and SSO is configured.
2. In Help Scout Admin > Authentication, enable SCIM and copy the SCIM bearer token.
3. In Okta, add the Help Scout SCIM app and enter base URL https://api.helpscout.net/v2/scim and the bearer token.
4. Enable 'Push Users' and optionally 'Push Groups' in Okta.
5. Assign users/groups in Okta; Okta will POST /Users to create accounts in Help Scout.
6. Unassigning a user in Okta triggers DELETE /Users/{id}, deactivating the user in Help Scout.

Watch out for: Deactivated users' conversations are not deleted; reassign open conversations before deprovisioning to avoid orphaned tickets.

Look up a user by email to retrieve their Help Scout user ID

1. Authenticate and obtain a Bearer token.
2. GET /v2/users?page=1 (page through all results if totalPages > 1).
3. Filter the returned users array client-side for the matching email field.
4. Use the returned id for subsequent API calls (e.g., filtering conversations by assignee).

Watch out for: There is no server-side email filter query parameter on GET /v2/users in the public API; filtering must be done client-side after fetching all pages.

The most common integration trap is assuming the REST API supports the full user lifecycle. It does not - there is no POST /users endpoint.

Teams that build provisioning pipelines against the REST API will hit a hard wall at user creation and must either fall back to UI-based invites or implement SCIM, which is gated behind the Pro plan and requires SSO to be configured first.

A second trap involves the identity graph assumption that deactivated users remain queryable. GET /v2/users and GET /v2/users/{userId} both exclude deactivated users - the latter returns HTTP 404 for any deactivated or deleted user ID.

If your identity graph needs to track offboarded users, persist their records externally before deactivation, as the API provides no tombstone or soft-delete state in its responses.

Webhooks do not emit user lifecycle events. There are no user.created or user.deleted webhook event types in the public documentation - webhooks cover conversation and customer events only. Detecting user changes requires polling GET /v2/users on a schedule and diffing against your stored state, or relying on SCIM callbacks from your IdP.