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 / Notes Example
externalId Int

username string

employeeCode string

name string

surname string

emailAddress string

alternateEmailAddress string

idNumber string

passportNumber string

mobileNumber string

workNumber string

homeNumber string

middleName string

initials string

title string

knownAs string

homeLanguage string

gender string

race string

citizenship string

maritalStatus string

birthDay string

disability string

residentialUnitNumber string

residentialComplexName string

residentialStreetNumber string

residentialStreetName string

residentialSuburbDistrict string

residentialCityTown string

residentialCountry string

residentialProvince string

residentialPostalCode string

residentialAsPostal string

postalUnitNumber string

postalComplexName string

postalStreetNumber string

postalStreetName string

postalSuburbDistrict string

postalCityTown string

postalCountry string

postalProvince string

postalCode string

jobExternalId int

jobTitle string

jobCode string

occupationalCategory string

occupationalLevel string

jobOfoCode string

jobGrade string

gradingType string

positionExternalId int

positionTitle string

positionCode string

appointmentType string

startDate string

endDate string

reasonForTermination string

startDateInGroup string

startDateInCompany string

orgLevel1_externalId Int

orgLevel1_name string

orgLevel1_code string

orgLevel1_workLocationName string

orgLevel2_externalId Int

orgLevel2_name string

orgLevel2_code string

orgLevel2_workLocationName string

orgLevel3_externalId Int

orgLevel3_name string

orgLevel3_code string

orgLevel3_workLocationName string

orgLevel4_externalId Int

orgLevel4_name string

orgLevel4_code string

orgLevel4_workLocationName string

orgLevel5_externalId Int

orgLevel5_name string

orgLevel5_code string

orgLevel5_workLocationName string

orgLevel6_externalId Int

orgLevel6_name string

orgLevel6_code string

orgLevel6_workLocationName string

orgLevel7_externalId Int

orgLevel7_name string

orgLevel7_code string

orgLevel7_workLocationName string

orgLevel8_externalId Int

orgLevel8_name string

orgLevel8_code string

orgLevel8_workLocationName string

orgLevel9_externalId Int

orgLevel9_name string

orgLevel9_code string

orgLevel9_workLocationName string

lineManagerUsername string

performanceManagerUsername string

departmentManagerUsername string

trainingManagerUsername string

pdpFirstApproverUsername string

pdpSecondApproverUsername string

leaveManagerUsername string

salaryReviewManagerUsername string

talentManagementManagerUsername string

secondaryReportingManagerUsername string

lineManagerOnceRemovedUsername string

workflowOriginatorUsername string

financeManagerUsername string

financeOfficerUsername string

hrOfficerUsername string

hrRecruitmentOfficerUsername string

businessUnitHrManagerUsername string

secondaryJobRequisitionApproverUsername string

leaveManagerAlternateApproverUsername string

Back to top