Exporting documents from a communication round via API

Pay Transparency Communication Rounds generate PDF documents for your workforce, including right to information documents, performance statements, and compensation letters. Many customer organizations chose to extract the documents to be stored outside beqom PaySuite, for example, in a record management system or an archive used for audit purposes. Our API lets you retrieve these documents programmatically, so you can find the communication round, list, inspect, and export all documents produced for it as part of a script or an integration.

Prerequisites

Before you start, make sure you fulfill the following prerequisites:

• You must be able to authenticate to the Integration API, as described in the Authentication section of this article. This API is separate from beqom's web application, which relies on an individual user's login session instead.

• The Documents feature must be enabled in the platform. See Enabling the Documents feature for details.

• You must have the unique code of the communication round whose documents you want to export. You can retrieve it through the Integration API or find it in the application. Learn more in Finding the code of a communication round below.

Authentication

The Integration API uses OAuth 2.0 and is protected by an access token. To obtain your token, call the /connect/token endpoint with your client credentials:

POST https://authentication.dev.accelerate.bqm-weu-aks-imp-1.beqom.dev/connect/token

This is illustrated in the following figure:

API authentication call

Where:

• grant_type: constant value client_credentials.

• client_id: ID of the client for which the token is requested; corresponds to your ClientName or CompanyName.

• client_secret: your client secret. Contact beqom Support for more information.

• scope: constant value documentsapi.

Error responses

• 422 Unprocessable Content: the Documents feature is not enabled for your tenant.

Enabling the Documents feature

Before you can use the Integration API, you must enable the Documents feature in the platform. To do so, proceed as follows:

1. Log into the platform with a user to whom the Configuration role has been granted.

2. Navigate to Workbench > Platform Setup > Feature Enablement, as you can see below:

   

   Feature Enablement page

3. In the list of features, toggle on the Documents feature. The feature is now enabled.

Finding the code of a communication round

Every export starts with the code of the communication round you want to retrieve documents from. You can obtain it in one of two ways.

From the Integration API

You can retrieve the list of published communication rounds, including their codes, with the same access token you use for the document endpoints. Call the following endpoint:

GET https://api.dev.accelerate.bqm-weu-aks-imp-1.beqom.dev/integrationapi/v1/communication-rounds

By default, the endpoint returns all communication rounds that are In progress, Open, or Closed, sorted by creation date, newest first. Draft and archived communication rounds are never returned, whether or not you apply a filter.

To narrow down the results, use the optional state query parameter. You can repeat it to combine several states:

Communication round states

For example, to list only rounds that are open or closed:

curl -X GET "https://api.dev.accelerate.bqm-weu-aks-imp-1.beqom.dev/integrationapi/v1/communication-rounds?state=1&state=2" \
  -H "Authorization: Bearer {token}"

On success, the system returns 200 OK, with the list of communication rounds:

[
  {
    "id": 4,
    "name": "Pay statements 2025",
    "state": 1,
    "code": "123456",
    "hasSummary": false,
    "isOwner": false,
    "owners": [
      {
        "id": "3f2b...",
        "fullName": "Jane Smith",
        "photoId": null,
        "jobTitle": "HR Director",
        "employeeId": "EMP-100"
      }
    ],
    "workflowConfiguration": {
      "enableWorkflowSteps": true,
      "enableHrbpReview": true,
      "enableHierarchyValidation": true,
      "permission": {
        "allowHrbpToRelease": true,
        "allowCommunicationManagerToRelease": true,
        "allowHrbpToUnrelease": true,
        "allowCommunicationManagerToUnrelease": true
      }
    },
    "startDate": "2025-03-01T00:00:00",
    "endDate": "2025-12-31T00:00:00",
    "creationDate": "2025-02-15T09:30:00"
  }
]

Where:

• id: internal ID of the communication round.

• name: name of the communication round.

• state: state of the communication round (see the Communication round states table above).

• code: unique code of the communication round. Use this value as communicationRoundCode in the calls described below. If code is null, the round has no code assigned and its documents cannot be listed through the Integration API.

• hasSummary: indicates whether the round includes summary documents.

• isOwner: always false for Integration API calls, since the request is not made on behalf of a user.

• owners: owners of the communication round.

• workflowConfiguration: workflow steps enabled for the round and the roles allowed to release and unrelease documents.

• startDate / endDate: visibility start and end dates of the round.

• creationDate: date on which the round was created.

Error responses

• 400 Bad Request: the state parameter contains an unsupported value. Only 0, 1, and 2 are accepted.

• 401 Unauthorized: the access token is missing or has expired.

• 403 Forbidden: the access token does not include the documentsapi scope.

• 422 Unprocessable Content: the Documents feature is not enabled for your tenant.

From the application

If you know the name of the round, log in to the application and navigate to Workbench > Pay Transparency > Documents > Communication Rounds. The round's code is visible in the Code column in the list of communication rounds, as presented in this image:

Communication round codes listed on the Communication Rounds page

From the Gateway API (web-app-facing API)

The communication round code can also be retrieved through beqom's web application API.

This is an note/information message.

Note that this is a separate API from the Integration API described in this article. It requires an authenticated user session rather than the client credentials specified in the Authentication section.

Users with permission to access communication rounds in Workbench (for instance, CompensationAdmin, GlobalCompensationAdmin, or Support) can call the following endpoint:

GET https://api.dev.accelerate.bqm-weu-aks-imp-1.beqom.dev/api/inbox/communication-rounds

The following code snippet shows a sample response from the API call:

[
  {
    "Id": 4,                      
    "Name": "My Test Round",
    "State": 1,
    "Code": "123456",
    "HasSummary": false,
    "IsOwner": true,
    "Owners": [ ... ],
    ...
  },
  ...
]

Use the value of the Code field in the calls described below.

Retrieving the list of documents in a communication round

To export all the documents associated with a communication round, start by retrieving the list of documents for that round. With the access token obtained above and the code of the communication round, call the following endpoint:

GET https://api.dev.accelerate.bqm-weu-aks-imp-1.beqom.dev/integrationapi/v1/documents?communicationRoundCode=XXX

The communicationRoundCode query parameter is mandatory; use the code value returned by the communication-rounds endpoint. You can combine it with the following optional filters to narrow down the results:

• documentId: filter by a specific document ID; repeat the parameter to filter by several document IDs..

• workerExternalId: filter by the external ID of a specific worker; repeat the parameter to filter by several workers.

• releaseState: filter by release state; repeat the parameter to include several release states; see the Release states table below.

• workflowStep: filter by workflow step; repeat the parameter to include several workflow steps; see the Workflow steps table below.

• isSummary: true or false, to filter summary documents in or out.

• generationDateFrom / generationDateTo: filter by the date range in which the documents were generated.

• page: page number for the results. Default is 1.

• size: number of items per page. Default is 20.

To filter by several values of the same parameter, repeat it in the query string, for example releaseState=0&releaseState=1.

The following example combines several of these filters in a single call:

curl -X GET "https://api.dev.accelerate.bqm-weu-aks-imp-1.beqom.dev/integrationapi/v1/documents?\
communicationRoundCode=123456&\
workerExternalId=EMP-001&\
releaseState=1&\
page=1&\
size=20" \
  -H "Authorization: Bearer {token}"

On success, the system returns 200 OK, with a paginated list of documents:

{
  "items": [
    {
      "documentId": 12345,
      "workerExternalId": "EMP-001",
      "workerFirstname": "John",
      "workerLastname": "Doe",
      "documentName": "Pay_Statement_2024_Q1.pdf",
      "releaseState": 1,
      "workflowStep": 2,
      "isSummary": false,
      "generationDate": "2024-03-15"
    }
  ],
  "currentPage": 1,
  "pageCount": 5,
  "pageSize": 20,
  "rowCount": 100
}

Where:

• documentId: unique ID of the document, to be used in the endpoints described below.

• workerExternalId: external ID of the worker the document belongs to, as per the import of workers in the Data Foundation.

• workerFirstname / workerLastname: name of the worker the document belongs to.

• documentName: original file name of the document.

• releaseState: release state of the document (see Release states above).

• workflowStep: workflow step the document is at (see Workflow steps above).

• isSummary: indicates whether the document is a summary document.

• generationDate: date on which the document was generated.

• currentPage, pageCount, pageSize, rowCount: pagination details for the response.

Error responses

• 400 Bad Request: the mandatory communicationRoundCode query parameter was not provided.

• 401 Unauthorized: the access token is missing or has expired.

Retrieving the details of a single document

If you already know the ID of a document, because, for instance, you retrieved it from the list above or from another integration, you can retrieve its details individually. Call the following endpoint:

GET https://api.dev.accelerate.bqm-weu-aks-imp-1.beqom.dev/integrationapi/v1/documents/{id}

On success, the system returns 200 OK, with the same set of fields described in the previous section, for a single document:

{
  "documentId": 12345,
  "workerExternalId": "EMP-001",
  "workerFirstname": "John",
  "workerLastname": "Doe",
  "documentName": "Pay_Statement_2024_Q1.pdf",
  "releaseState": 1,
  "workflowStep": 2,
  "isSummary": false,
  "generationDate": "2024-03-15"
}

Error responses

• 401 Unauthorized: the access token is missing or has expired.

• 404 Not Found: no document exists with the given ID.

Downloading a document

Once you have identified the document you want to retrieve, download the file itself. Call the following endpoint:

GET https://api.dev.accelerate.bqm-weu-aks-imp-1.beqom.dev/integrationapi/v1/documents/{id}/document

If the request is valid, the system returns 200 OK, with the document served as binary content under its original file name:

For example, the response headers for a document named Pay_Statement_2024_Q1.pdf would look like this:

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="Pay_Statement_2024_Q1.pdf"
Content-Length: 125432

Treat the response as a file download rather than a JSON payload. The Content-Disposition header carries the original file name from the document's metadata, and the body is the raw PDF itself.

Error responses

• 401 Unauthorized: the access token is missing or has expired.

• 404 Not Found: no document exists with the given ID.