Documentation
Become a partner

Quick start guide

Learn how to add and submit an app in the Developer Portal

This guide walks you through every step of bringing your integration to life, from logging into the Developer Portal to creating your app, submitting it for review, and finally going live in the HiBob Marketplace.

Whether you’re building your first integration or expanding your offering with multiple apps, this guide ensures a smooth and clear journey.

Onboarding flow overview

The lifecycle of your partner app includes:

  1. Initial setup: log in to Bob and the Developer Portal
  2. Develop:
    • Create and submit your app
    • Build and test your integration
    • Submit for technical and marketing review
  3. Distribute:
    • Provide a customer-facing user guide
    • Schedule your deployment and go live

Initial setup

Once your team has signed the T&Cs, you will need to complete these steps:

  1. Use the link you receive to open a new Bob Partner account for building and testing in Bob app.
  2. Use the invite you receive to create an account in the Developer Portal where you will manage you apps.

Relevant links

Create and submit your app

In this step, you will receive your development credentials and Installation link, which are required for the OAuth flow.

🚧

Important:

  • To complete this step, you’ll need to provide a valid redirect URI. This is where the authorization server sends the user after they approve the installation in Bob.
  • The redirect URI must work for users who are not logged in to your app yet, regardless of which installation mode you choose.
  • Use only OAuth 2.0. Other authentication methods (like service users or token-based) are not allowed for Marketplace apps. See OAuth 2.0 guide for more details on the OAuth flow.

  1. Login to the Developer Portal.

  2. From the top left, select My apps.

  3. Click Create app.

  4. Set up Basic Information, fill in the following fields:

    • App icon: Upload the logo for your app (160x160 px preferred, 1:1 ratio).
    • App name: The name of your app as it will appear in the Marketplace. Usually, the name is your app’s name.
    • App description: A short summary of your app’s purpose and main features (1–2 sentences). This info will show in Bob Marketplace.
    • Built by: The name of the company building the app (if different from the app name).
    • Preview: Review how your app will look in Bob Marketplace.

  5. Set up Installing your app (on the same Basic information page, below Preview):

    Choose how users discover and install your app.

    • Install from Bob Marketplace: Users can install your app directly from the Bob Marketplace. An Install button appears on your app listing and starts the OAuth consent flow in Bob.
    • Install from your landing page: An Install button appears on your app listing. When clicked, Bob sends the customer to your landing page to install. You control the onboarding experience. When selected, provide a Landing page URL (required, HTTPS).
    Installation modeMarketplace buttonWhen customer clicks InstallWhat you need
    Install from Bob MarketplaceInstallOAuth consent flow starts in BobNo extra fields
    Install from your landing pageInstallCustomer is sent to your landing page URLLanding page URL (HTTPS)
    🚧

    Notes:

    • Your app is listed in the HiBob Marketplace in both modes.
    • If you choose Install from your landing page, embed your App Installation URL on that page after your onboarding steps. See Start installation from your landing page in the OAuth guide.
    • Uninstall always happens in Bob, regardless of installation mode.
    • Click Save on the Basic information page to apply your installation mode.

  6. Set up Redirect URI:

    • Click OAuth and scroll down to redirect URI.
    • Enter the redirect URI. This is where the authorization server sends the user after they approve the installation in Bob.
    • Click Save.
    • Once you save the Redirect URI, the installation URL will regenerate automatically to include it.

  7. Set up Scopes:

    • Scopes define which data your app can access. You must specify at least one scope in order to test your app.
    • Click Manage scopes.
    • From the list on the left, expand each topic and select the actions your app needs to have access to.
    • Each selection will add to the scope on the right.
    • Click Apply and then click Save.
    • Once you save the scopes, the App installation URL for testing and App Installation URL will regenerate automatically to include it.
      🚧

      Scopes notes

      • When the user installs and approves the scopes, they also choose whos data the app can access in Bob.
      • If your app relies on custom fields, ensure those fields exist in the testing Bob account.
      • When the user installaing the app has cutom employee fields defined in their workspace, Bob always adds the scope: Manage custom categories and fields (custom_resources:write) to the installation consent screen automatically, regardless of which scopes you select. It is not available in the scope picker.

  8. Set up Webhooks (optional):

    Use this option only if your app relies on Webhook events from Bob for updates.

    • Click Webhooks.

    • Click the toggle on the right to Allow event subscription.

    • Enter the Endpoint URL.

    • Click Validate. This will send a test message to your listener. Ensure your listener responds with a 200 status code to proceed.

    • Once validated, click Manage events to select the events your app will listen to.

    • Click Save.

    • Copy the Secret that was generated.

    • Use the secret to authenticate the events and secure your connection. See how does Bob calculate the signature.

    🚧

    Note: Be sure to review Getting Started with Partner Webhooks for detailed implementation instructions.

  9. Build and test your app

  10. Add the app Listing Details: this would typically be filled out by your Marketing team or Partner Manager and includes:

  • Screenshots
  • Integration description
  • Value statements
  • Support contacts
  • Optional help article links
  • App listing provides a rich-text editor (WYSIWYG), allowing formatting and embedded links.

Build and test your app

Build your app

  • Implement OAuth.​

  • Connect to Bob APIs.

  • Validate scopes.

  • Validate data access with audience restriction.

  • Test all data flows end-to-end.

  • Verify webhook handling (if used).

  • Test app installation

Test app installation

  1. Test app installation from Bob Marketplace (if you chose Install from Bob Marketplace):

    • In the Developer Portal, from OAuth, scroll to Test your app installation.
    • Click Test from Bob Marketplace > Install button.
    • This will open Bob's consent screen and then redirect to your redirect URI.

  2. Test installation from your landing page (if you chose Install from your landing page):

    • Click Install on your marketplace listing (or Test from Bob Marketplace > Install in the Developer Portal).
    • Verify Bob sends the customer to your landing page URL.
    • Complete your onboarding flow on the landing page, then start OAuth using your App installation URL for testing.
    • Verify the consent screen appears and the redirect to your redirect URI succeeds.

  3. (Optional) Test installation from anywhere (Postman, your marketplace, etc.)

    • In the Developer Portal, under Development credentials, copy the Client ID and Client Secret, and use them as your credentials to implement and test OAuth 2.0.
    • From Test your app installation, copy App installation URL for testing and use it from anywhere. It already contains the redirect URL, scopes, and app ID, so if you change your setup, you need to copy it again.
🚧

Once your integration is stable and your listing is complete, proceed to submission.

Submit for App Technical Review

When your app is ready, you’ll need to submit it for technical review. As part of this process, you are required to upload a certification video demonstrating your integration.

Video flows coverage

The certification video should demonstrate your integration end-to-end and include the following:

  1. OAuth installation flow for your installation mode:
    • Install from Bob Marketplace: OAuth flow starting from Bob (including consent screen and redirect to your application)
    • Install from your landing page: Bob Marketplace Install → your landing page → OAuth consent screen → redirect to your application
  2. Initial data sync (e.g., pulling employee data from Bob)
  3. Specific flows relevant for the data you access:
    • Employee lifecycle flows, such as employee creation or sync, employee update, or employee termination.
    • Time off requests, such as time off request submitted or time off request approved.
    • Other event-driven data flows such as Position events, Task events, Docs events, etc.
  4. Any additional supported flows (e.g., writeback, webhooks, or other key functionality)
  5. Uninstall flow:
    • Uninstall the app using the uninstall link.
    • Confirm tokens or connections are invalidated.

Technical video requirements

  • App ID: The certification video must be recorded using the same app ID that was submitted for technical review.
  • Timeline: The video should be recorded no later than 14 days after the initial app submission.
  • Scope coverage: Ensure the flows demonstrated in the video align with the requested app scopes. Each requested scope should correspond to a clear functional use case shown in the demo.
  • Testing environment: You must use your dedicated Bob account with demo data when recording the certification video. The same environment will be used for the technical validation and compare the results against:
    • The functionality demonstrated in the video
    • The scopes requested in the Developer Portal
  • Real-time demonstration: The video should include live execution of integration flows (e.g., triggering a sync, updating an employee, or performing a write action), not just a walkthrough of the UI. These actions should demonstrate real-time API calls during the recording.
  • Clean testing environment: During the recording period, avoid mixing unrelated testing or development activity under the same app ID, as this may impact the accuracy of the technical review.
  • Video production guidelines:
    • Length: 5–6 minutes
    • Use demo data only
    • Add voiceover or captions
    • Upload as unlisted video link

Submit a User Guide

A customer-facing user guide is required before going live.

Include:

  • Overview of the integration
  • Installation steps — in Bob and/or on your landing page, depending on your installation mode
  • Setup in your platform
  • Data sync flows
  • Screenshots or short clips
  • Troubleshooting tips
  • Support contact info

Schedule deployment and go live

🚧

In this step, make sure you replace your development credentials with the Production credentials.

After approval:

  1. Agree on a go-live date with HiBob
  2. Ensure final validation is completed
  3. From the developer portal:
    • From OAuth > Production credentials
    • Copy the Client ID and Client secret
    • Replace your credentials with the Production credentials
  4. Your app is published and visible to customers in the Marketplace

At this point, your app is installable via the HiBob Marketplace based on the installation mode set in Basic information.

Contact us

Need assitance?