Skip to main content

help center

PaySuite

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

Importing pay information requests via API

Nolwenn Marjou
  • Last updated:

Importing pay information requests via API

The PaySuite solution makes it possible to import pay information requests into the system via API. This particularly useful for importing into the application, existing requests that were created in a third-party customer platform.

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, refer to the Enabling the pay information request feature section of this article.
  • You must have the payload to be uploaded on hand.

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 & configuring 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, as illustrated in the following figure:

Documents activation toggle

The feature is now enabled. You can move on the configuration page.

  1. Navigate to Workbench > Pay Transparency > Document Settings.
  2. Enable pay information requests by checking the Enable pay information requests box.
  3. Make sure that the API use is enabled by checking the API import checkbox.

This configuration makes sure that HRBPs can access the Pay information in Planner to see the list of requests, and that requests can be uploaded via API.

Preparing the payload for API ingestion

The payload for an API ingestion must be a json array containing one document per request.

A single payload can contain multiple request, as long as the size of the request does not exceed 30MB.

The following fields must be filled in for each request:

  • WorkerExternalId: external ID of the worker, as per the import of workers in the Data Foundation. Used to attribute the pay information request to the correct worker in the system.
  • RequestDate: date at which the request was placed by the worker (different from the date of the import). The date must be in ISO UTC time (YYYY-MM-DD, YYYY-MM-DDThh:mm<TZDSuffix> or YYYY-MM-DDThh:mm:ss<TZDSuffix>) and cannot be in the future.

Optionally, the following fields can also be filled in within the payload:

  • ReferenceNumber: external reference number, from a custom third-party system for instance. The reference number can contain up to 50 characters and does not have to be unique.
  • Description: description of the request. Text field that can contain up to 3,000 characters.
  • InternalNote: additional information about the pay information request. Text field that can contain up to 3,000 characters.

The following code snippet illustrates an example of the expected payload:

Copy
[
    {
      "WorkerExternalId" : "BQ1003",
      "RequestDate" : "2025-09-19T13:03:48.5832Z",
      "ReferenceNumber" : "CST123X12",
      "Description": "...",
      "InternalNote": "..."
    },
        {
      "WorkerExternalId" : "BQ1008",
      "RequestDate" : "2026-01-22T17:46:12.4511Z",
      "ReferenceNumber" : "CST123Y38",
      "Description": "...",
      "InternalNote": "..."
    },
    ...
]

This is an attention message.

It is not possible to import, for a single worker, multiple requests created at the same time. Validation of this constraint is performed within individual payloads as well as across already existing requests. In case of conflict, the relevant requests will be ignored, but other valid requests in the payload will be successfully processed.

Importing requests

To start using the API to import pay information requests, you need to call the following endpoint: POST integrationapi/v1/pay-information-requests with your payload.

The system processes the requests and validated, in order that:

  • No conflicts exists within the requests in the payload

  • The fields are valid (length and references to other data)

  • Each request is unique (i.e. no other request for the same worker at the same date exists in the application)

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

Copy
{
  "HasErrors": true/false
  "Summary":
  {
    "Total": 5,
    "Success": 1,
    "Failed": 3,
    "Conflict": 1
  },
  "Results":
  [
      {
        "WorkerExternalId" : "BQ1003",
        "RequestDate" : "2025-09-19T13:03:48.5832Z"
        "ReferenceNumber" : "CST123X12",
        "RequestId": "BQM0000DF"
        "ImportDate": "2025-09-24T18:00:21.0086Z",
        "Result" : "Success/Conflict/Failed",
        "Errors" : [
          {
            "FieldName" : "string",
            "ErrorMessage": "string"
          },
          ...
        ]
      },
      ...
  ]
}

Where:

  • HasErrors: indicates if all requests were successfully imported. This field can be used to detect if any errors occurred, even if the response contained 200 ok. For more information, refer to the Error responses section.

  • Summary: displays counters for:

    • Total: number of requests received (i.e. sum of the Success, Failed and Conflict counters).

    • Success: number of requests successfully imported.

    • Failed: number of requests that could not be imported due to errors in the data.

    • Conflict: number of requests that could not be imported due to the presence of another request for the same worker, either in the platform or in the payload.

  • Results: array of import results containing as many items as the Total counter of the Summary section. For each request, the response includes:

    • Original WorkerExternalId and RequestTime

    • Original ReferenceNumber, if provided in the payload

    • RequestId: unique identifier generated by the application to be later able to query the status of the request and get its attached document. This ID is also visible in the application UI.

    • ImportDate: date and time at which the request was stored into the platform and assigned an ID (RequestId).

    • Result: result of the import. Possible values are: Success (the request was valid, unique and was stored in the application), Failure (at least one of the fields in the request did not pass validation) or Conflict (a request already exists for the same worker at the same time).

  • Errors: array of FieldName/ErrorMessage pairs. Contains information only if the status of the result is Failure. Possible errors are:

    • WorkerExternalId: worker ID was provided in the payload, but is not found in the application

    • RequestTime: provided in a valid format but is set in the future

    • One of the fields ReferenceNumber, Description or InternalNote is too long.

  • In case of conflict:

    • If the conflict is against a request that was previously imported or created in the system, the field RequestId is included in the response and provides the ID of the request that already exists in the application. The conflicting request included in the payload is ignored.

    • If the conflict is between duplicated requests within the payload, the result of both requests will be set to Conflict but reported without request ID, and neither is stored in the application.

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": "00-86161ed2ae20c645c3a46535ee2e538e-3e3d23024e1111cb-01"
}

  • 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": "00-3b81f57653ca2b10bbafc5a1289e8a38-aa92dcc37cd7e178-01"
}

  • 422 UnprocessableContent: means that the pay information request feature is not enabled in the tenant. The response body for this error is as follows:

Copy
{
    "type": "https://httpstatuses.io/422",
    "title": "One or more validation errors occurred.",
    "status": 422,
    "errors": {
        "PayInformationRequestDisabled": [
            "PayInformationRequest is disabled"
        ]
    },
    "traceId": "00-1290264074c29690aea3744e50fbc756-4910628d1b86f94c-01"
}

  • 400 BadRequest: means that at least one of the requests in the payload either misses a mandatory field or contains an invalid format for the RequestDate (ISO UTC format). The response body for this error is as follows:

Copy
{
  "type" : "https://httpstatuses.io/400",
  "title" : "Bad Request",
  "status" : 400,
  "detail" : "One or more validation errors occurred.",
  "errors" : [
    "The requests field is required.",
    "JSON deserialization for type 'bqm.Contracts.Inbox.PayInformationRequests.ImportPayInformationRequest' was missing required properties, including the following: workerExternalId, requestDate"
  ],
  "traceId" : "0HNFS8BHEQCOL:00000002"
}

This is an attention message.

Unlike conflicts of data, if the 400 BadRequest error is due to missing mandatory fields, none of the requests present in the payload will be uploaded, even if they are valid. Data processing is done on all requests (if valid) or none of them.

Was this article helpful?
0 out of 0 found this helpful
Return to top