Skip to main content

Integration with Signify using the user import API

The user import API should be used when a third party needs to push data to Signify on a specific ruleset to update employee records.

image.png

1. Get an Access Token

First, you need to authenticate and get an access token.

End point: https://{domain}/api/identity/v1/CreateUserAccessToken

Run the cURL command (replace the values as needed):

curl --request POST \
  --url https://live.signifyhr.co.za/api/identity/v1/CreateUserAccessToken \
  --header 'Content-Type: application/json' \
  --cookie .AspNetCore.Antiforgery.3CuCAIFqZrU=YOUR_ANTIFORGERY_COOKIE \
  --data '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD","clientId":"YOUR_CLIENT_ID","skipRulesetActiveCheck":false}'
  • This will return a JSON response with an accessToken field.
  • The values for YOUR_USERNAME, YOUR_PASSWORD must be generated for a valid user in the system and provided by your system administrator.
  • The value YOUR_CLIENT_ID can be retrieved on the ruleset by going to
    • Ruleset Management | System Access| Additional Service Section | Copy the GUID e.g.

    • image.png

2. Use the Access Token to Import Users

Copy the value of accessToken (it starts with Bearer ...).
Now, use this token in the next cURL command to import your user data:

End point: https://{domain}/api/importapi/v1/ImportUsers
curl --request POST \
  --url https://live.signifyhr.co.za/api/importapi/v1/ImportUsers \
  --header 'Authorization: YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --cookie .AspNetCore.Antiforgery.aJ9qYnOEx9w=YOUR_ANTIFORGERY_COOKIE \
  --data '{
    "users": [
      {
        "username": "ASmith2025",
        "name": "Alex",
        "surname": "Smith",
        ...
      }
      // Add more users as needed
    ]
  }'
  •  Replace YOUR_ACCESS_TOKEN with the value from step 1.
  • Replace the user data in the user's array as needed. 
    • The externalIds in the body of the user are optional and should only be populated should a link to the external identity of that record be needed.
    • Limited to 50K users

The following code snippet shows an example of the user array JSON body

{
  "users": [
    {
      "externalId": 1001,
      "username": "ASmith2025",
      "name": "Alex",
      "surname": "Smith",
      "emailAddress": "alex.smith@example.com",
      "idNumber": "9001011234088",
      "mobileNumber": "+27798575766",
      "orgLevel1": {
        "externalId": 10,
        "name": "Corporate",
        "code": "CORP",
        "workLocationName": "Headquarters"
      },
      "orgLevel2": {
        "externalId": 20,
        "name": "Technology",
        "code": "TECH",
        "workLocationName": "Tech Campus"
      },
      "orgLevel3": {
        "externalId": 30,
        "name": "Software Development",
        "code": "SWDEV",
        "workLocationName": "Building A"
      },
      "orgLevel4": {
        "externalId": 0,
        "name": "",
        "code": "",
        "workLocationName": ""
      },
      "orgLevel5": {
        "externalId": 0,
        "name": "",
        "code": "",
        "workLocationName": ""
      },
      "orgLevel6": {
        "externalId": 0,
        "name": "",
        "code": "",
        "workLocationName": ""
      },
      "orgLevel7": {
        "externalId": 0,
        "name": "",
        "code": "",
        "workLocationName": ""
      },
      "orgLevel8": {
        "externalId": 0,
        "name": "",
        "code": "",
        "workLocationName": ""
      },
      "orgLevel9": {
        "externalId": 0,
        "name": "",
        "code": "",
        "workLocationName": ""
      },
      "jobExternalId": 2001,
      "jobTitle": "Software Engineer",
      "jobCode": "SE01",
      "positionExternalId": 3001,
      "positionTitle": "Full Stack Developer",
      "positionCode": "FSD01",
      "appointmentType": "permanent",
      "lineManagerUsername": "MJones2025",
      "performanceManagerUsername": "MJones2025",
      "startDate": "2023-01-15",
      "endDate": "",
      "reasonForTermination": "",
      "passportNumber": "X1234567",
      "payrollConnectorName": "GlobalPayroll",
      "payrollId": "GP-1001",
      "middleName": "Taylor",
      "initials": "A.T.",
      "title": "Mx.",
      "knownAs": "Alex",
      "homeLanguage": "English",
      "gender": "Non-binary",
      "race": "Not Disclosed",
      "citizenship": "United States",
      "maritalStatus": "Single",
      "maritalDate": "",
      "workNumber": "+15559876543",
      "homeNumber": "+15552223333",
      "birthDay": "1990-01-01",
      "residentialUnitNumber": "12B",
      "residentialComplexName": "Green Gardens",
      "residentialStreetNumber": "123",
      "residentialStreetName": "Maple Avenue",
      "residentialSuburbDistrict": "Downtown",
      "residentialCityTown": "Springfield",
      "residentialCountry": "United States",
      "residentialProvince": "Illinois",
      "residentialPostalCode": "62704",
      "residentialAsPostal": "1",
      "postalUnitNumber": "12B",
      "postalComplexName": "Green Gardens",
      "postalStreetNumber": "123",
      "postalStreetName": "Maple Avenue",
      "postalSuburbDistrict": "Downtown",
      "postalCityTown": "Springfield",
      "postalCountry": "United States",
      "postalProvince": "Illinois",
      "postalCode": "62704",
      "occupationalCategory": "Information Technology",
      "occupationalLevel": "Professional",
      "jobOfoCode": "2512",
      "jobGrade": "P3",
      "gradingType": "Standard",
      "departmentManagerUsername": "MJones2025",
      "trainingManagerUsername": "LChen2025",
      "pdpFirstApproverUsername": "LChen2025",
      "pdpSecondApproverUsername": "SKumar2025",
      "leaveManagerUsername": "MJones2025",
      "salaryReviewManagerUsername": "SKumar2025",
      "talentManagementManagerUsername": "LChen2025",
      "secondaryReportingManagerUsername": "SKumar2025",
      "lineManagerOnceRemovedUsername": "SKumar2025",
      "workflowOriginatorUsername": "ASmith2025",
      "financeManagerUsername": "RPatel2025",
      "financeOfficerUsername": "RPatel2025",
      "hrOfficerUsername": "JNguyen2025",
      "hrRecruitmentOfficerUsername": "JNguyen2025",
      "businessUnitHrManagerUsername": "JNguyen2025",
      "disability": "None",
      "alternateEmailAddress": "alex.smith.alt@example.com",
      "location": "Remote",
      "employeeCode": "EMP1001",
      "startDateInGroup": "2023-01-15",
      "secondaryJobRequisitionApproverUsername": "SKumar2025",
      "leaveManagerAlternateApproverUsername": "LChen2025",
      "startDateInCompany": "2023-01-15"
    }
  ]
}

Below is the list of fields that are required and recommended. Fields with no comment are optional.

Field Name API Field Type Description Required/Optional/ ESS Configured
externalId Int External Payroll Identity Id Optional
username string Username to allow the user to login Required
employeeCode string When empty it is set equal to username ESS Configured
name string Name of the user ESS Configured
surname string Surname of the user ESS Configured
emailAddress string Email for most notifications in the system e.g. Password reset ESS Configured
alternateEmailAddress string Email for reporting ESS Configured
idNumber string Id Number of the user ESS Configured
passportNumber string Passport number of the user ESS Configured
mobileNumber string Mobile number preferably with country code ESS Configured
workNumber string Work number preferably with country code ESS Configured
homeNumber string Home number preferably with country code ESS Configured
middleName string Middel name of user ESS Configured
initials string Initials of user  ESS Configured
title string Title of user ESS Configured
knownAs string Name the user is known as ESS Configured
homeLanguage string
ESS Configured
gender string
ESS Configured
race string
ESS Configured
citizenship string
ESS Configured
maritalStatus string
ESS Configured
birthDay string Date of birth of the user ESS Configured
disability string A single disability for the user ESS Configured
residentialUnitNumber string
Optional
residentialComplexName string
Optional
residentialStreetNumber string
Optional
residentialStreetName string
Optional
residentialSuburbDistrict string
Optional
residentialCityTown string
Optional
residentialCountry string
Required when any residential field supplied
residentialProvince string
Required when any residential field supplied
residentialPostalCode string
Optional
residentialAsPostal string
Optional
postalUnitNumber string
Optional
postalComplexName string
Optional
postalStreetNumber string
Optional
postalStreetName string
Optional
postalSuburbDistrict string
Optional
postalCityTown string
Optional
postalCountry string
Required when any postal field supplied
postalProvince string
Required when any postal field supplied
postalCode string
Optional
jobExternalId int The payroll job id Optional
jobTitle string Name of the job  Optional
jobCode string Code of the job Optional
occupationalCategory string Occupation Category of the job Optional
occupationalLevel string Occupational Level of the job within the category Optional
jobOfoCode string OFO code of the job Optional
jobGrade string Grade of the job Optional
gradingType string Grading used for the job Optional
positionExternalId int The payroll position Id Optional
positionTitle string Position Name Optional
positionCode string Position Code Optional
appointmentType string How the user is appointed in the position Optional
startDate string Start date in the position Optional
endDate string End date in the position, when empty the user is not terminated Optional
reasonForTermination string The reason the users employment has been ended Optional
startDateInGroup string The start date in the group Optional
startDateInCompany string The start date in the company within the group Optional
orgLevel1_externalId Int Org unit Id on payroll Optional
orgLevel1_name string
Required
orgLevel1_code string Unique code per ruleset for org unit Optional
orgLevel1_workLocationName string
Optional
orgLevel2_externalId Int Org unit Id on payroll Optional
orgLevel2_name string
Optional
orgLevel2_code string Unique code per ruleset for org unit Optional
orgLevel2_workLocationName string
Optional
orgLevel3_externalId Int Org unit Id on payroll Optional
orgLevel3_name string
Optional
orgLevel3_code string Unique code per ruleset for org unit Optional
orgLevel3_workLocationName string
Optional
orgLevel4_externalId Int Org unit Id on payroll Optional
orgLevel4_name string
Optional
orgLevel4_code string Unique code per ruleset for org unit Optional
orgLevel4_workLocationName string
Optional
orgLevel5_externalId Int Org unit Id on payroll Optional
orgLevel5_name string
Optional
orgLevel5_code string Unique code per ruleset for org unit Optional
orgLevel5_workLocationName string
Optional
orgLevel6_externalId Int Org unit Id on payroll Optional
orgLevel6_name string
Optional
orgLevel6_code string Unique code per ruleset for org unit Optional
orgLevel6_workLocationName string
Optional
orgLevel7_externalId Int Org unit Id on payroll Optional
orgLevel7_name string
Optional
orgLevel7_code string Unique code per ruleset for org unit Optional
orgLevel7_workLocationName string
Optional
orgLevel8_externalId Int Org unit Id on payroll Optional
orgLevel8_name string
Optional
orgLevel8_code string Unique code per ruleset for org unit Optional
orgLevel8_workLocationName string
Optional
orgLevel9_externalId Int Org unit Id on payroll Optional
orgLevel9_name string
Optional
orgLevel9_code string Unique code per ruleset for org unit Optional
orgLevel9_workLocationName string
Optional
lineManagerUsername string The username of the manager, existing in the system or part of the API body Optional
performanceManagerUsername string The username of the manager, existing in the system or part of the API body Optional
departmentManagerUsername string The username of the manager, existing in the system or part of the API body Optional
trainingManagerUsername string The username of the manager, existing in the system or part of the API body Optional
pdpFirstApproverUsername string The username of the manager, existing in the system or part of the API body Optional
pdpSecondApproverUsername string The username of the manager, existing in the system or part of the API body Optional
leaveManagerUsername string The username of the manager, existing in the system or part of the API body Optional
salaryReviewManagerUsername string The username of the manager, existing in the system or part of the API body Optional
talentManagementManagerUsername string The username of the manager, existing in the system or part of the API body Optional
secondaryReportingManagerUsername string The username of the manager, existing in the system or part of the API body Optional
lineManagerOnceRemovedUsername string The username of the manager, existing in the system or part of the API body Optional
workflowOriginatorUsername string The username of the manager, existing in the system or part of the API body Optional
financeManagerUsername string The username of the manager, existing in the system or part of the API body Optional
financeOfficerUsername string The username of the manager, existing in the system or part of the API body Optional
hrOfficerUsername string The username of the manager, existing in the system or part of the API body Optional
hrRecruitmentOfficerUsername string The username of the manager, existing in the system or part of the API body Optional
businessUnitHrManagerUsername string The username of the manager, existing in the system or part of the API body Optional
secondaryJobRequisitionApproverUsername string The username of the manager, existing in the system or part of the API body Optional
leaveManagerAlternateApproverUsername string The username of the manager, existing in the system or part of the API body Optional

Back to top