Skip to main content
All requests use a single endpoint: POST https://api.helpgenie.ai/v1 with resource: "profiles".

Access control

Admin endpoints require a role starting with internal_ (e.g. internal_admin). Non-admin users attempting admin-only actions receive a 403 Forbidden response.

role values

Profile mutations (create, update, delete) are automatically logged to the activities table as user_action events. Update actions include the list of changed fields in the activity metadata.

List all profiles (admin)

Retrieves all profiles with complete joined data including subscriptions, call purchases, and phone subscriptions.
string
required
Must be "profiles"
string
required
Must be "all"
object

Response

boolean
object

List basic profiles (admin)

Retrieves a paginated list of profiles with basic fields only, optimized for lists and dropdowns.
string
required
Must be "profiles"
string
required
Must be "list"
object

Response

boolean
object

Get a profile

Retrieves a single profile with complete details including subscriptions and team data. Users can only access their own profile; admins can access any profile.
string
required
Must be "profiles"
string
required
Must be "get"
string
required
The profile ID (user UUID).

Response

boolean
object

Create a profile (admin)

Creates a new user profile. There are two ways to call it:
  • Attach to an existing account — send id set to the UUID of an existing sign-in account.
  • Create the account too — send email with password, or email with send_welcome_email: true (no id needed). The sign-in account is created first with its email already confirmed, and its UUID becomes the profile id. Without a password, the account gets a random one that the user replaces through the set-password link in the welcome email. Fields you leave out keep the defaults the new account was given; they are not reset to empty. If saving the profile fails, the new sign-in account is removed again.
No email is sent to the user unless send_welcome_email is true, so accounts can be set up quietly. Any field not listed below is ignored.
string
required
Must be "profiles"
string
required
Must be "create"
object
required

Response (status 201)

boolean
object
string[]
Present only when a field was ignored, e.g. an unsupported billing_currency.

Update a profile

Updates an existing profile. Users can only update their own profile; admins can update any profile. This is a partial update — only include the fields you want to change.
string
required
Must be "profiles"
string
required
Must be "update"
string
required
The profile ID (user UUID).
object
required
Any key not listed below is rejected with a validation error. country, country_name and billing_currency are normalized the same way as on create.
Auth-context keys such as adminMode and impersonatedUserId are also rejected. Because admin API keys add adminMode to data automatically, update currently fails when called with an admin API key.

Response

boolean
object
string[]
Present only when a field was ignored, e.g. an unsupported billing_currency.

Delete a profile

Permanently deletes a profile. Users can only delete their own profile; admins can delete any profile.
string
required
Must be "profiles"
string
required
Must be "delete"
string
required
The profile ID (user UUID).

Response

boolean
object
This permanently deletes the profile record, the user’s sign-in account, and cancels any active subscriptions.
Before the profile is deleted, the mailbox of every genie the user owns is permanently removed. The profile is kept in place, and the request returns an INTERNAL_ERROR, when:
  • one or more mailboxes can’t be removed — the error names the affected genies. Try again.
  • the account has too many genies to clear in one call — the error reports how many mailboxes were removed. Call delete again to continue; each call picks up where the last one stopped.

Check timezone

Checks the authenticated user’s profile for a timezone value. If the timezone is not set, auto-detects it from the server and saves it to the profile. No-op if timezone is already set.
string
required
Must be "profiles"
string
required
Must be "check-timezone"

Response

boolean
object

Get inbox filters

Returns the filters the authenticated user last used on the Conversations inbox, so the inbox can reopen the way they left it.
string
required
Must be "profiles"
string
required
Must be "get-inbox-filters"

Response

boolean
object
Example response

Save inbox filters

Remembers the authenticated user’s Conversations inbox filters. The saved filters are replaced as a whole — any field you leave out is stored as null. Malformed or unknown values are stored as null (meaning “all”) rather than rejected, so a bad value never blocks the save.
string
required
Must be "profiles"
string
required
Must be "save-inbox-filters"
object
required

Response

boolean
object
Returns VALIDATION_ERROR when data is missing or is not an object.

List sign-in sessions

Lists the authenticated user’s active sign-ins (browsers and devices), most recently active first.
Sign-ins can only be listed from the user’s own signed-in browser session. API keys, service calls and admin impersonation receive 403 Forbidden.
string
required
Must be "profiles"
string
required
Must be "list-auth-sessions"

Response

boolean
object
Example response

Revoke a sign-in session

Signs out one of the authenticated user’s other sign-ins. The current session cannot be revoked this way; sign out instead.
Sign-ins can only be revoked from the user’s own signed-in browser session. API keys, service calls and admin impersonation receive 403 Forbidden.
The revoked device can no longer renew its sign-in, but the access token it already holds stays valid until it expires (about an hour).
string
required
Must be "profiles"
string
required
Must be "revoke-auth-session"
object
required

Response

boolean
object
Returns VALIDATION_ERROR when sessionId is not a valid UUID or is the current session, and NOT_FOUND when the session does not exist or belongs to someone else.

Profile object

The full profile object returned by all, get, create, and update actions.

Core fields

string
User UUID.
string | null
string | null
string | null
string | null

Contact information

string | null
string | null

Address

string | null
string | null
string | null
string | null
string | null
string | null
string | null

Company

string | null
string | null

Preferences

string | null
string | null
string | null
string | null

External IDs

string | null
string | null

Marketplace

string | null
boolean | null

Team

number | null
object | null

Subscription

object | null

Call purchases

object[]

Phone subscriptions

object[]

Timestamps

string
string

Generate SSO token

Generates a signed, time-limited SSO token for the authenticated user. The token is used to authenticate the user into connected suite applications without a separate login. When impersonation parameters are provided, the token encodes the target user’s identity alongside the admin’s, allowing the receiving application to establish an impersonated session.
string
required
Must be "profiles"
string
required
Must be "generate-sso-token"
object

Response

boolean
object

Generates a signed, time-limited URL that redirects the user through an OAuth consent flow to authorise a third-party integration. The link is valid for a short window and is tied to the user’s email address. Regular users can only generate a link for their own email. Admins can generate a link for any user’s email.
string
required
Must be "profiles"
string
required
Must be "generate-sync-consent-link"
object
required

Response

boolean
object

Usage summary

Returns a usage summary for the profile (calls, leads, conversations, etc.).
string
required
usage-summary
string
Profile UUID. Defaults to the authenticated user. Admins may pass any profile ID.

Activity logging

Profile mutations are logged to the activities table:

Error responses