Look up a new starter in your HR system

Let the SuperIT agent read a new starter's details straight from your HR system, so an onboarding request needs only a name and SuperIT fills in the job title, department, manager, office and start date. For MSPs and IT teams whose HR platform has a REST API.

Why use an action instead of asking SuperIT

SuperIT can't see your HR system: it has no credential for it and no way to call an arbitrary API. This action stores the HR API key once as an encrypted credential, and lets SuperIT pull the starter's title, manager, department and start date into the onboarding action's inputs, so nobody retypes them from an email.

If HR has already sent the details in the ticket, just ask SuperIT to onboard the user with them.

When to use it

• "Sam Patel starts Monday. Can you get everything ready?"
• "What's the new finance hire's start date and who's their manager?"
• "Check HR before we set up the account for Alex Chen."

This action is a building block. The SuperIT agent uses its output as the inputs for your onboarding action, so the account is created with the same details HR holds, and engineers don't retype them from an email.

What the action does

1. Reads name and, optionally, work_email.
2. Searches the HR system's employee directory with the API key from the linked credential.
3. If you gave a work_email, keeps only the person with that email. If nobody has it, the action reports no match and says the email didn't match, rather than guessing from the name.
4. If exactly one person matches, prints their preferred name, job title, department, manager, location, employment type and start date.
5. If several people match, lists them briefly so SuperIT can ask which one is meant.

What it doesn't do:

• It doesn't create the account, assign licences or add groups. Your onboarding action does that, with its own approval.
• It doesn't return pay, home address, date of birth, national ID numbers or other sensitive HR data. The script keeps an explicit list of the fields it outputs.
• It doesn't write anything back to the HR system.

Before you begin

• An HR API key with the narrowest read scope available, ideally limited to the employee directory fields listed above. Ask your HR administrator; HR systems often let you restrict an API user's field access.
• A credential. Under Workflows → Credentials, select New, name it HR System and choose the Auth scheme your HR system uses. This guide uses Other (Basic auth), read by the script as CREDENTIAL_HR_SYSTEM_AUTHORIZATION. See Credentials.
• No authorization policy, so only engineers and admins can run it. Don't let end users run an action that reads HR data about other people. See Approvals.
• Your role. Creating an action in chat needs the Admin role. Engineers can build it by hand under Workflows → Actions.

Build it with SuperIT

Create an action called "Look up new starter in HR".
Purpose: find a new starter in our HR system by name (and optional work email) and return the details we need for onboarding.
Runtime: PowerShell in the cloud sandbox, using Invoke-RestMethod.
Inputs: name (string, required), work_email (email, optional).
Credential: "HR System" (Basic auth). API docs: <link to your HR system's API docs>.
Only output: preferred name, job title, department, manager name and email, location, employment type, start date. Never output pay, address, date of birth or ID numbers.
If several people match, list them with job title and start date so I can choose. If work_email is given and nobody has it, return no match and say the email didn't match.
No authorization policy: engineers and admins only, no approval.

SuperIT drafts the script against your HR system's API, validates it and creates the action as a draft. You review it, test it and publish it under Workflows → Actions.

Or build it yourself

Set Runtime to PowerShell and adapt the endpoint and field names:

# Goal: find a new starter in the HR directory by name (and optional work email), read-only, returning only onboarding fields.
$baseUrl = "https://hr.example.com/api/v1"   # your HR system's API
$auth = $env:CREDENTIAL_HR_SYSTEM_AUTHORIZATION
$allowedFields = @("preferredName", "jobTitle", "department", "managerName",
    "managerEmail", "location", "employmentType", "startDate")

function Invoke-NewStarterLookup {
    param([string]$Name, [string]$WorkEmail)

    $searchName = $Name.Trim()
    $email = $WorkEmail.Trim().ToLower()
    Assert-Inputs -Name $searchName
    $nameMatches = @(Find-Employee -Name $searchName)
    $people = @(Select-ByWorkEmail -People $nameMatches -Email $email)
    $emailMismatch = [bool]($email -and $nameMatches.Count -gt 0 -and $people.Count -eq 0)
    $safe = @($people | ForEach-Object { ConvertTo-SafeRecord -Person $_ })
    Write-StarterReport -Name $searchName -People $safe -Email $email -EmailMismatch $emailMismatch -NameMatchCount $nameMatches.Count
    # $script: so the runner can still read $result after this function returns.
    $script:result = @{ matches = $safe.Count; email_mismatch = $emailMismatch; people = @($safe | Select-Object -First 10) }
}

function Assert-Inputs {
    param([string]$Name)
    if ($Name.Length -lt 2) { throw "Input 'name' is required." }
    if (-not $auth) { throw "The 'HR System' credential is not linked to this action." }
}

function Find-Employee {
    param([string]$Name)
    $uri = "$baseUrl/employees?search=$([uri]::EscapeDataString($Name))"
    try {
        $response = Invoke-RestMethod -Uri $uri -Headers @{ Authorization = $auth; Accept = "application/json" } -TimeoutSec 30
    } catch {
        throw "Failed to search the HR system for '$Name': $($_.Exception.Message)"
    }
    return @($response.employees | Where-Object { $_ })
}

function Select-ByWorkEmail {
    param([object[]]$People, [string]$Email)
    if (-not $Email) { return $People }
    # No fallback to the name matches: their manager and title must not reach onboarding for the wrong person.
    return @($People | Where-Object { "$($_.workEmail)".ToLower() -eq $Email })
}

function ConvertTo-SafeRecord {
    param($Person)
    # Copy only the allowed fields, so nothing else the HR API returns can reach the output.
    $row = [ordered]@{}
    foreach ($f in $allowedFields) {
        $value = $Person.$f
        # Invoke-RestMethod turns ISO timestamps into [datetime] objects.
        if ($value -is [datetime]) { $value = $value.ToString('yyyy-MM-dd') }
        $row[$f] = $value
    }
    return $row
}

function Write-StarterReport {
    param([string]$Name, [object[]]$People, [string]$Email, [bool]$EmailMismatch, [int]$NameMatchCount)
    Write-Output "=== HR LOOKUP ==="
    Write-Output "Search  : $Name"
    if ($Email) { Write-Output "Email   : $Email" }
    Write-Output "Matches : $($People.Count)"
    if ($EmailMismatch) {
        Write-Output "$NameMatchCount person(s) called '$Name' were found, but none has the work email '$Email'. Check the email with HR."
    } elseif ($People.Count -eq 0) {
        Write-Output "No one called '$Name' was found in the HR system."
    } elseif ($People.Count -gt 1) {
        Write-Output "Several people match '$Name'. Ask which one is meant:"
        foreach ($p in ($People | Select-Object -First 10)) {
            Write-Output "- $($p.preferredName) | $($p.jobTitle) | starts $($p.startDate)"
        }
    } else {
        $p = $People[0]
        foreach ($f in $allowedFields) {
            $value = if ($p[$f]) { $p[$f] } else { "(not set)" }
            Write-Output "${f} : $value"
        }
    }
}

Invoke-NewStarterLookup -Name $ctx.inputs.name -WorkEmail $ctx.inputs.work_email

Test it

1. Save the draft and select Test.
2. Test is not a dry run: it skips authorization and approvals and uses the real credential and network access. This action only reads. Test runs aren't billed.
3. Test with a recent hire, a common first name that matches several people, a name that doesn't exist, and a real name with the wrong work email.
4. Check that no field outside the list appears in Stdout or Result.
5. Select Publish.

Use it

• In chat: "Sam Patel starts Monday. Look them up in HR and draft the onboarding." SuperIT runs this action, shows what it found and, after you confirm, runs your onboarding action with those values.
• From a ticket: when an onboarding request arrives as a ticket, SuperIT can recommend this action first and the onboarding action second. An investigation only recommends actions and doesn't read their output, so an engineer runs the lookup in chat and SuperIT carries the details into the onboarding action from there.
• Ahead of start dates: to check upcoming starters every week, add a start_after input and ask SuperIT to schedule the action every 7 days.

Variations

• Leavers: look up the leaver's last working day and manager, to feed an offboarding action.
• Cross-check: compare the HR job title and department with the user's Microsoft 365 profile and list differences.
• Your HR system has no API: use a Playwright action to sign in to the HR portal with a read-only account and read the same fields.

Related

• Call a third-party API
• Credentials
• Approvals
• Connect Microsoft 365