Overview

The Bob Reports API enables seamless access to reporting data, providing tools to retrieve, download, and automate reports for HR insights, compliance, and analytics. Whether you want to fetch predefined reports, customize data outputs, or integrate with analytics tools, the Reports API is designed to support your business needs.

To learn more about configuring reports in Bob, see Getting started with reports ↗.

Key concepts

Reports and Report IDs

Reports are structured data sets available within Bob. Each report has a unique identifier (reportId) used to fetch specific details or download data. Use the ‘Get Company Reports’ endpoint to list all available reports and their properties, such as name, creation date, and description.

File Formats

Reports can be exported in various formats, including CSV, XLSX, and JSON. The format can be specified when requesting a report download, providing flexibility for integrating other tools.

JSON-format reports are designed for programmatic processing and provide a format similar to the API’s payload. To get the values as they appear in the UI, the JSON format usually requires using the humanReadable flag when calling the endpoints. To learn more, see Fields and lists metadata.

Permissions

Access to reports is managed by the permissions granted to the service user. Ensure that the service user accessing the API has the appropriate rights to view or download specific reports.
The service user may require both Feature permissions and People’s data permissions. To learn more, see Reports API reference.

File location

When generating a new report via the API, an asynchronous process is triggered, and the file location is provided as a URL in the response’s HTTP header. This URL contains a download link, but only the file name at the end of the URL should be passed for downloading via the API.
For example: https://app.hibob.com/v1/company/reports/download/2022-06-17T11_22_14.798810-test.JsonFormat
The file location for download is only “2022-06-17T11_22_14.798810-test.JsonFormat”

📘

Note:

Note: For existing reports, no file location is required.

Report endpoints

Reports endpoints let you retrieve and generate reports:

To learn more, see Reports endpoints.

Common use-cases

Downloading a report by ID

Downloading reports via the API is useful when you need to extract filtered data and apply dynamic conditions while exporting information to a third-party system.

For example, suppose you want to retrieve a specific group of employees who changed their manager in the last month. You can configure the report easily in Bob's UI and then fetch it by its ID in CSV, XLSX, or JSON format without specifying any additional conditions or filters. This approach allows you to access advanced and sophisticated data effortlessly, which can then be parsed and pushed to the third-party system.

1. Download a specific report using the GET /company/reports/{reportId}/download endpoint.
2. Specify the desired format (csv, xlsx, or json) in the query parameters.

Example:
GET /company/reports/12345/download?format=csv

To learn more about configuring reports in Bob, see Getting started with reports ↗.

Listing available reports

To identify the reports available for your organization, use the GET /company/reports endpoint. This provides a list of reports, including their names, descriptions, and IDs.

Example:

{  
  "views": [  
    {  
      "id": 12345,  
      "name": "Employee Overview",  
      "description": "Detailed employee information",  
      "createdBy": "[email protected]",  
      "creationDate": "2023-01-01"  
    }  
  ]  
}

Asynchronous report generation

Use async generation to schedule periodic report creation via the API.

1. Start the report generation by ID: GET /company/reports/12345/download-async?format=xlsx
2. This triggers asynchronous generation and returns a location URL for downloading the report.
3. Download the report when ready using the GET /company/reports/download/{reportName} endpoint.

Integration with storage integrations

You can send scheduled automated reports to a storage system destination. The Schedule reports feature allows you to set any report to automatically run and be sent to colleagues or external parties via email or to an integrated SFTP or S3 server.

Setting up storage destination enables sending report data from Bob to SFTP servers. You can create as many SFTP destinations as you need for your organization’s needs.

This way, you can leverage the Reports API to feed HR data into business intelligence (BI) platforms or compliance systems. Automate this integration by scheduling report downloads and transferring files via SFTP or APIs.

To learn more, see Mastering APIs and custom integrations.

Related resources

• Mastering reports
• Scheduled reports.
• Getting started with Bob API.
• Rate limiting.