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 allan example of the currentuser availablearray fieldsJSON for import 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