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.

1. Get an Access Token

First, you need to authenticate and get an access token.
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:

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.

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