How to set up a HiBob marketplace install

October 16, 2026

Use this when a HiBob customer installs your app from Bob Marketplace. Bob sends the browser to a fixed callback with only a code. Unified exchanges that code and creates the connection.

The embedded sign-in flow, where the user starts in Unified and returns to your app, is a different setup. A HiBob app has only one Redirect URI, so see "One Redirect URI per HiBob app" below before you choose.

Before you start

• A Unified workspace in the region where the connection should live
• A HiBob app in the HiBob Developer Portal, with its Client ID and Client Secret. HiBob OAuth is only available to approved Marketplace and technology partners.
• The scopes your app needs, set on the HiBob app

1. Save the HiBob credentials in Unified

1. In Unified, open Integrations and activate HiBob for the environment you are using (Production or Sandbox).
2. Enter the Client ID and Client Secret from the HiBob app. HiBob issues separate Development and Production credentials. Use the set that matches the installs you expect, because tokens issued with one set cannot be refreshed with the other.
3. Save the integration. The marketplace callback reads these credentials. It does not take a workspace API key, and it does not use the App ID field. Unified only uses the App ID when the install starts in Unified.

2. Register the Redirect URI on the HiBob app

In the HiBob Developer Portal, open your app and, under OAuth, set the Redirect URI to the callback for this workspace and environment. Use the API host for the workspace region.

https://api.unified.to/hb/{workspace_id}/{environment}/connection

Replace the placeholders:

• workspace_id is the Unified workspace ID.
• environment is Production or Sandbox, matching the integration you activated.

Regional hosts:

• United States: https://api.unified.to
• Europe: https://api-eu.unified.to
• Australia: https://api-au.unified.to

Example:

https://api.unified.to/hb/5f9c2a1b8e4d3c0011223344/Production/connection

The URI must match exactly. Do not add a query string, a trailing slash, or a success or failure URL. HiBob only sends the authorization code to this address, and Unified sends the same address back to HiBob when it exchanges the code.

When you save the Redirect URI, HiBob regenerates the App Installation URL. If you test with the "App installation URL for testing", copy it again after this change.

3. Install from Bob Marketplace

1. In Bob, an admin opens your app in Bob Marketplace and clicks Install.
2. Bob shows the consent screen. The admin approves the scopes and chooses the People data access for the app.
3. Bob redirects the browser to the URL above with ?code=. The code expires after 5 minutes.
4. Unified creates the connection. The HiBob company ID (the companyId claim in the access token) is stored on the connection as the external reference.
5. Unified shows a short page saying the install finished and the tab can be closed. Unlike HighLevel, the browser is not sent back to Bob, because the page it came from is the consent screen.

If your workspace listens for new connections, that webhook includes the new connection and its external reference.

To test before your listing is live, follow Test apps in Bob Marketplace and use your Development credentials in Unified.

Each HiBob company is its own connection

Each company that installs the app creates a separate Unified connection, identified by its HiBob company ID.

Reinstalling the app creates a new connection. It does not update the existing one, and the old connection stops working at its next token refresh.

One Redirect URI per HiBob app

A HiBob app has a single Redirect URI, and HiBob requires every request to use it. An app set up with the URL above is for marketplace installs. Installs that start in Unified's embedded flow use https://api.unified.to/oauth/code as the redirect address, which does not match that app.

Uninstalls

Customers uninstall the app from Bob Marketplace. HiBob does not send a notification when this happens. The connection stops working at its next token refresh, when HiBob rejects the refresh token.

If the install fails

• Redirect URI does not match. Compare the HiBob app Redirect URI with the workspace ID, environment, and regional API host.
• HiBob integration is missing, or the Client ID and Client Secret are not saved for that environment.
• Development and Production credentials are mixed up. The credentials saved in Unified must belong to the same set as the install.
• The authorization code expired. Codes last 5 minutes, so start the install again.
• The admin declined the install. Unified shows the error HiBob returned.
• The HiBob app does not include the scopes you need. Scopes are configured on the HiBob app, not on the Redirect URI.

HiBob reference: Add and submit an app and OAuth 2.0.