Importing documents via API

In the Pay Suite application, you can store large quantities of documents, both historical and current. These documents may be imported into the application via API. This solution allows for a better control over the documentation that is shared with the workers in the organization.

This is a tip message.

You can also use the SFTP upload to import your documents. For more information about this method refer to Importing documents through SFTP upload.

Prerequisites

Before you can start the upload of documents within the platform, there are two prerequisites that you must fulfill.

Firstly, you must first enable the Documents feature in the platform. This step is crucial; without it your reviewers will not be able to see the documents in their team planner and your workers won't receive their documents. To enable the feature, navigate to the Workbench > Platform Setup > Feature Enablement > Inbox and switch the toggle to enabled (blue).

This is a tip message.

Access to Workbench depends on your role within the platform.

Activating the Documents feature will:

• Enable the import of documents.

• Give access to the creation of communication rounds in Workbench.

• Give access to team documents in Planner.

Secondly, you must create at least one communication round to which the documents will be linked. This round can be in the past and used to mass-import historical documents. This step is mandatory because a reference to the round is mandatory in the HTTP request of the API call.

This is a tip message.

For more details about the creation of the communication round, refer to Creating a communication round.

Once the communication round is created, in the Communication round details section check if the status is marked as Open or In Progress, and write down the Code of the communication round. You will need unique code in the next steps of the import. These two pieces of information are highlighted in the following figure:

Communication round details

Obtaining the access token to use the API

The outbound API endpoints are secured using OAuth 2.0, and are protected by an access token. To obtain an access token, you need to call the /connect/token endpoint with your unique client credentials, as illustrated in the following figure:

API authentication call

Where:

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

• grant_type constant value client_credentials.

• client_secret client secret; for more information, contact beqom..

• scope constant value import_inbox.

This is a tip message.

To obtain your API connection information and obtain your token, get in touch with our Support team.

Identifying the worker

Is possible to upload one document per worker per time. The worker must be identified by their personal worker id, that you can find under Workbench > Data management > Workers & roles > Worker details > Worker ID, as illustrated in the following picture:

Worker ID

This is a tip message.

Access to Workbench depends on your role within the organization.

Importing the documents

This is an note/information message.

The following explanation uses a beqom development environment in Postman as example. To use this on your side, replace dev.accelerate.bqm-weu-aks-imp-1.beqom.dev with the URL of your own environment.

To import a document, choose the Authorization header and set the bearer token, as illustrated in the following figure

Setting the token

Then in the Body header, choose form-data with credentials, as the following figure illustrates:

API import call

Where:

• workerexternalId: id of the worker who is the subject of the imported document.

• communicationRoundCode: unique code of the communication round.

• isSummary set to false.

• generationTime the chosen date must be a past date.

• file:file with a name referencing a file existing locally.

The API endpoints return results in a paginated model. The response contains the following fields:

• documentId: an internal reference of the document in the database

• overridden: status will be false for new documents or true if there was already an existing document with the same name that was overridden.

• importTime: the time when the import occurred.