Skip to main content

help center

Pay Suite

Submit a request
Submit a request
  1. beqom PaySuite HelpCenter
  2. Technical admin
  3. Data foundation

Uploading data into the data foundation via API

Nolwenn Marjou
  • Last updated:

Uploading data into the data foundation via API

This is an note/information message.

This article focuses on the injection of data into the Pay Suite data foundation using the data ingestion API. To upload CSV files via SFTP, refer to Uploading data into the data foundation via SFTP. To upload files via the UI, refer to Uploading data into the data foundation.

In addition to the upload of .csv files for the entities and enums that make up the Pay Suite data foundation, beqom also offers an API that can be used to inject the data into the system and start configuring the platform.

This is a tip message.

For more information about the data foundation and the upload of .csv files, refer to the following articles:

This API, called the Integration API, has a number of endpoints that correspond to each entity and enum present in the data foundation.

This article details the use of the Pay Suite Integration API and its endpoints.

Authenticating 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 must 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 integrationapi.

This is a tip message.

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

API Endpoints

Two types of endpoints are used during the ingestion process via the Integration API:

  • An endpoint used to pass the data, with the data type, to the application. For more information, refer to Data transmission endpoint.

  • The second endpoint is used to track the status of the ingestion; when called, it will return different values based on the current status of the process. For more information, refer to Ingestion status endpoint.

Data transmission endpoints

The syntax of the data transmission endpoints is setup as follows:

POST integrationapi/v1/data-foundation/ingestion/{data type name}

where {data type name} corresponds to the entity or enum into which you want to inject data.

Considering this, the endpoints listed in the table below are available.

This is a warning message.

The data type names in the endpoints are case-sensitive. Using the incorrect case will result in a failure of the ingestion attempt. Make sure you respect the case outlined in the table below.

Data injection endpoint methods
Method Description
POST integrationapi/v1/data-foundation/ingestion/Worker Used to inject data into the Worker entity.
POST integrationapi/v1/data-foundation/ingestion/Employment Used to inject data into the Employment entity.
POST integrationapi/v1/data-foundation/ingestion/Absence Used to inject data into the Absence entity.
POST integrationapi/v1/data-foundation/ingestion/Demographics Used to inject data into the Demographics entity.
POST integrationapi/v1/data-foundation/ingestion/CompensationHistory Used to inject data into the CompensationHistory entity.
POST integrationapi/v1/data-foundation/ingestion/CompensationElement Used to inject data into the CompensationElement entity.
POST integrationapi/v1/data-foundation/ingestion/JobArchitecture Used to inject data into the JobArchitecture entity.
POST integrationapi/v1/data-foundation/ingestion/Organization Used to inject data into the Organization entity.
POST integrationapi/v1/data-foundation/ingestion/LegalEntity Used to inject data into the LegalEntity entity.
POST integrationapi/v1/data-foundation/ingestion/CostCenter Used to inject data into the CostCenter entity.
POST integrationapi/v1/data-foundation/ingestion/PayScale Used to inject data into the PayScale entity.
POST integrationapi/v1/data-foundation/ingestion/IndividualPayRange Used to inject data into the IndividualPayRange entity.
POST integrationapi/v1/data-foundation/ingestion/PerformanceRatingScales Used to inject data into the PerformanceRatingScales entity.
POST integrationapi/v1/data-foundation/ingestion/PerformanceReviewRating Used to inject data into the PerformanceReviewRating entity.
POST integrationapi/v1/data-foundation/ingestion/GoalsAchievement Used to inject data into the GoalsAchievement entity.
POST integrationapi/v1/data-foundation/ingestion/EmploymentStatus Used to inject data into the EmploymentStatus enum.
POST integrationapi/v1/data-foundation/ingestion/CompensationElementFrequency Used to inject data into the CompensationElementFrequency enum.

POSTintegrationapi/v1/data-foundation/ingestion/CompensationElementType

 Used to inject data into the CompensationElementType enum.
POST integrationapi/v1/data-foundation/ingestion/PerformanceRatingType Used to inject data into the PerformanceRatingType enum.
POST integrationapi/v1/data-foundation/ingestion/PerformanceReviewType Used to inject data into the PerformanceReviewType enum.
POST integrationapi/v1/data-foundation/ingestion/Proficiency Used to inject data into the Proficiency enum.
POST integrationapi/v1/data-foundation/ingestion/ContractType Used to inject data into the ContractType enum.
POST integrationapi/v1/data-foundation/ingestion/Gender Used to inject data into the Gender enum.
POST integrationapi/v1/data-foundation/ingestion/MaritalStatus Used to inject data into the MaritalStatus enum.
POST integrationapi/v1/data-foundation/ingestion/Religion Used to inject data into the Religion enum.
POST integrationapi/v1/data-foundation/ingestion/PoliticalAffiliation Used to inject data into the PoliticalAffiliation enum.
POST integrationapi/v1/data-foundation/ingestion/EducationLevel Used to inject data into the EducationLevel enum.
POST integrationapi/v1/data-foundation/ingestion/Ethnicity Used to inject data into the Ethnicity enum.
POST integrationapi/v1/data-foundation/ingestion/Nationality Used to inject data into the Nationality enum.
POST integrationapi/v1/data-foundation/ingestion/PayScaleType Used to inject data into the PayScaleType enum.
POST integrationapi/v1/data-foundation/ingestion/PayScaleArea Used to inject data into the PayScaleArea enum.
POST integrationapi/v1/data-foundation/ingestion/PayScaleGroup Used to inject data into the PayScaleGroup enum.
POST integrationapi/v1/data-foundation/ingestion/PayScaleLevel Used to inject data into the PayScaleLevel enum.
POST integrationapi/v1/data-foundation/ingestion/PayScaleLocalGrade Used to inject data into the PayScaleLocalGrade enum.
POST integrationapi/v1/data-foundation/ingestion/PayScaleGlobalGrade Used to inject data into the PayScaleGlobalGrade enum.
POST integrationapi/v1/data-foundation/ingestion/PayGrade Used to inject data into the PayGrade enum.
POST integrationapi/v1/data-foundation/ingestion/JobFamily Used to inject data into the JobFamily enum.
POST integrationapi/v1/data-foundation/ingestion/JobFunction Used to inject data into the JobFunction enum.
POST integrationapi/v1/data-foundation/ingestion/JobCategory Used to inject data into the JobCategory enum.
POST integrationapi/v1/data-foundation/ingestion/JobLevel Used to inject data into the JobLevel enum.
POST integrationapi/v1/data-foundation/ingestion/AbsenceType Used to inject data into the AbsenceType enum.
POST integrationapi/v1/data-foundation/ingestion/PerformanceRatingScale Used to inject data into the PerformanceRatingScale enum.
POST integrationapi/v1/data-foundation/ingestion/GoalPlan Used to inject data into the GoalPlan enum.
POST integrationapi/v1/data-foundation/ingestion/GoalPlanGroup Used to inject data into the GoalPlanGroup enum.

The following table details the structure of a call to the data ingestion API:

Method Endpoint Request body Response
POST integrationapi/v1/data-foundation/ingestion/{data type name}
Copy
[
 {
   "field1":String,
   "field2":Numeric
 }
]

Before doing any data validation or commit to the database, the system will return a 202 ACCEPTED response, with the following response body:

Copy
{
    "ExecutionId": GUID,
    "Status": "Accepted"
}

 
POST v1/api/data-foundation/ingestion/{data type name}/incremental
Copy
[
 {
   "field1":String,
   "field2":Numeric
 }
]

Before doing any data validation or commit to the database, the system will return a 202 ACCEPTED response, with the following response body:

Copy
{
    "ExecutionId": GUID,
    "Status": "Accepted"
}

JSON body structure

The body of a call to the data ingestion API is a JSON array containing one or more JSON nodes. To be accepted by the system, each JSON node must contain the required properties for the targeted entity or enum.

This is an note/information message.

For more information about required field in each entity or enum, refer respectively to Data foundation entities and Data foundation enums.

For optional fields in any given entity or enum, it is possible to put a null value or to omit the property from the JSON body. However, keep in mind that a null value and an empty value don't have the same meaning; an empty value is considered a valid value. If a property references another data type, using an empty value will result in an error, while a null value will not raise any referential integrity error.

The type of data that needs to be provided depends on the data type of each field in the target entity/enum. The following table details the values that can be entered for each data type encountered in the Pay Suite data foundation:

Possible values by data type
JSON property type Possible values
Boolean

true

false

null
Date

Dat, in ISO8601 format

YYYY-MM-DD

null
Number DDD.DDD where " . " is used as the decimal separator
String

<string>

null

The following code snippet offers an example of a JSON node for the Worker entity:

Copy
[
{
  "ExternalId":"worker5",
  "LastName":"Abc",
  "FirstName":"Piotr",
  "WorkEmail":"piotr.abc@beqom.com",
  "PreferredLanguage":"pa",
  "Timezone":"Africa/Accra",
  "UserName":"piotrabc",
  "ProvisionUserAccount":false,
  "PerformanceEligibility":false,
  "ProvisionActiveWorker":false
}
]

This is a tip message.

Once the request is accepted, a unique ID is generated for the requested ingestion and returned back as a response.

Ingestion status endpoint

The data injection status endpoint is used to track the status of an injection process. There are six possible statuses:

Data ingestion API statuses
Status Description
Queued

The request was accepted by the system.

This is a preliminary state, it doesn't mean that the ingestion is completed.
In Progress The system is currently parsing, validating and committing the data provided in the system.
Sync The system is synchronizing the ingested data with the other services.
Completed The ingestion was successfully completed.
Failed The ingestion was not successfully completed.
StaleTimeout

The ingestion was not successfully completed due to timeout. There are two possible reasons for that status:

  1. service was restarted during ingestion (due to a new release or out of memory restart)

  2. IAM Service was not responding

Use the following API endpoint to return the status of your current data ingestion:

GET integrationapi/v1/data-foundation/ingestion/{ingestionId}/status

where the body of the call is empty and the ingestion ID corresponds to the ID returned by the data transmission endpoint.

The following table details the possible responses for the endpoint:

Status Response body
Ingestion log not found 404 NOT FOUND
Execution in progress
Copy
{ 
    "Status": "InProgress"
}
Execution completed successfully

200

Copy
[
    {
        "dataType": "Organization",
        "status": 2,
        "ingestionResult": "Ingestion completed successfully.",
        "iamResult": "Synchronization completed successfully."
    }
]
Execution failed

200

Copy
[{ 
    "dataType": "Worker",
    "status": "Failed",
    "ingestionResult":
      {
        Errors:[
          {
                "Type": "ReferencedDataTypeNotFoundError",
                "PropertyName": "PreferredLanguage",
                "ReferencedDataTypeName": "Language",
                "UserMeaningfulIdentifier": [
                    {
                        "Value": "worker5",
                        "PropertyName": "ExternalId"
                    }
                ],
                "ReferencedDataTypeUniqueIdentifier": "PropertyValue { IsInt = False, IsUInt = False, IsInt64 = False, IsUInt64 = False, IsDouble = False, IsBool = False, IsDate = False, IsDateTime = False, IsGuid = False, IsString = True, IsEmpty = False, HashCode = 10858878348103056540 }"
            }
        ]
      }
}]

Limitations of the data ingestion API

The following limitations apply to the use of the data ingestion API:

  • Only one data ingestion request can be run at any given time.

  • The maximum size of the request body is 10MB.

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