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 support the Marketplace-first install flow (starting from Bob) and must work for users who are not logged in to your app yet.
  • The installation URL is is dynamically generated and is used by Bob Marketplace to start installation. You can use the Installation URL for testing, when in developer mode, and add &mode=dev to the URL. Note that when you change your setup the URL changes and you need to copy it again.
  • 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:

    • Icon (TBD): Upload the logo for your app (min. size: 160x160 px, 1:1 ratio). This feature may not be available yet.
    • Name: The name of your app as it will appear in the Marketplace. Usually, the name is your app’s name.
    • Description: A short summary of your app’s purpose.
    • Builder (optional): The name of the company building the app (if different from the app name).

  5. 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.

  6. 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 installation URL will regenerate automatically to include it.
🚧

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.

  1. 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.
    🚧

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

  2. Copy OAuth details for testing:

    • From Development credential, copy Client ID and Client Secret and use them as your credentials to implement and test OAuth 2.0.
    • From App installation URL, copy the unique URL for testing or publishing in your Marketplace listing. While testing with developer credentials, you need to add a query param: mode=dev to the installation URL.
    • Use these details to build and test your app.

  3. App Listing Details 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

🚧

This section is for Developers testing the app with Bob’s developer environment

Use the Development credentials from the portal to:

  • 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)
  • Install a draft version of your app via the installation URL found in the OAuth section in the developer portal.
🚧

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 from Bob (including consent screen and 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 that the flows demonstrated in the video reflect the scopes requested for the app. 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
  • 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 Marketplace, using the installation link defined during app creation.

Contact us

Need assitance?


Updated 11 days ago