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 list, inspect, and export all documents produced for a communication round 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. 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 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 Rount",
    "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, 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. You can combine it with the following optional filters to narrow down the results:

• documentId: filter by a specific document ID.

• workerExternalId: filter by the external ID of a specific worker.

• releaseState: filter by release state; see the Release states table below.

• workflowStep: filter by workflow step; 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.

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.