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 Required / Recommended / NotesDescription ExampleRequired/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