Profiles - Help Genie

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

Access control

Action	Regular user	Admin
`all`	No	Yes
`list`	No	Yes
`get`	Own profile only	Any profile
`create`	No	Yes
`update`	Own profile only	Any profile
`delete`	Own profile only	Any profile
`check-timezone`	Yes (own profile)	Yes
`generate-sso-token`	Yes (own session)	Yes (+ impersonation)
`generate-sync-consent-link`	Yes (own email)	Yes (any email)
`usage-summary`	Yes (own profile)	Yes

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

Value	Description
`"standard_user"`	Business owner — can create and manage agents, view leads, and access all standard features
`"consumer"`	End user — can talk to agents and interact with consumer-facing features
`"internal_admin"`	Full platform access — can manage all users, agents, marketplace listings, and system settings

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

Show properties

number

Results per page. Range: 1-500. Default: 50.

number

Pagination offset. Default: 0.

object

Show properties

string

Search in full_name or email.

string

Filter by role (exact match).

number

Filter by team ID.

boolean

Filter profiles with active subscriptions.

string

Column to sort by. One of: "created_at" (default), "email", "full_name".

string

Sort direction. "asc" or "desc". Default: "desc".

Response

boolean

object

Show properties

object[]

Array of full profile objects with joined relations. See profile object.

number

const response = await ApiService.invoke<{
  profiles: Profile[];
  count: number;
  limit: number;
  offset: number;
}>({
  resource: "profiles",
  action: "all",
  data: {
    limit: 100,
    offset: 0,
    filters: {
      role: "internal_admin",
    },
  },
});

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

Show properties

number

Results per page. Range: 1-500. Default: 50.

number

Pagination offset. Default: 0.

object

Show properties

string

Search in full_name or email.

string

Filter by role.

number

Filter by team ID.

Response

boolean

object

Show properties

object[]

Show Basic profile fields

string

string | null

number | null

string

number

const response = await ApiService.invoke<{
  profiles: Profile[];
  count: number;
}>({
  resource: "profiles",
  action: "list",
  data: {
    limit: 50,
    filters: {
      searchTerm: "john@example.com",
    },
  },
});

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

Show properties

object

Full profile object with all joined relations. See profile object.

const { user } = await supabase.auth.getUser();
const response = await ApiService.invoke<{ profile: Profile }>({
  resource: "profiles",
  action: "get",
  id: user.id,
});

const subscriptions = response?.profile?.call_purchases;

curl -X POST https://api.helpgenie.ai/v1/profiles \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "get",
    "id": "d4f8e2a1-5b3c-4e9f-a1b2-c3d4e5f67890"
  }'

Create a profile (admin)

Creates a new user profile. The id must match an existing auth user UUID.

string

required

Must be "profiles"

string

required

Must be "create"

object

required

Show properties

string

required

Auth user UUID. Must match an existing user in the auth system.

string

number

string

boolean

Response (status 201)

boolean

object

Show properties

object

The created profile with joined data.

const response = await ApiService.invoke<{ profile: Profile }>(
  {
    resource: "profiles",
    action: "create",
    data: {
      id: "auth-user-uuid-here",
      full_name: "Jane Smith",
      email: "jane@example.com",
      role: "standard_user",
    },
  },
  201
);

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 combination of profile fields. See the create action for the full list of fields (all fields except id are accepted).

Response

boolean

object

Show properties

object

The updated profile with joined data.

const response = await ApiService.invoke<{ profile: Profile }>({
  resource: "profiles",
  action: "update",
  id: userId,
  data: {
    full_name: "John Doe",
    timezone: "America/New_York",
    company_name: "Acme Corp",
  },
});

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

Show properties

boolean

string

This permanently deletes the profile record.

const response = await ApiService.invoke<{
  success: boolean;
  message: string;
}>({
  resource: "profiles",
  action: "delete",
  id: "user-uuid",
});

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

Show properties

boolean

await ApiService.invoke({
  resource: "profiles",
  action: "check-timezone",
});

curl -X POST https://api.helpgenie.ai/v1/profiles \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "check-timezone" }'

Profile object

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

Core fields

string

User UUID.

string | null

Contact information

string | null

Address

string | null

Company

string | null

Preferences

string | null

External IDs

string | null

Marketplace

string | null

boolean | null

Team

number | null

object | null

Show properties

number

string

Subscription

object | null

Show properties

number

string | null

number | null

string | null

string

Call purchases

object[]

Show properties

number

number | null

string | null

string

Phone subscriptions

object[]

Show properties

string

Timestamps

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

Show properties

string

The user ID of the account to impersonate. Must be supplied together with adminUserId. Both fields must be present for impersonation fields to be embedded; supplying only one has no effect.

string

The admin user’s own ID. Must be supplied together with impersonatedUserId.

Response

boolean

object

Show properties

string

A signed token string in the format email={email}&ts={unix_timestamp}[&imp_uid={id}&admin_uid={id}]&sig={hmac_hex}. Pass this value to the target suite application to authenticate the session.

const response = await ApiService.invoke<{ token: string }>({
  resource: "profiles",
  action: "generate-sso-token",
});

const ssoToken = response?.token;
// Redirect: https://app.example.com/sso?token=<ssoToken>

const response = await ApiService.invoke<{ token: string }>({
  resource: "profiles",
  action: "generate-sso-token",
  data: {
    impersonatedUserId: "target-user-uuid",
    adminUserId: "admin-user-uuid",
  },
});

const ssoToken = response?.token;

curl -X POST https://api.helpgenie.ai/v1/profiles \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "generate-sso-token"
  }'

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

Show properties

string

required

The email address of the user to generate the link for. Must match the authenticated user’s email unless the caller is an admin.

string

required

The integration to connect. Must be one of: "airtable", "anthropic", "asana", "github-app", "google-calendar", "google-sheet", "hubspot", "simpro", "slack", "supabase", "xero".

Response

boolean

object

Show properties

string

A signed consent URL. Redirect the user to this URL to complete the integration authorisation flow. The URL includes HMAC-verified query parameters (email, ts, sig, connection) and is time-limited.

const response = await ApiService.invoke<{ url: string }>({
  resource: "profiles",
  action: "generate-sync-consent-link",
  data: {
    email: "user@example.com",
    connection: "slack",
  },
});

// Redirect the user to response?.url to complete authorisation
const consentUrl = response?.url;

const response = await ApiService.invoke<{ url: string }>({
  resource: "profiles",
  action: "generate-sync-consent-link",
  data: {
    email: "customer@example.com",
    connection: "hubspot",
  },
});

const consentUrl = response?.url;

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "profiles",
    "action": "generate-sync-consent-link",
    "data": {
      "email": "user@example.com",
      "connection": "google-calendar"
    }
  }'

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:

Action	Activity type	Action logged
Create	`user_action`	`profile_created`
Update	`user_action`	`profile_updated` (includes `updated_fields` in metadata)
Delete	`user_action`	`profile_deleted`

Error responses

Status	Code	Description
400	`VALIDATION_ERROR`	Profile ID not provided
401	`UNAUTHORIZED`	Invalid or missing authentication token
403	`FORBIDDEN`	Non-admin accessing admin-only action, or user accessing another user’s profile
404	`NOT_FOUND`	Profile does not exist
500	`INTERNAL_ERROR`	Database operation failed

​Access control

​role values

​List all profiles (admin)

​Response

​List basic profiles (admin)

​Response

​Get a profile

​Response

​Create a profile (admin)

​Response (status 201)

​Update a profile

​Response

​Delete a profile

​Response

​Check timezone

​Response

​Profile object

​Core fields

​Contact information

​Address

​Company

​Preferences

​External IDs

​Marketplace

​Team

​Subscription

​Call purchases

​Phone subscriptions

​Timestamps

​Generate SSO token

​Response

​Generate sync consent link

​Response

​Usage summary

​Activity logging

​Error responses

Access control

`role` values

List all profiles (admin)

Response

List basic profiles (admin)

Response

Get a profile

Response

Create a profile (admin)

Response (status 201)

Update a profile

Response

Delete a profile

Response

Check timezone

Response

Profile object

Core fields

Contact information

Address

Company

Preferences

External IDs

Marketplace

Team

Subscription

Call purchases

Phone subscriptions

Timestamps

Generate SSO token

Response

Generate sync consent link

Response

Usage summary

Activity logging

Error responses