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. Become a partner (if you are not already): submit the partner application, get approved, sign the Terms and Conditions, receive a Bob account, then receive a Developer Portal invitation
2. Initial setup: log in to Bob and the Developer Portal
3. Develop:
   • Create and submit your app
   • Design your multi-tenant installation layer — store tokens per Bob company and link installs to your customers
   • Build and test your integration
   • Submit for listing review and technical review; complete Security Review when required for your category (see Security Review)
4. Distribute:
   • Provide a customer-facing user guide
   • Schedule your deployment and go live

Initial setup

If you are not yet a partner

1. Submit the partner application form.
2. After approval, sign the Terms and Conditions.
3. You receive a Bob Partner account for building and testing.
4. You receive an invitation to the Developer Portal, where you can add your apps.

You can start the Security Review as soon as you sign the Terms and Conditions — even before you have Developer Portal access.

If you are already an approved partner

Once your team has signed the Terms and Conditions, complete these steps:

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

Relevant links

• Become a partner: https://www.hibob.com/partner/
• Bob App Login: https://app.hibob.com
• Developer Portal: https://developers.hibob.com

Create and submit your app

In this step, you will receive your development credentials and Installation link, which are required for 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 mode	Marketplace button	When customer clicks Install	What you need
   Install from Bob Marketplace	Install	OAuth consent flow starts in Bob	No extra fields
   Install from your landing page	Install	Customer is sent to your landing page URL	Landing 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 whose data the app can access (People data access).
     • Approving a scope includes current and future data in that scope. If the customer later adds custom fields, columns, or tables in a category covered by an approved scope (for example View employee data), that data is included automatically. Bob shows this on the consent screen: The permissions you approve here stay the same for this app. However, if your organization updates its fields or categories, the data included in those permissions may change.
     • If your app relies on custom fields, ensure those fields exist in the testing Bob account so you can verify they are returned under the approved employee-data scope.

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

   • Follow the steps to build and test your app.
   • Follow the steps to test your app's installation.

10. Complete listing content for Overview and About (marketing-oriented)

Listing content is marketing-oriented. It is usually owned by your Marketing team or Partner Manager, not your engineering team. The live Marketplace app page has two content sections filled from different sources — partners often mix these up on first submission, which leads to revision requests.

Overview (App listing details in the Developer Portal)

Complete under Distribute → App listing details. Fields under Overview (for example App gallery, Value statement, and Functionality and how the integration works) populate the Overview section of the live listing. Also complete support contacts, optional help article links, and any other listing fields shown there. The editor supports rich text (formatting and embedded links).

Focus Value statement and Functionality on the integration itself — what the Bob ↔ partner app does for customers and how it works — not a general pitch for your standalone product.

About (Tech Partner Overview form)

Complete the external Tech Partner Overview form linked from the Developer Portal. That submission populates the About section of the live listing (company/solution description, platform value proposition, and key features of your product).

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

• Managing customer installations — multi-tenant model, callback patterns, and installation lifecycle (read before implementing your redirect URI).

• Test apps in Bob Marketplace (Dev mode) — in Bob, open Bob products > Marketplace > Manage apps > In development to see your Developer Portal apps (Dev mode) for listing and install testing on your partner company.

• Test app installation

Test app installation

Apps you create in the Developer Portal also appear in Bob under Marketplace → Manage apps → In development (company-scoped Dev mode). Use that view when you want the full Marketplace user journey; use Test from Bob Marketplace in the Developer Portal when you mainly need to verify Bob OAuth consent and redirect. See Test apps in Bob Marketplace (Dev mode).

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.
   • Or, in Bob, open Bob products > Marketplace > Manage apps > In development, then install from the app tile to test the full Marketplace experience. See Test apps in Bob Marketplace (Dev mode).

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.

Submit for review

When your app is ready, click Submit for review in the Developer Portal. Complete App listing details and the Tech Partner Overview form before or as part of submission so listing content is ready for review.

When you submit your app, it goes through two separate reviews:

• Listing review: the general listing content and marketing assets used in the Overview and About sections. This review is marketing-oriented and is usually prepared by your Marketing team or Partner Manager.
• Technical review: technical details, scopes, user guide, integration video, and related materials. Prepare this with your technical team.

Listing review and technical review are separate tracks. Both must pass before go-live. Listing review does not replace technical review — passing listing review does not mean the integration itself was approved.

Review materials should tell one consistent story: what the listing promises should match the scopes you requested, the flows in your certification video, and the steps in your user guide.

Technical review

As part of technical review, 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 for technical review and before going live. Write it for a first-time Bob admin, not for your engineering team.

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

Listing review

Listing review is marketing-oriented. It covers the content customers see on your live Marketplace page — the Overview and About sections described in step 10 above — and is usually prepared by your Marketing team or Partner Manager.

Keep Overview focused on the Bob ↔ partner integration; keep About focused on your company and product platform. Incomplete or mixed content is a common reason for listing revision requests after the first submission. Listing review does not replace technical review — passing listing review does not mean the integration itself was approved.

Security Review

You may also go through a Security Review, which follows a separate timeline from listing review and technical review.

You can initiate Security Review as soon as you sign the Terms and Conditions — even before you have access to the Developer Portal — or at any later point, including after your app goes live. You can also initiate it more than once. For example, if your first review identifies a missing security requirement or standard, you can address the gap and initiate another review.

Whether you must pass Security Review before launch depends on your app category:

• For apps in the Payroll and Global Payroll categories, the Security Review is mandatory. Your app must successfully pass it before it can go live in the Marketplace.
• For apps in all other categories, the Security Review is optional. You can complete it to qualify for the Security Certified badge on your app listing, but your app can go live without it.

Schedule deployment and go live

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?

• For Technical assistance, contact us at [email protected]
• For any business queries, contact us at [email protected]
• Join other Marketplace partners in Bob for Builders