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
ESS Configured
passportNumber string
ESS Configured
mobileNumber string
ESS Configured
workNumber string
ESS Configured
homeNumber string
ESS Configured
middleName string
ESS Configured
initials string
ESS Configured
title string
ESS Configured
knownAs string
ESS Configured
homeLanguage string
ESS Configured
gender string
ESS Configured
race string
ESS Configured
citizenship string
ESS Configured
maritalStatus string
ESS Configured
birthDay string
ESS Configured
disability string
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
Optional
jobTitle string
Optional
jobCode string
Optional
occupationalCategory string
Optional
occupationalLevel string
Optional
jobOfoCode string
Optional
jobGrade string
Optional
gradingType string
Optional
positionExternalId int
Optional
positionTitle string
Optional
positionCode string
Optional
appointmentType string
Optional
startDate string
Optional
endDate string
Optional
reasonForTermination string
Optional
startDateInGroup string
Optional
startDateInCompany string
Optional
orgLevel1_externalId Int
Optional
orgLevel1_name string
Required
orgLevel1_code string
Optional
orgLevel1_workLocationName string
Optional
orgLevel2_externalId Int
Optional
orgLevel2_name string
Optional
orgLevel2_code string
Optional
orgLevel2_workLocationName string
Optional
orgLevel3_externalId Int
Optional
orgLevel3_name string
Optional
orgLevel3_code string
Optional
orgLevel3_workLocationName string
Optional
orgLevel4_externalId Int
Optional
orgLevel4_name string
Optional
orgLevel4_code string
Optional
orgLevel4_workLocationName string
Optional
orgLevel5_externalId Int
Optional
orgLevel5_name string
Optional
orgLevel5_code string
Optional
orgLevel5_workLocationName string
Optional
orgLevel6_externalId Int
Optional
orgLevel6_name string
Optional
orgLevel6_code string
Optional
orgLevel6_workLocationName string
Optional
orgLevel7_externalId Int
Optional
orgLevel7_name string
Optional
orgLevel7_code string
Optional
orgLevel7_workLocationName string
Optional
orgLevel8_externalId Int
Optional
orgLevel8_name string
Optional
orgLevel8_code string
Optional
orgLevel8_workLocationName string
Optional
orgLevel9_externalId Int
Optional
orgLevel9_name string
Optional
orgLevel9_code string
Optional
orgLevel9_workLocationName string
Optional
lineManagerUsername string
Optional
performanceManagerUsername string
Optional
departmentManagerUsername string
Optional
trainingManagerUsername string
Optional
pdpFirstApproverUsername string
Optional
pdpSecondApproverUsername string
Optional
leaveManagerUsername string
Optional
salaryReviewManagerUsername string
Optional
talentManagementManagerUsername string
Optional
secondaryReportingManagerUsername string
Optional
lineManagerOnceRemovedUsername string
Optional
workflowOriginatorUsername string
Optional
financeManagerUsername string
Optional
financeOfficerUsername string
Optional
hrOfficerUsername string
Optional
hrRecruitmentOfficerUsername string
Optional
businessUnitHrManagerUsername string
Optional
secondaryJobRequisitionApproverUsername string
Optional
leaveManagerAlternateApproverUsername string
Optional

Back to top