Masterdata API Documentation

This document describes the available endpoints for submitting masterdata imports, checking import status, updating import status, and triggering legal entity import processing in the acceptance environment.

POST

Submit data for masterdata importing


URL:https://masterdata-api-acceptance.hrblizz.dev/import
Method: POST
Content-Type: application/json
Description: Submits a masterdata payload for import processing.

Request Body

JSON payload containing import metadata and employee items.

{
  "hash": "unique-hash",
  "legalEntityCode": "REF-23-001",
  "validateEmployeeExistence": false,
  "filename": "hrb-demo",
  "numberOfItems": 46,
  "processingDate": "2019-01-01",
  "effectiveStartDate": "2019-01-01",
  "effectiveEndDate": "2019-01-31",
  "errorMessages": [
    "string"
  ],
  "items": [
    {
      "actionCode": "hire",
      "employeeId": "DEMO",
      "employee": {
        "hireDate": "2019-01-02",
        "originalHireDate": "2019-01-02",
        "enterpriseId": "[email protected]",
        "firstName": "John",
        "middleName": "Appleseed",
        "lastName": "Doe",
        "formattedName": "عبدال هادي محبوبة",
        "nationalId": 1234567,
        "passportNumber": "AB231654",
        "employeeGroupCode": "Permanent",
        "department": "Sales and Marketing",
        "division": "Division 11",
        "grade": "MGMT",
        "nationality": "ee",
        "gender": "m",
        "birthDate": "1990-01-01",
        "maritalStatus": "not_married",
        "position": "Manager",
        "status": "active",
        "contractType": "fixed_term",
        "payGroupCode": "demo3",
        "workScheduleCode": "WEEKLY",
        "lastWorkingDate": "2020-01-01",
        "terminationDate": "2019-01-01",
        "terminationReasonCode": "termination",
        "primaryCostCenterCode": "CC120091",
        "secondaryCostCenterCode": "CC00002",
        "secondaryCostCenterCodes": [
          {
            "code": "CC02",
            "ratio": 0.1
          },
          {
            "code": "CC04",
            "ratio": 0.2
          }
        ],
        "primaryProfitCenterCode": "PC900721",
        "payElements": [
          {
            "effectiveStartDate": "2019-01-01",
            "effectiveEndDate": "2019-01-31",
            "code": "basic",
            "payUnitCode": "hour",
            "debitAmount": "2300.00",
            "creditAmount": "2300.00",
            "currency": "USD"
          }
        ],
        "communications": {
          "effectiveDate": "2019-01-01",
          "emailAddress": "[email protected]",
          "phoneNumber": 1877123456,
          "addressLine1": "Some street 14",
          "addressLine2": "Apartment 421",
          "city": "Miami",
          "state": "Florida",
          "postalCode": "540069",
          "country": "us",
          "residenceCountry": "us"
        },
        "paymentMethod": "Bank",
        "primaryBankInfo": {
          "effectiveDate": "2019-01-01",
          "beneficiaryName": "John Doe",
          "swift": "IIRUBEBB",
          "iban": "NL55RABO4948749915",
          "accountNumber": "O4948749915",
          "accountCurrency": "USD",
          "bankCountry": "ee",
          "routingCode": 26985,
          "verificationNumber": "verif123"
        },
        "secondaryBankInfo": {
          "effectiveDate": "2019-01-01",
          "beneficiaryName": "John Doe",
          "swift": "IIRUBEBB",
          "iban": "NL55RABO4948749915",
          "accountNumber": "O4948749915",
          "accountCurrency": "USD",
          "bankCountry": "ee",
          "routingCode": 26985,
          "verificationNumber": "verif123"
        },
        "managerReferenceCode": "ManagerEmployeeId1",
        "hrFields": [
          {
            "code": "employment_type",
            "value": "LO"
          },
          {
            "code": "region",
            "value": "ASIA"
          },
          {
            "code": "sub_region",
            "value": "S033"
          },
          {
            "code": "site",
            "value": ""
          },
          {
            "code": "job_code",
            "value": ""
          },
          {
            "code": "legal_entity",
            "value": "YLL"
          },
          {
            "code": "sub_location",
            "value": "SL00A"
          },
          {
            "code": "cost_centre",
            "value": "D05"
          },
          {
            "code": "country",
            "value": "alpha_2_country_code"
          },
          {
            "code": "contracting_entity",
            "value": ""
          },
          {
            "code": "employment_type",
            "value": "COS"
          },
          {
            "code": "job_family",
            "value": "JF_**"
          },
          {
            "code": "sub_job_family",
            "value": "SM_**"
          },
          {
            "code": "employee_class",
            "value": "EMPCL-2"
          },
          {
            "code": "contract_start_date",
            "value": "01-01-2020"
          },
          {
            "code": "country_of_origin",
            "value": "alpha_2_country_code"
          },
          {
            "code": "full_legal_entity_name",
            "value": "free text"
          },
          {
            "code": "country_of_assignment",
            "value": "free text"
          },
          {
            "code": "city_of_assignment",
            "value": "free text"
          },
          {
            "code": "site_of_assignment",
            "value": "free text"
          },
          {
            "code": "client_name",
            "value": "free text"
          },
          {
            "code": "bonus_type",
            "value": "Com"
          },
          {
            "code": "bonus_structure",
            "value": "p"
          },
          {
            "code": "bonus_entitlement",
            "value": "amount"
          },
          {
            "code": "event_reasons",
            "value": "EC0082"
          },
          {
            "code": "family_information",
            "value": ""
          },
          {
            "code": "confirmation_due_date",
            "value": ""
          },
          {
            "code": "action_confirmation_date",
            "value": ""
          },
          {
            "code": "emergency_contact",
            "value": ""
          }
        ],
        "numberOfChildren": 1
      }
    }
  ]
}

Responses

200 OK Successful response

{
  "data": {
    "hrMasterdataImport": {
      "id": 1,
      "status": "pending",
      "hash": "unique-hash",
      "filename": "hrb-demo",
      "errors": [
        "string"
      ],
      "importTime": "2020-03-24T11:26:52",
      "createTime": "2020-03-24T11:24:31"
    }
  },
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "status": 200
}

4XX Error response

{
  "errors": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "status": 400
}

GET

Get masterdata import status

URL: https://masterdata-api-acceptance.hrblizz.dev/import/status/
Method: GET
Description: Returns the status and metadata for an existing masterdata import.

Path Parameters

legal_entity_code:Legal entity code associated with the import.
hr_masterdata_import_id:Identifier of the masterdata import record.

Responses

200 OK Successful response

{
  "data": {
    "hrMasterdataImport": {
      "id": 1,
      "status": "draft",
      "processingPeriod": {
        "id": 1,
        "name": "July 2019",
        "status": "scheduled",
        "beginDate": "2020-01-20",
        "endDate": "2020-01-20"
      },
      "hash": "unique-hash",
      "filename": "hrb-demo",
      "errors": [
        "string"
      ],
      "containsFieldErrors": false,
      "reports": [
        {
          "accessToken": "5f8696e7ee03c2264a530fb2",
          "createTime": "2020-11-31 17:19:44",
          "label": "Audit trail",
          "mimetype": "application/vnd.ms-excel",
          "size": 34304,
          "meta": {
            "property1": "someValue",
            "property2": "someValue"
          }
        }
      ],
      "importTime": "2020-03-24T11:26:52",
      "effectiveStartDate": "2020-01-31",
      "payloadFileApiToken": "5fabaa46a595ec95f59d12bc",
      "createTime": "2020-03-24T11:24:31",
      "lastStatusChangeTime": "2020-03-24T11:24:31",
      "lastStatusChangeActorEmployee": {
        "id": 1,
        "firstName": "John",
        "middleName": "Appleseed",
        "lastName": "Doe",
        "referenceCode": "REF-001",
        "photoAccessToken": "c14489a6-98ba-412d-b8ae-cc8415fd62f1"
      }
    }
  },
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fieldName": "string"
    }
  ],
  "status": 200
}

PUT

Edit masterdata import status

URL: https://masterdata-api-acceptance.hrblizz.dev/import/{hr_masterdata_import_id}
Method: PUT
Content-Type: application/json
Description: Updates the status and error details of an existing masterdata import.

Path Parameters

hr_masterdata_import_id: Identifier of the masterdata import record to update.

Request Body

{
  "hrImportStatus": "rejected",
  "errors": "[\"Wrong separator detected\",\"No matching parser mapping group found\"]"
}

Responses

200 OK Successful response

{
  "data": {
    "hrMasterdataImport": {
      "id": 1,
      "status": "draft",
      "processingPeriod": {
        "id": 1,
        "name": "July 2019",
        "status": "scheduled",
        "beginDate": "2020-01-20",
        "endDate": "2020-01-20"
      },
      "hash": "unique-hash",
      "filename": "hrb-demo",
      "errors": [
        "string"
      ],
      "containsFieldErrors": false,
      "reports": [
        {
          "accessToken": "5f8696e7ee03c2264a530fb2",
          "createTime": "2020-11-31 17:19:44",
          "label": "Audit trail",
          "mimetype": "application/vnd.ms-excel",
          "size": 34304,
          "meta": {
            "property1": "someValue",
            "property2": "someValue"
          }
        }
      ],
      "importTime": "2020-03-24T11:26:52",
      "effectiveStartDate": "2020-01-31",
      "payloadFileApiToken": "5fabaa46a595ec95f59d12bc",
      "createTime": "2020-03-24T11:24:31",
      "lastStatusChangeTime": "2020-03-24T11:24:31",
      "lastStatusChangeActorEmployee": {
        "id": 1,
        "firstName": "John",
        "middleName": "Appleseed",
        "lastName": "Doe",
        "referenceCode": "REF-001",
        "photoAccessToken": "c14489a6-98ba-412d-b8ae-cc8415fd62f1"
      }
    }
  },
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fieldName": "string"
    }
  ],
  "status": 200
}

POST

Submit legal entity data for masterdata importing

URL: https://masterdata-api-acceptance.hrblizz.dev/import/submit/{legal_entity_code}
Method: POST
Request Body: Empty
Description: Triggers submission of legal entity masterdata for import processing.

Path Parameters

legal_entity_codeLegal entity code to submit for import.

Responses

201 CreatedSuccessful response example

{
  "data": {
    "queuedTasks": [
      {
        "uuid": "0ef87f9b-b4de-4b1f-883f-79cf610a5abf",
        "taskName": "Interface parse",
        "groupCode": "interface.parse",
        "routingKey": "taskrunner.InitiateCorrectionRunTask",
        "status": "done",
        "actorEmployee": {
          "id": 1,
          "firstName": "John",
          "middleName": "Appleseed",
          "lastName": "Doe",
          "referenceCode": "REF-001",
          "photoAccessToken": "c14489a6-98ba-412d-b8ae-cc8415fd62f1"
        },
        "resultMessage": "Invalid parameters provided",
        "message": "Payslips submitted to ESS without sending out notifications.",
        "fileId": 12764,
        "fileAccessToken": "98ea0ef6-1301-4203-b1a5-2ff3fcf4e7d4",
        "additionalProperties": [
          {
            "code": "required",
            "message": "Missing required field Email",
            "fieldName": "primary_email",
            "parameters": [
              {
                "key": "referenceCode",
                "value": "REF-E-49"
              }
            ]
          }
        ],
        "actionDescription": "Filename: qwerty.csv",
        "createTime": "2020-11-31 17:19:44",
        "updateTime": "2020-11-31 17:19:44"
      }
    ]
  },
  "errors": null,
  "status": 201
}