UserGuiding User Management API Guide

Auth method: API Token (Bearer token passed in Authorization header)

Setup steps

1. Log in to your UserGuiding dashboard.
2. Navigate to Settings → Integrations → API.
3. Generate or copy your API Token.
4. Include the token in all requests as: Authorization: Bearer

Identify / Upsert User

• Method: POST
• URL: https://api.userguiding.com/v1/identify
• Watch out for: userId must exactly match the ID used in the frontend SDK initialization; mismatches result in duplicate user profiles.

Request example

POST /v1/identify
Authorization: Bearer <TOKEN>
Content-Type: application/json
{
  "userId": "user_123",
  "attributes": { "email": "user@example.com", "plan": "pro" }
}

Response example

{
  "success": true
}

Identify / Upsert Company

• Method: POST
• URL: https://api.userguiding.com/v1/identify
• Watch out for: Company attributes are passed nested inside the same identify call; there is no separate company endpoint.

Request example

POST /v1/identify
Authorization: Bearer <TOKEN>
Content-Type: application/json
{
  "userId": "user_123",
  "company": { "companyId": "acme", "attributes": { "name": "Acme Corp" } }
}

Response example

{
  "success": true
}

• Rate limits: Rate limits are not explicitly documented in official sources.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No official rate-limit documentation found. Treat as unknown.

• Pagination method: none

• Default page size: 0

• Max page size: 0

• Pagination pointer: Not documented

• Webhooks available: No

• Webhook notes: No official webhook support documented in UserGuiding's API or help center as of the policy date.

• Alternative event strategy: Use UserGuiding's native integrations (e.g., Segment, Amplitude, HubSpot) or Zapier to react to guide completion and NPS events.

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise (Corporate)
• Endpoint: Not documented

Limitations:

• No native SCIM provisioning documented.
• SSO is listed as a Corporate-tier feature but SCIM provisioning is not confirmed in official docs.
• No IdP connector (Okta, Entra, Google Workspace, OneLogin) officially listed.

The three documented integration patterns are server-side attribute sync on login, company association via nested identify payload, and bulk attribute backfill via iterated POST calls.

For server-side sync, call POST /v1/identify on successful authentication with userId, relevant attributes (plan, role, created_at), and the Authorization: Bearer header

the frontend SDK picks up updated attributes on next page load, but guide display still requires the SDK to be active client-side.

For company association, include a company object with companyId in the same identify call;

there is no separate company endpoint and no explicit unlink operation is documented, so account switches require a new identify call.

For bulk backfill, there is no batch endpoint

each user requires an individual POST call, and since rate limits are entirely undocumented, implement exponential backoff and monitor for HTTP 429 responses before running at volume.

Server-side user attribute sync on login

1. On successful authentication in your backend, call POST /v1/identify with the user's userId and relevant attributes (plan, role, created_at).
2. Include Authorization: Bearer header.
3. UserGuiding updates the user profile; the frontend SDK will pick up the latest attributes on next page load.

Watch out for: Attributes set server-side are available for segmentation but guide display still requires the frontend SDK to be loaded.

Associate user with a company/account

1. Include a company object in the identify payload with companyId and desired company attributes.
2. Send POST /v1/identify with both userId and company fields.
3. UserGuiding links the user to the company, enabling company-level segmentation.

Watch out for: If companyId changes (e.g., user switches accounts), send a new identify call; there is no explicit unlink operation documented.

Bulk backfill user attributes

1. Iterate over your user records and send individual POST /v1/identify calls for each user.
2. Add a delay or rate-limiting mechanism between requests as official rate limits are undocumented.
3. Verify attribute updates in the UserGuiding dashboard under Users.

Watch out for: No bulk/batch endpoint exists; each user requires a separate API call. Monitor for HTTP 429 responses and implement backoff.

The most common integration failure is a userId mismatch between the server-side API call and the frontend SDK initialization - the match is case-sensitive, and any divergence silently creates duplicate user profiles in the identity graph rather than throwing an error.

Custom attributes written via the API are not retroactively applied to historical sessions, so backfills affect future segmentation only. Webhooks are not supported; to react to guide completion or NPS events, you must route through UserGuiding's native integrations (Segment, Amplitude, HubSpot) or Zapier.

SCIM provisioning is not documented even at the Corporate tier, meaning the identity graph built through the API cannot be managed through a standard IdP connector - automated lifecycle operations require custom tooling against the upsert endpoint.