Skip to main content

help center

PaySuite

Submit a request
  1. beqom PaySuite HelpCenter
  2. APIs
  3. Functional APIs

Retrieving pay information requests via API

Nolwenn Marjou
  • Last updated:

Retrieving pay information requests via API

The PaySuite solution makes it possible to retrieve pay information requests via API.

Prerequisites

Before you can start a pay information upload, the following prerequisites must be fulfilled

  • You must have the required credentials to call the API. For more information, refer to the Authentication section of this document.
  • The pay information request feature must be enabled in the platform. For more information about the enablement of the feature, refer to Retrieving pay information requests via API.

Authentication

The pay information request API is secured using OAuth 2.0 and protected by an access token. To obtain your token and connect to the API, you need to call the /connect/token endpoint with 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 the beqom Support.

  • scope: constant value payinformationapi.

Enabling the pay information request feature

Before you can start using the API, you must make sure that the feature is enabled 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.
  3. In the list of features, toggle on the Documents feature. The feature is now enabled.

Retrieving a single pay information request

To retrieve a single pay information, you need to call the following endpoint: GET integrationapi/v1/pay-information-requests/{requestId}

This is a tip message.

You can use the bulk retrieval endpoint, with or without filters, to obtain a list pay information requests from the system. For more information, refer to the section Retrieving pay information requests in bulk.

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

Copy
{
  "requestId": "string",
  "referenceNumber": "string | null",
  "workerExternalId": "string",
  "workerFirstName": "string",
  "workerLastName": "string",
  "requestDate": "string",
  "creationType": 0,
  "status": 0,
  "description": "string | null",
  "responseToWorker": "string | null",
  "internalNote": "string | null",
  "alert": 0,
  "resolutionDate": "string | null",
  "communicationRoundCode": "string | null",
  "communicationRoundName": "string | null",
  "hasDocumentAttached": true
}

Where:

  • requestId: unique ID of the pay information, retrieved from the system.

  • referenceNumber: external reference number of the request, if any.

  • workerExternalId: external ID of the worker, as per the import of workers in the Data Foundation. Used to match each request to a given worker in the system.

  • workerFirstName: first name of the worker, as per the import of workers in the Data Foundation.

  • requestDate: date at which the request was placed. Corresponds to the RequestDate field if you imported pay information requests using the API (for more information refer to Importing pay information requests via API).

  • creationType: method used to create the request; either from the platform UI or the API. Possible values are:

    • 0: API

    • 1: Worker

    • 2: HRBP

  • status: status of the pay information request in the platform. Corresponds to the Status field in the application UI (in the list of the pay information requests, under Planner > Pay Information). Possible values are:

    • 0: New

    • 1: In progress

    • 2: Closed

  • description: description of the pay information request. Corresponds to the Description field in the application UI and in the pay information payload if the request was created via API.

  • responseToWorker: indicates what response has been given to the worker. Corresponds to the Response to worker field in the application UI, in which the HRBP can type in information regarding the pay situation of the worker.

  • internalNote: returns any internal note (i.e. note not visible to the worker) entered in the system by the HR team. Corresponds to the Internal note field in the application UI.

  • alert: indicates whether an alert is associated with the pay information request. Corresponds to the Alert field in the application UI. Possible values are:

    • -1: None

    • 0: Approaching deadline

    • 1: Overdue

    • 2: Closed without document

    • 3: Not released to worker

    • 4: Document deleted

  • resolutionDate: data at which the pay information request was resolved, if its status is Closed in the application UI.

  • communicationRoundCode: code of the communication round to which the pay information request is attached.

  • communicationRoundName: code of the communication round to which the pay information request is attached.

  • hasDocumentAttached: indicates whether a document is attached to the pay information request. Possible values are true (yes) and false (no).

Error responses

  • 401 Unauthorized: means that the access token is either missing or expired. The response body for this error is as follows:

Copy
{
  "type": "https://httpstatuses.io/401",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "..."
}

  • 403 Forbidden: means that the token does not have the right scope (payinformationapi). The response body for this error is as follows:

Copy
{
  "type": "https://httpstatuses.io/403",
  "title": "Forbidden",
  "status": 403,
  "traceId": "..."
}

  • 404 Not Found: means that the request ID entered in the API call is incorrect.

Copy
{
  "type": "https://httpstatuses.io/404",
  "title": "Not Found",
  "status": 404,
  "detail": "PayInformationRequest not found",
  "traceId": "..."
}

Retrieving pay information requests in bulk

To retrieve a paginated list of pay information requests, with optional filters, call the following API endpoint: GET /integrationapi/v1/pay-information-requests?[queries].

Request body sample:

Copy
curl -X GET "https://api.dev.accelerate.bqm-weu-aks-imp-1.beqom.dev/integrationapi/v1/pay-information-requests?\
requestId=REQ-001&\
requestId=REQ-002&\
referenceNumber=REF-123&\
referenceNumber=REF-456&\
workerExternalId=EMP001&\
workerExternalId=EMP002&\
status=1&\
alert=0&\
requestDateFrom=2024-01-01&\
requestDateTo=2024-12-31&\
resolutionDateFrom=2024-06-01&\
resolutionDateTo=2024-06-30&\
page=1&\
size=20" \
  -H "Authorization: Bearer {token}"

Parameters:

  • requestId: use this field to filter the response by one or multiple pay information request IDs. For instance, requestId=REQ-001&requestId=REQ-002

  • referenceNumber: use this field to filter the response by one or multiple reference numbers. For example: referenceNumber=REF-123&referenceNumber=REF-456

  • workerExternalId: use this field to filter the response by one or multiple worker IDs. For example: EMP001, EMP002

  • status: use this field to filter the response by status code. Example: 1 for "In progress"

  • alert: use this field to filter the response by alert code. Example: 0 for "Approaching deadline"

  • requestDateFrom / requestDateTo: get the pay information requests created within the specified date range

  • page: page number for the pagination. Default = 1.

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

Header:

  • Authorization: Bearer {token}: Replace the variable{token} with your valid OAuth2.0 bearer token to authenticate to use the API.

For valid calls, the system will return a response similar to the following:

Copy
{
  "items": [
    {
      "requestId": "REQ-001",
      "referenceNumber": "REF-123",
      "workerExternalId": "EMP001",
      "workerFirstName": "John",
      "workerLastName": "Doe",
      "requestDate": "2024-06-10",
      "creationType": 0,
      "status": 1,
      "description": "Request for pay slip",
      "responseToWorker": null,
      "internalNote": null,
      "alert": 0,
      "resolutionDate": "2024-06-15",
      "communicationRoundCode": null,
      "communicationRoundName": null,
      "hasDocumentAttached": true
    }
    // ... more items
  ],
  "currentPage": 1,
  "pageCount": 5,
  "pageSize": 20,
  "rowCount": 100
}

Error responses

  • 401 Unauthorized: means that the access token is either missing or expired. The response body for this error is as follows:

Copy
{
  "type": "https://httpstatuses.io/401",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "..."
}

  • 403 Forbidden: means that the token does not have the right scope (payinformationapi). The response body for this error is as follows:

Copy
{
  "type": "https://httpstatuses.io/403",
  "title": "Forbidden",
  "status": 403,
  "traceId": "..."
}

Downloading the PDF attached to a pay information request

To download the PDF document attached to a pay information request, call the following API endpoint: GET /integrationapi/v1/pay-information-requests/{requestId}/document].

The following rules apply to downloading the documents:

  • The document is returned only if a document exists for the request.

  • The document is only retrieved is the request is in Closed status.

  • The response is a PDF in binary stream.

  • If no document exists for the request, a 404 error is returned.

  • If the pay information request is not closed, the system returns 422 Unprocessable Entity.

If the request is valid and passes, the system returns 200 OK and returns the document as a binary file content: Content-Type: application/pdf

Error responses

  • 401 Unauthorized: means that the access token is either missing or expired. The response body for this error is as follows:

Copy
{
  "type": "https://httpstatuses.io/401",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "..."
}

  • 403 Forbidden: means that the token does not have the right scope (payinformationapi). The response body for this error is as follows:

Copy
{
  "type": "https://httpstatuses.io/403",
  "title": "Forbidden",
  "status": 403,
  "traceId": "..."
}

  • 404 Not found: means that the request ID entered in the API call is incorrect.

Copy
{
  "type": "https://httpstatuses.io/404",
  "title": "Not Found",
  "status": 404,
  "detail": "PayInformationRequest not found or no document attached",
  "traceId": "..."
}

  • 422 Unprocessable Entity: means that the pay information request is not in the right status (Closed)

Copy
{
  "type": "https://httpstatuses.io/422",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Request is not closed",
  "traceId": "..."
}
Was this article helpful?
0 out of 0 found this helpful
Return to top