Overview

The Payroll Hub for Partners Public API enables payroll providers to seamlessly integrate with HiBob's ecosystem and automate payroll data synchronization.

The Payroll Hub API provides programmatic access to payroll-specific reports so you can:

1. Receive webhook notifications when data syncs are triggered
2. Retrieve the sync report with employee changes and updates
3. Update sync status to provide feedback to customers

Common use cases include:

• Automating employee onboarding into your payroll system
• Keeping employee records up to date with the latest changes
• Reducing manual data entry and minimizing errors
• Maintaining compliance through accurate record keeping

Payroll Hub Integration Architecture

The Payroll Hub uses a Push-to-Pull Hybrid model designed for optimal partner experience:

1. Event notification via webhook: HiBob sends you a webhook when data is ready (triggered by customer sync action)
2. Controlled data retrieval: Your system calls the Payroll Hub API to fetch the required sync request data.
3. Process data on your terms: Validate and process the data within your systems.
4. Return status: Send success/error responses per record to provide feedback to customers before the sync request expires.

   📘

   Sync request expiration window

   Each sync request has two deadlines. The expiringAt timestamp in the webhook payload marks the first one, which by default is 2 minutes after the webhook is sent.

   Action	Deadline	If you miss it
   First GET (retrieve sync records)	By expiringAt	The request returns a 400 timeout error, and you can no longer retrieve the records.
   First PUT (update at least one record's status)	Within 30 seconds after expiringAt	The request returns a 400 timeout error.

   Extending the window: Each PUT that updates at least one record extends the window by another 2 minutes. Within that time, update at least one more record to extend it again, and continue until all records are updated.

   Complete the GET before expiringAt. The extra 30 seconds for the first PUT is a buffer, not a target.

sequenceDiagram
    User->>Bob: Triggers sync request
    Bob-->>Payroll System: Webhook: Sync Request event (syncRequestId, expiringAt)
    Payroll System->>Bob: GET /sync-requests/{syncRequestId}/sync-records
    Bob-->>Payroll System: Sync records + templateId, templateName
    Payroll System->>Payroll System: Process the Sync Request records
		Payroll System->>Bob: PUT /sync-requests/{syncRequestId}/sync-records
    Bob->>User: Review sync status

Integration templates and connections

You can offer one or more integration templates for your app. A template defines the fields and field mapping your payroll system expects. Offer more than one template when different customer populations need a different data structure, for example UK vs Germany, employees vs contractors, or two payroll products you provide.

On the customer side:

• A customer who installs your app creates one or more connections. Each connection is based on one of your templates.
• Each pay cycle in Bob uses one connection. Several pay cycles can share the same connection, for example two UK pay cycles with different schedules.
• When a sync runs, the records follow the field structure of the template behind that pay cycle's connection.

This means one company can send you syncs that use different templates. Get sync report data returns templateId and templateName at the top level of every response page, so you know which field structure to expect. See Identify the template for a sync.

Plan your templates

Each Payroll Connect configuration (instance) you create can become one template, with its own fields that you define. You can use templates however suits your customers, for example:

• One template per country, with country-specific fields.
• Two templates for the same country: a lean set of fields for most customers, and an extended set for enterprise customers who typically need more fields.

How customers install a template

Customers set up your app in Bob by installing it from the Marketplace, then clicking Manage on your tile to create a connection. When they create a connection, they select one of your templates and map your fields to their Bob fields. Finally, they add the connection to a pay cycle. The Bob help center article Set up a payroll partner connection describes each step in Bob. Use it as a helper for your customers and your implementation manager, to make sure every step is covered. It doesn't replace your own onboarding, so share it alongside your user guide and implementation process, not instead of them.

Two parts of the journey depend on your side:

• Authentication. After the customer clicks Install in the Marketplace, Bob sends them to your side to authenticate, then back to your Marketplace page. Make sure that flow works for customers who aren't yet logged in to your product.
• Value mapping. Customers map lists and codes between Bob and your system in your product, not in Bob. Tell them where to do it in your user guide.

How fields behave for customers

• When the customer creates the connection: The fields are locked. The customer can't add, rename or remove them, and can only change which Bob field each one is mapped to.
• When the customer sets up a pay cycle: All fields are currently mandatory, so the customer can't remove fields from a report.

Update a template

1. Update the same Payroll Connect configuration that the template was created from.
2. Tell HiBob. We update the template and let you know when it's done.
3. Your customers create a new connection from the updated template, field-map it from scratch, and set up the pay cycle or cycles for the new connection again. A customer needs to reinstall to apply the changes.

Setup and Testing Flow

1. Step 1: Create your app in the Developer Portal and get the installation link for testing
2. Step 2: Configure the report in Payroll Connect (one report per template) and send the template details to HiBob
3. Step 3: Add and activate a pay cycle
4. Step 4: Install your app (developer mode)
5. Step 5: Discover field types and list values
6. Step 6: Send sync requests and test your integration
7. Step 7: Submit your app for review to be published in the marketplace

Step 1: Create your app to obtain installation

1. Log in to the developer portal.
2. Follow the Quick start guide to set up your app, and select the required scopes and webhooks.
3. You will need the installation link for testing.
4. Implement your server side OAuth flow and Webhook listener.

Step 2: Configure the report in Bob’s Payroll Connect

Each Payroll Connect report you configure here represents one integration template. To offer more than one template, repeat this step for each template, for example one report for UK and one for Germany. Each report can have its own fields and field mapping.

1. Add a configuration in Payroll connect

   • In Bob, from the top left, click Bob products > Marketplace.
   • From the left menu, select Payroll.
   • Click the Payroll connect tile.
   • Click Connect.
   • Click + Add configuration at the bottom of the screen.
   • Select Start from scratch to set up a connection.
   • This opens the Configure payroll reports wizard, used to set up a custom payroll connection.

2. Connection Details

   • In the Vendor name field, enter your company Name.
   • In Transfer method, select File download.
   • Leave all other selections as-is.
   • Click Next to proceed to Fields, where you define the fields required by your payroll system.

3. In Fields, add the fields you want to receive from Bob via the API:

   • For each field:

     • In the Vendor field column, enter the Field Name as you want it to appear in the sync request data. Use a human-readable name, not a code alone (see the prerequisite at the start of this step).
     • Check the boxes next to the Bob reports you want to include the field in: Changes, New Hires, Terminations, and Time Off.
     • Click +Add field to add more fields.

   • To add a Deduction, Variable pay, Actual Payment or Entitlement field, click the arrow next to +Add field and select the required option.

   • Select a field (any field will do) as the Identifier field.

   • Click Next.

   🚧

   Note: Currently New Hires, Changes, Terminations, and Time Off reports are supported for the partner sync API.

4. In Value Mapping click Next to skip this step.

5. In Field Mapping, add mapping to the actual fields in Bob. This determines which Bob fields’ values will appear in the API response data object. For each field:

   • In Mapped with, always choose Exact.

   • In Source, select the field in HiBob you want to map to each field.

   • Click Next when done mapping all the fields.

   🚧

   Note: If you want to map a Bob custom field, make sure it is included as a prerequisite for clients as part of the user guide.

6. In Report settings, click Done to skip this step and finalize the configuration.

7. Send your template details to the partner support team. Each Payroll Connect configuration (also called an instance) can be converted into a template that customers choose from your Marketplace tile. HiBob creates the template from your configuration, so for each one you want to offer, tell us the following three parameters. The more detail you give, the easier the process.

   Parameter	What to provide
   Connection	The Payroll Connect configuration you want HiBob to convert into a template.
   Template name	The name customers will see. Mention the country the template is relevant for, for example Payroll UK. This is the templateName returned in Get sync report data.
   Template description	A short description customers will see for this template, for example Extended fields for enterprise customers in Denmark.

   Once HiBob has created the templates, we let you know. The partner support team adds them to your app's Marketplace profile.

Step 3: From Bob: Add and activate a pay cycle in Payroll Hub

• From Bob products > Payroll > Settings, click Add pay cycle.
• In Vendor, select the Payroll Connect configuration you defined in Step 2.
• Click Continue.
• Enter a Pay cycle name and click Next.
• From People and frequency enter the required fields. To learn more, see the relevant People and frequency in the help center.
• From Reports, select which reports will be sent to the payroll system with this pay cycle, and if the data will be synced automatically.
• To ensure a report is included in the pay cycle, select Enable [report name] for this pay cycle.  To learn more, see Reports settings in the help center.
• Click Next, skip the Report fields step, and then click Save.
• From the top right, click Activate to activate the pay cycle.

Step 4: Install your app in developer mode

• When testing, you can use the installation link to create an OAuth token via Postman with developer credentials. To learn mode, see Step 3: Request authorization in the OAuth guide.

• When you have a token from Postman, you can use it to try the endpoints from the documentation

  Action	Endpoint
  Get sync report records	[BETA] Get sync report data
  Update sync status	[BETA] Update sync request records
  Get integrations metadata	[BETA] Get integrations metadata

• Make sure your Webhook listener is up and running and that you are using the Developer Credentials in your OAuth flow.

Step 5: Discover field types and list values

After you configure vendor fields in Payroll Connect and install your app, call [BETA] Get integrations metadata to fetch the partner-facing field catalog for your integrations. Your OAuth app needs the company.metadata:read scope.

Use this response during setup to:

• Learn each field’s vendorFieldName (these match the keys in sync record data)
• Learn each field’s partner-facing type
• For list, multi-list, and hierarchy-list fields, retrieve allowed values when a list catalog is available

Rate limit: 5 requests per minute per auth.

Step 6: Send sync requests to test your integration

1. To test each sync request type, you should first make sure you have relevant updates included in the report:
   • For changes, make changes to the fields you selected to send in sync requests.
   • For New Hires, add new employees.
   • For terminations, terminate employees.
2. From Payroll > Payroll cycles, open your Payroll Connect.
3. Choose the relevant report and select the lines you want to export.
4. Click Export all records, then click Export.
5. A webhook event will be sent to your webhook listener URL provided for your app in the developer portal.
6. Receive a webhook with a syncRequestId.
7. Use the syncRequestId to pull the sync data.
   • Results are paginated. Use limit and cursor to retrieve all records.
   • Check templateId and templateName in the response to confirm which template the records follow. If you configured more than one report, test a sync for each one.
8. Process records and report per-record status
   • Use Update sync request records to report status (synced/failed).
   • Each record includes an identifier object (used to match the record when reporting status) and a data object.

     👍

     Tip: Treat vendor field names in the data object as stable identifiers. Use Get integrations metadata to discover types and list values for those keys.

Step 7: Submit your app for review to be published in the marketplace

• Before you submit, make sure every vendor field you named yourself has a human-readable name (see Step 2).

• Prepare a customer-facing user guide. For Payroll Hub, the guide must also include:

  1. Supported fields: The fields your integration supports, for each template and country.
  2. Implementation process: A few bullet points explaining how a customer from the Bob Marketplace implements your integration, and what you instruct them to do to complete the implementation. Link to Set up a payroll partner connection as a helper for the steps customers complete in Bob. It supports your customers and your implementation manager, but it doesn't replace your own onboarding, so don't send it on its own.

  HiBob's sales teams are asked these questions by prospective customers, and need your guide to answer them.

• Once your app is ready, submit it for review. After submission, HiBob runs separate listing and technical reviews. Security Review follows a separate timeline and is mandatory for Payroll and Global Payroll before go-live — you can start it as soon as you sign the Terms and Conditions. See Security Review.

• Once the required reviews are approved, your app will appear in the Bob Marketplace.

Payroll Hub Public API

A sync request represents a specific instance of data synchronization. Each sync request has a unique syncRequestId that you use to retrieve the associated report data and update sync status. Each sync request is short-lived, and must be retrieved by its expiringAt time. See Sync request expiration window for the full timing rules.

Sync request types

Webhooks

Webhooks provide real-time notifications when data syncs are triggered from HiBob to your payroll system.

Webhook types and triggers

Subscribe to these webhook types to receive notifications:

Webhook payload structure

All sync webhooks send the same payload structure:

{
  "companyId": 637323,
  "type": "payrollhub.datasync.changes",
  "triggeredBy": "3418533772247696340",
  "triggeredAt": "2024-10-03T09:29:00.831502",
  "expiringAt": "2024-10-03T09:31:00.831502",
  "version": "v2",
  "data": {
    "syncRequestId": 123456789
  }
}

Payload fields

Endpoints

Use these endpoints to retrieve report data and update sync status.

Identify the template for a sync

Every page of Get sync report data includes top-level templateId and templateName. They identify the integration template behind the connection that triggered the sync, and they have the same value on every page of a sync request.

• Use templateId to decide which field mapping to apply. It is stable, so prefer it over templateName for routing logic.
• Use templateName for logs and for messages your customers or support team see.
• Template identity is returned only on Get sync report data. The report-sync webhook includes only syncRequestId in data, so fetch the first page before you choose how to process the records.

Response data structure

Response body: 

Sync records:

Time off nested data.timeOff

For Time Off sync records, the response may include a nested timeOff object under data. It carries time-off request fields from the report (keys such as timeOffRequestId and timeTaken).

Always use identifier.timeOffRequestId (not only data.timeOff.timeOffRequestId) when calling Update sync request records, so Bob can match the same row.

Example — Time off sync

{
  "objectType": "syncRecord",
  "identifier": {
    "employeeId": "3308236326381289484",
    "effectiveDate": "2026-08-17",
    "timeOffRequestId": 987654321
  },
  "data": {
    "firstName": "John",
    "lastName": "Doe",
    "timeOff": {
      "timeOffRequestId": 987654321,
      "unit": "days",
      "endDate": "2026-08-18",
      "startDate": "2026-08-17",
      "timeTaken": 2.0,
      "approvedBy": "3840950714129974020",
      "requestedOn": "2026-08-16T09:21:39.381109"
    }
  }
}

Employee active bank account rows (data.bankAccounts)

When customers map bank account fields in Payroll Hub, Bob groups those values into a bankAccounts array under data — one object per bank account row.

Each array item includes:

• id — the bank account row ID in Bob (always present; reserved key inside each item)
• Other keys — your vendor field names from the integration template, with the value for that account

The id is included on every bank account object, in addition to the vendor fields you mapped. Only fields that have a value for a given account appear on that item (sparse objects are expected). Scalar employee fields stay at the top level of data.

Default bank account vendor field names

This catalog applies to the employee active bank account field set in Payroll Hub — the fields returned under data.bankAccounts.

When you add those columns in Payroll Hub, these are the default Vendor field names (and therefore the default keys inside each bankAccounts[] item).

Example — Changes sync with bank accounts

{
  "objectType": "syncRecord",
  "identifier": {
    "employeeId": "3830162299797110792",
    "effectiveDate": "2026-09-02"
  },
  "data": {
    "email": "[email protected]",
    "first name": "Jane",
    "last name": "Baker",
    "bankAccounts": [
      {
        "id": "403",
        "Bank account status": "Active",
        "Deposit type": "Percent",
        "Branch code": "001",
        "Bank number": "021000021",
        "Account number": "000123456785",
        "Branch address": "1 Wall Street, New York, NY",
        "Name": "Jane Baker",
        "Bank account type": "Checking",
        "Bsb": "062-000",
        "Transit number": "12345",
        "Reg nr": "004",
        "Bank identifier code": "CHASUS33",
        "Account nickname": "Payroll checking",
        "Account display name": "Checking - Payroll (6785)",
        "Roll number": "12345678",
        "Routing number": "021000021",
        "Swift": "CHASUS33",
        "Clabe": "012180001234567890",
        "Bank account in use": "In-use",
        "Iban": "GB29NWBK60161331926819",
        "Institution number": "001",
        "Use for bonus": "true",
        "Account holder name": "Jane Baker",
        "Bank name": "Chase",
        "Sort code": "60-16-13",
        "Country": "United States",
        "Deposit numeric amount": 100,
        "Priority": 1,
        "Deposit amount": {
          "value": 1000,
          "currency": "USD"
        }
      }
    ]
  }
}

How to read this structure

Vendor field names and data types

Fields are configured and mapped in Payroll Connect. The data object keys are the vendor field names you set in the integration template (Vendor field column).

Each mapped field appears in the response data object as a vendorFieldName: value pair.

If you offer more than one template, each template can use different vendor field names, and the same name can have a different type in each template. Use the response's templateId to know which set of keys to expect.

Don't assume every key in the template is present in every record. See How fields behave for customers.

Regular (custom) vendor fields

For standard fields added with +Add field, the Vendor field name you enter in Payroll Connect is the key used in the sync payload data object. You can choose any label that helps your integration, as long as it is human readable. A code alone, such as 000_P076, is not accepted; add a readable label, such as 000_P076_FirstName.

Pre-mapped table fields (Deduction, Variable pay, Entitlement, Actual payment)

Some fields are pre-mapped table columns, not regular Bob profile fields. Add them from Fields in Payroll Connect by clicking the arrow next to +Add field and selecting Add Variable pay fields, Add Deduction fields, Add Entitlement fields, or Add Actual payments fields (see Step 2 above).

Field ID format (Entitlement, Deduction, Variable pay)

For these pay-component tables, each column is sent as a separate key:

{Table name} - {Pay component type name} - {Column name}

• Table name — Entitlement, Deduction, or Variable (based on the table you added).
• Pay component type name — the configured type in Bob (for example company car, commission, lunch vouchers). This is not customizable in the payload.
• Column name — the table column (for example end date, amount, payment period). This is not customizable in the payload.

Entitlement

Deduction

Variable pay

Example — Changes sync with pre-mapped fields

{
  "objectType": "syncRecord",
  "identifier": {
    "employeeId": "3845474844414050433",
    "effectiveDate": "2026-06-11"
  },
  "data": {
    "Entitlement - company car - end date": "2026-06-12",
    "Entitlement - company car - amount": {
      "value": 1000,
      "currency": "USD"
    },
    "Entitlement - lunch vouchers - end date": "2027-03-04",
    "Entitlement - lunch vouchers - amount": {
      "value": 150,
      "currency": "GBP"
    },
    "Deduction - company car - end date": "2026-04-22",
    "Deduction - company car - amount": {
      "value": 1000,
      "currency": "USD"
    },
    "Variable - commission - amount": {
      "value": 5000,
      "currency": "USD"
    },
    "Variable - commission - payment period": "Monthly",
    "Variable - commission - company percent": 10,
    "Variable - commission - department percent": 20,
    "Variable - commission - individual percent": 70
  }
}

Only pay component types and columns included in your Payroll Connect report appear in the payload. If an employee has no value for a type, its keys may be omitted.

Actual payment fields

Actual payment works differently from Entitlement, Deduction, and Variable pay:

• Actual payment fields appear at the same level as other employee fields (for example job_title).
• For each actual payment row, Bob returns two top-level keys:
  • Actual payment - amount
  • Actual payment - pay type
• Each key holds an object keyed by the actual payment row ID (not by pay type name).

Example

{
  "data": {
    "job_title": "Designer",
    "Actual payment - amount": {
      "372": {
        "value": 1000,
        "currency": "USD"
      }
    },
    "Actual payment - pay type": {
      "372": "Bonus"
    }
  }
}

How to read this structure

If an employee has multiple actual payment rows, expect multiple entries inside each object (one entry per row ID):

"Actual payment - amount": {
  "372": { "value": 1000, "currency": "USD" },
  "401": { "value": 250, "currency": "USD" }
},
"Actual payment - pay type": {
  "372": "Bonus",
  "401": "Commission"
}

Data types: The JSON value type for each key depends on which Bob field the customer maps. Instruct your customers to map each vendor field to a Bob source field of the type your integration requires. Payroll Connect does not enforce type matching yet. To discover partner-facing types and allowed list values for your vendor field names, call Get integrations metadata.

Tile configuration: Use the Get all employee fields metadata endpoint when choosing source Bob fields in the integration template—not to discover types from sync record keys.

To see how a mapped Bob field type is represented in API payloads, refer to Field Types.

Example (data keys are vendor field names from your Payroll Connect template, such as fullName and department):

Required permissions and scopes

To use the Payroll Hub Partners API, your OAuth app requires the scopes defined in the reference guide.

Best practices

When implementing the Payroll Hub Partners API integration:

• Persist webhooks before handling them to ensure a robust and resilient solution
• Retrieve sync data immediately after receiving the webhook, before expiringAt, and don't queue the GET behind other work
• Update at least one record's status in every window to keep extending the sync request until all records are updated
• Parse responses tolerantly. Ignore unknown properties, because new objects and fields may be added during the early-access phase
• Don't assume every template field is present in every record:
  • Change reports include only fields that were actually changed for the user
  • We may allow customers to remove fields in a pay cycle in the future, so assume that some keys may not be included in the report. That's not as an error. See How fields behave for customers
• Create jobs to handle webhooks rather than processing them synchronously
• Route each sync by templateId, not only by companyId. One company can have several connections to your app, each using a different template
• Use appropriate error handling and retries for production implementations
• Cache authentication tokens according to OAuth best practices
• Respect rate limits of 5 concurrent requests
• Audit API requests and responses (HiBob does not audit this data)
• For webhook guidelines, see HiBob's webhooks guide for partners.