Skip to main content

Sync users

Introduction​

This guide shows you how to mirror your system's users into Upheal so that providers, clients, and the provider-client relationships are kept consistent across both platforms.

There are two flows you'll typically run:

  1. Initial sync — one-time bulk import of all existing providers and clients when you first integrate.
  2. Ongoing sync — keep both systems aligned as users are created, updated, or removed in your system.

Upheal exposes both V1 and V2 user-management endpoints. This guide uses V2 wherever it exists and falls back to V1 only for endpoints that V2 does not provide.

Rate limits​

The user-management endpoints share a default rate limit of 300 requests per minute, per API key. When you exceed it, the API returns 429 Too Many Requests.

Recommendations:

  • For an initial sync of thousands of users, process them sequentially or with low concurrency to stay under the limit.
  • Implement exponential backoff on 429 responses.
  • The V1 and V2 endpoints share the same limit — splitting calls across versions does not raise the effective ceiling.

Initial sync​

Run providers first, then clients. Clients reference providers by Upheal userId, so all providers must exist before you can assign them.

tip

On every create call, pass partnerUserId (your internal ID for the user). Upheal includes it in webhook payloads, which makes incoming events easy to attribute to the right record in your system.

1. Sync providers​

For each provider in your system:

  1. Check if the provider already exists. Call POST /users/check with the provider's email.

    • If isUserExists is true, store the returned userId and move on to the next provider.
    • If isUserExists is false, continue to step 2.

  2. Create the provider in Upheal. Call POST /users/providers (V2) with at least email, firstName, and lastName. Store the returned userId against your internal provider record — you'll need it when creating clients.

    The create response contains an inviteUrl that the provider can use to finish setting up their Upheal account.

    • If providers in your integration also use Upheal's UI directly (for example, to manage notes or join video calls), share inviteUrl with them.
    • If your integration is API-only and providers never interact with Upheal's UI, you can ignore inviteUrl.

2. Sync clients​

Only start this step once all providers have been synced and you have their Upheal userIds on hand.

For each client in your system:

  1. Check if the client already exists. Call POST /users/check with the client's email (if you have one).
    • If isUserExists is true, store the returned userId and skip to step 3.
    • If isUserExists is false, continue to step 2.
  2. Create the client in Upheal. Call POST /users/clients (V2). Required fields are firstName, lastName, and therapistUserId — set therapistUserId to the Upheal userId of the client's primary provider.
  3. Assign additional providers, if needed. If the client sees more than one provider, call POST /users/{userId}/providers (V1) with the complete list of providerUserIds.
note

POST /users/{userId}/providers is a full-list replace — it replaces every provider currently assigned to the client with the list you submit. Always send the entire list, not just additions or removals.

Keep users in sync​

Once the initial sync is done, mirror future changes in your system to Upheal as they happen. Trigger the matching Upheal call on each event in your system.

New provider in your system​

Call POST /users/providers (V2) to create the provider in Upheal. Decide whether to share inviteUrl with the provider (same rule as in the initial sync).

New client in your system​

Call POST /users/clients (V2) with therapistUserId set to the client's primary provider in Upheal. If the client sees multiple providers, follow up with POST /users/{userId}/providers (V1) and the full list.

User updated in your system​

Client's providers change​

Use this whenever a client's provider assignment changes — adding a provider, removing one, or swapping the only provider for a different one. Call POST /users/{userId}/providers (V1) with the new complete list of provider IDs. Send every provider the client should now see, not only the ones being added or removed.

User leaves your system​

Call DELETE /users/{userId} (V1) to remove the user from Upheal. V2 does not currently expose a delete endpoint; use V1 for deletes.