HR Directory & Identity Integration

The HR Directory integration synchronizes employee data from HR systems (SAP SuccessFactors, Workday, BambooHR) and identity providers (Azure AD, Okta, on-prem Active Directory/LDAP). This enables automatic user provisioning, org chart resolution for ticket routing, manager escalation chains, and department-based access control.

Supported sources

The platform ships with adapters for six identity and HR data sources out of the box.

Source	Capabilities	Auth methods
Azure AD / Entra ID	User sync, group sync, nested group resolution, conditional access	OAuth2 (Client Credentials)
Okta	User provisioning, group sync, SCIM	API Token, OAuth2
Active Directory (LDAP)	User lookup, group membership, manager hierarchy, authentication	LDAP Bind (LDAPS)
SAP SuccessFactors	Employee master data, org chart, cost centers	OAuth2, SAML
Workday	Worker data, department hierarchy, leave balances	OAuth2, API Key
BambooHR	Employee records, directory, time-off tracking	API Key

The employee model

The employee model contains the full profile of an employee record as synchronized from connected HR systems and identity providers, including organizational placement, employment metadata, and source tracking.

Properties

Name
id
Type
string
Description
Unique identifier for the employee record.
Name
employee_id
Type
string
Description
HR system employee number (e.g. EMP25048172).
Name
email
Type
string
Description
Corporate email address.
Name
display_name
Type
string
Description
Full display name as it appears in the directory.
Name
first_name
Type
string
Description
Employee first name.
Name
last_name
Type
string
Description
Employee last name.
Name
job_title
Type
string
Description
Current job title.
Name
department
Type
string
Description
Department name.
Name
division
Type
string
Description
Business division or business unit.
Name
cost_center
Type
string
Description
Financial cost center code.
Name
manager_id
Type
string
Description
Reference to the manager's employee record ID.
Name
location
Type
string
Description
Office location (building, city, or site name).
Name
phone
Type
string
Description
Business phone number.
Name
status
Type
string
Description
Employment status. One of active, on_leave, suspended, terminated, retired, or contractor.
Name
employment_type
Type
string
Description
Type of employment. One of full_time, part_time, contractor, intern, or temporary.
Name
start_date
Type
string
Description
Employment start date in ISO 8601 format.
Name
source
Type
string
Description
Identity provider or HR system that owns this record. One of azure_ad, okta, ldap, sap_successfactors, workday, bamboohr, or manual.
Name
external_id
Type
string
Description
The employee's ID in the source system (e.g. Azure AD Object ID, LDAP DN, Okta user ID).
Name
groups
Type
array
Description
AD/LDAP/IdP group memberships as an array of group names.
Name
user_id
Type
string
Description
Linked ITSM platform user ID, if the employee has a platform account.
Name
synced_at
Type
timestamp
Description
Timestamp of the last successful sync from the source system.
Name
created_at
Type
timestamp
Description
Timestamp of when the employee record was created.
Name
updated_at
Type
timestamp
Description
Timestamp of the last update to this record.
Name
org_id
Type
string
Description
Organization (tenant) that owns this employee record.

GET/v1/hr/employees

List employees

This endpoint allows you to retrieve a paginated list of employees in your organization. Results can be filtered by department, employment status, source system, and manager. By default, a maximum of twenty employees are shown per page.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of employees returned. Default is 20, maximum is 100.
Name
cursor
Type
string
Description
Pagination cursor from a previous response's next_cursor field.
Name
department
Type
string
Description
Filter by department name, e.g. IT Infrastructure.
Name
status
Type
string
Description
Filter by employment status: active, on_leave, suspended, terminated, retired, or contractor.
Name
source
Type
string
Description
Filter by source system: azure_ad, okta, ldap, sap_successfactors, workday, bamboohr, or manual.
Name
manager_id
Type
string
Description
Filter by manager's employee ID to list direct reports.
Name
search
Type
string
Description
Fuzzy search across name, email, and employee ID fields.

Request

GET

/v1/hr/employees

curl -G http://localhost:3000/v1/hr/employees \
  -H "Authorization: Bearer {token}" \
  -d limit=10 \
  -d department=IT%20Infrastructure \
  -d status=active

Response

{
  "has_more": true,
  "next_cursor": "eyJpZCI6ImVtcF85dFJuTDRtSzd3WGIifQ",
  "data": [
    {
      "id": "emp_7xKpQ2mR4wVb",
      "employee_id": "EMP25048172",
      "email": "jane.smith@acmecorp.com",
      "display_name": "Jane Smith",
      "first_name": "Jane",
      "last_name": "Smith",
      "job_title": "Sr. DevOps Engineer",
      "department": "IT Infrastructure",
      "division": "Technology",
      "cost_center": "CC-4200",
      "manager_id": "emp_3nLsW8kF9xYt",
      "location": "Austin HQ - Bldg 3",
      "phone": "+1-512-555-0142",
      "status": "active",
      "employment_type": "full_time",
      "start_date": "2022-03-15",
      "source": "azure_ad",
      "external_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "groups": [
        "IT-Infrastructure",
        "VPN-Users",
        "Cloud-Admins",
        "On-Call-Rotation"
      ],
      "user_id": "usr_8mWqR3nT5vXp",
      "synced_at": 1708732800,
      "created_at": 1647302400,
      "updated_at": 1708732800,
      "org_id": "org_5kPmN8rT2wXq"
    },
    {
      "id": "emp_2kNpL7mS9wYr",
      "employee_id": "EMP25031456",
      "email": "marcus.chen@acmecorp.com",
      "display_name": "Marcus Chen",
      "first_name": "Marcus",
      "last_name": "Chen",
      "job_title": "Network Engineer II",
      "department": "IT Infrastructure",
      "division": "Technology",
      "cost_center": "CC-4200",
      "manager_id": "emp_7xKpQ2mR4wVb",
      "location": "Austin HQ - Bldg 3",
      "phone": "+1-512-555-0198",
      "status": "active",
      "employment_type": "full_time",
      "start_date": "2023-06-01",
      "source": "azure_ad",
      "external_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "groups": [
        "IT-Infrastructure",
        "VPN-Users",
        "Network-Admins"
      ],
      "user_id": "usr_6jHtK4pR8uWn",
      "synced_at": 1708732800,
      "created_at": 1685577600,
      "updated_at": 1708732800,
      "org_id": "org_5kPmN8rT2wXq"
    }
  ]
}

GET/v1/hr/employees/:id

Get employee details

This endpoint allows you to retrieve the full profile of a single employee, including their organizational context such as manager information and department placement. The response includes the employee's linked ITSM platform user ID if provisioned.

Request

GET

/v1/hr/employees/emp_7xKpQ2mR4wVb

curl http://localhost:3000/v1/hr/employees/emp_7xKpQ2mR4wVb \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "emp_7xKpQ2mR4wVb",
  "employee_id": "EMP25048172",
  "email": "jane.smith@acmecorp.com",
  "display_name": "Jane Smith",
  "first_name": "Jane",
  "last_name": "Smith",
  "job_title": "Sr. DevOps Engineer",
  "department": "IT Infrastructure",
  "division": "Technology",
  "cost_center": "CC-4200",
  "manager_id": "emp_3nLsW8kF9xYt",
  "manager": {
    "id": "emp_3nLsW8kF9xYt",
    "display_name": "Priya Ramirez",
    "email": "priya.ramirez@acmecorp.com",
    "job_title": "Director of Infrastructure"
  },
  "location": "Austin HQ - Bldg 3",
  "phone": "+1-512-555-0142",
  "status": "active",
  "employment_type": "full_time",
  "start_date": "2022-03-15",
  "source": "azure_ad",
  "external_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "groups": [
    "IT-Infrastructure",
    "VPN-Users",
    "Cloud-Admins",
    "On-Call-Rotation"
  ],
  "user_id": "usr_8mWqR3nT5vXp",
  "synced_at": 1708732800,
  "created_at": 1647302400,
  "updated_at": 1708732800,
  "org_id": "org_5kPmN8rT2wXq"
}

GET/v1/hr/employees/:id/direct-reports

Get direct reports

This endpoint returns the list of employees who directly report to the specified manager. This is used for ticket routing (assigning to the right team), approval workflows, and building the org chart visualization.

Request

GET

/v1/hr/employees/emp_3nLsW8kF9xYt/direct-reports

curl http://localhost:3000/v1/hr/employees/emp_3nLsW8kF9xYt/direct-reports \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "id": "emp_7xKpQ2mR4wVb",
      "employee_id": "EMP25048172",
      "email": "jane.smith@acmecorp.com",
      "display_name": "Jane Smith",
      "job_title": "Sr. DevOps Engineer",
      "department": "IT Infrastructure",
      "status": "active"
    },
    {
      "id": "emp_4rTnM6kW2xPq",
      "employee_id": "EMP25052841",
      "email": "david.okafor@acmecorp.com",
      "display_name": "David Okafor",
      "job_title": "Systems Administrator III",
      "department": "IT Infrastructure",
      "status": "active"
    },
    {
      "id": "emp_9wLsK3mR7vNb",
      "employee_id": "EMP25019384",
      "email": "sarah.park@acmecorp.com",
      "display_name": "Sarah Park",
      "job_title": "Cloud Platform Engineer",
      "department": "IT Infrastructure",
      "status": "on_leave"
    }
  ]
}

GET/v1/hr/employees/:id/chain

Get management chain

This endpoint returns the management escalation chain for an employee, starting with their direct manager and walking up the hierarchy to the top of the organization. This is used for SLA escalation paths, approval routing, and VIP detection. The direction parameter controls whether to walk up (toward CEO) or down (full subtree).

Optional attributes

Name
direction
Type
string
Description
Direction to traverse. up returns the chain of managers toward the top. down returns the full subtree of reports. Defaults to up.
Name
max_depth
Type
integer
Description
Maximum depth of the hierarchy to return. Defaults to 10.

Request

GET

/v1/hr/employees/emp_7xKpQ2mR4wVb/chain

curl -G http://localhost:3000/v1/hr/employees/emp_7xKpQ2mR4wVb/chain \
  -H "Authorization: Bearer {token}" \
  -d direction=up \
  -d max_depth=5

Response

{
  "employee_id": "emp_7xKpQ2mR4wVb",
  "direction": "up",
  "depth": 3,
  "chain": [
    {
      "level": 1,
      "id": "emp_3nLsW8kF9xYt",
      "display_name": "Priya Ramirez",
      "email": "priya.ramirez@acmecorp.com",
      "job_title": "Director of Infrastructure",
      "department": "IT Infrastructure"
    },
    {
      "level": 2,
      "id": "emp_6pRtH5jN2cEm",
      "display_name": "Thomas Whitfield",
      "email": "thomas.whitfield@acmecorp.com",
      "job_title": "VP of Engineering",
      "department": "Engineering"
    },
    {
      "level": 3,
      "id": "emp_1mWqR3nT5vXp",
      "display_name": "Elena Vasquez",
      "email": "elena.vasquez@acmecorp.com",
      "job_title": "Chief Technology Officer",
      "department": "Executive"
    }
  ]
}

GET/v1/hr/departments

List departments

This endpoint returns a list of all departments in the organization along with their headcounts, broken down by employment status. Useful for building department-based routing rules and capacity dashboards.

Request

GET

/v1/hr/departments

curl http://localhost:3000/v1/hr/departments \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "name": "IT Infrastructure",
      "division": "Technology",
      "headcount": 42,
      "active": 38,
      "on_leave": 3,
      "contractors": 1,
      "cost_center": "CC-4200",
      "head": {
        "id": "emp_3nLsW8kF9xYt",
        "display_name": "Priya Ramirez",
        "job_title": "Director of Infrastructure"
      }
    },
    {
      "name": "Application Development",
      "division": "Technology",
      "headcount": 87,
      "active": 81,
      "on_leave": 4,
      "contractors": 2,
      "cost_center": "CC-4100",
      "head": {
        "id": "emp_8kWnL4pR2vYt",
        "display_name": "Michael Torres",
        "job_title": "Director of Application Development"
      }
    },
    {
      "name": "Human Resources",
      "division": "Corporate",
      "headcount": 18,
      "active": 17,
      "on_leave": 1,
      "contractors": 0,
      "cost_center": "CC-1100",
      "head": {
        "id": "emp_5jRtK3mN7wXb",
        "display_name": "Amanda Liu",
        "job_title": "VP of Human Resources"
      }
    }
  ]
}

GET/v1/hr/org-chart

Get organization chart

This endpoint returns a hierarchical tree representation of the organization chart, suitable for rendering in visualization components. By default, it returns the full tree from the top-level executive down. Use root_id to scope the tree to a specific subtree.

Optional attributes

Name
root_id
Type
string
Description
Employee ID to use as the root of the tree. Defaults to the top-level executive.
Name
max_depth
Type
integer
Description
Maximum tree depth to return. Defaults to 5.
Name
department
Type
string
Description
Filter the tree to a specific department.

Request

GET

/v1/hr/org-chart

curl -G http://localhost:3000/v1/hr/org-chart \
  -H "Authorization: Bearer {token}" \
  -d root_id=emp_3nLsW8kF9xYt \
  -d max_depth=2

Response

{
  "root": {
    "id": "emp_3nLsW8kF9xYt",
    "display_name": "Priya Ramirez",
    "email": "priya.ramirez@acmecorp.com",
    "job_title": "Director of Infrastructure",
    "department": "IT Infrastructure",
    "direct_report_count": 5,
    "children": [
      {
        "id": "emp_7xKpQ2mR4wVb",
        "display_name": "Jane Smith",
        "email": "jane.smith@acmecorp.com",
        "job_title": "Sr. DevOps Engineer",
        "department": "IT Infrastructure",
        "direct_report_count": 3,
        "children": [
          {
            "id": "emp_2kNpL7mS9wYr",
            "display_name": "Marcus Chen",
            "job_title": "Network Engineer II",
            "direct_report_count": 0,
            "children": []
          }
        ]
      },
      {
        "id": "emp_4rTnM6kW2xPq",
        "display_name": "David Okafor",
        "email": "david.okafor@acmecorp.com",
        "job_title": "Systems Administrator III",
        "department": "IT Infrastructure",
        "direct_report_count": 2,
        "children": []
      }
    ]
  },
  "total_nodes": 12,
  "max_depth_reached": false
}

POST/v1/hr/sync

Trigger directory sync

This endpoint triggers an on-demand synchronization of employee and group data from a configured identity provider or HR system. Syncs are enqueued via BullMQ and processed asynchronously with retry logic and exponential backoff. The response returns a sync job ID you can poll via the status endpoint.

Required attributes

Name
source
Type
string
Description
The identity provider to sync from: azure_ad, okta, ldap, sap_successfactors, workday, or bamboohr.

Optional attributes

Name
sync_type
Type
string
Description
Sync scope: full (re-sync everything), incremental (only changes since last sync), or manual (admin-triggered full). Defaults to incremental.
Name
include_groups
Type
boolean
Description
Whether to also sync group memberships. Defaults to true.

Request

POST

/v1/hr/sync

curl -X POST http://localhost:3000/v1/hr/sync \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "azure_ad",
    "sync_type": "incremental",
    "include_groups": true
  }'

Response

{
  "sync_id": "sync_4kPmN8rT2wXq",
  "source": "azure_ad",
  "sync_type": "incremental",
  "status": "queued",
  "include_groups": true,
  "queued_at": 1708733100,
  "estimated_duration_ms": 45000
}

GET/v1/hr/sync/status

Get sync status

This endpoint returns the status of the most recent directory synchronization job, including detailed statistics on users and groups created, updated, skipped, and errored. Use the sync_id parameter to query a specific sync job, or omit it to get the latest.

Optional attributes

Name
sync_id
Type
string
Description
The specific sync job ID to query. If omitted, returns the most recent sync.
Name
source
Type
string
Description
Filter by source provider to get the latest sync for that specific source.

Request

GET

/v1/hr/sync/status

curl -G http://localhost:3000/v1/hr/sync/status \
  -H "Authorization: Bearer {token}" \
  -d sync_id=sync_4kPmN8rT2wXq

Response

{
  "sync_id": "sync_4kPmN8rT2wXq",
  "source": "azure_ad",
  "sync_type": "incremental",
  "status": "completed",
  "started_at": 1708733100,
  "completed_at": 1708733142,
  "duration_ms": 42381,
  "stats": {
    "users_created": 3,
    "users_updated": 47,
    "users_disabled": 1,
    "users_deleted": 0,
    "users_skipped": 812,
    "users_errors": 0,
    "groups_created": 0,
    "groups_updated": 5,
    "groups_deleted": 0,
    "groups_skipped": 34,
    "groups_errors": 0,
    "memberships_added": 12,
    "memberships_removed": 3,
    "total_processed": 902
  },
  "errors": [],
  "next_sync_token": "aHR0cHM6Ly9ncmFwaC5taWNyb3NvZnQuY29tL3YxLjAvdXNlcnMvZGVsdGE_JGRlbHRhdG9rZW49..."
}

POST/v1/hr/lookup

Lookup employee

This endpoint performs a fuzzy search for employees by email, name, or employee ID. It returns the best matching results ranked by relevance. This is designed for typeahead/autocomplete in ticket forms and for resolving caller identity from inbound channels (email, chat, phone).

Required attributes

Name
query
Type
string
Description
The search term. Can be a partial name, email address, or employee ID.

Optional attributes

Name
limit
Type
integer
Description
Maximum number of results to return. Default is 5, maximum is 20.
Name
status
Type
string
Description
Only return employees with this status. Defaults to active.

Request

POST

/v1/hr/lookup

curl -X POST http://localhost:3000/v1/hr/lookup \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "jane.smith",
    "limit": 5
  }'

Response

{
  "data": [
    {
      "id": "emp_7xKpQ2mR4wVb",
      "employee_id": "EMP25048172",
      "email": "jane.smith@acmecorp.com",
      "display_name": "Jane Smith",
      "job_title": "Sr. DevOps Engineer",
      "department": "IT Infrastructure",
      "location": "Austin HQ - Bldg 3",
      "status": "active",
      "match_score": 0.98,
      "match_field": "email"
    },
    {
      "id": "emp_5tRnL4mK7wXb",
      "employee_id": "EMP25037291",
      "email": "janet.smithson@acmecorp.com",
      "display_name": "Janet Smithson",
      "job_title": "Business Analyst",
      "department": "Finance",
      "location": "Chicago Office",
      "status": "active",
      "match_score": 0.72,
      "match_field": "email"
    }
  ]
}

GET/v1/hr/groups

List directory groups

This endpoint returns a paginated list of AD/LDAP/IdP groups synchronized from connected identity providers. Groups are used for role-based access control, ticket routing rules, and notification targeting.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of groups returned. Default is 20, maximum is 100.
Name
source
Type
string
Description
Filter by source provider: azure_ad, okta, or ldap.
Name
search
Type
string
Description
Search by group name.
Name
is_security_group
Type
boolean
Description
Filter to only security groups (AD) or include distribution lists. Defaults to showing all.

Request

GET

/v1/hr/groups

curl -G http://localhost:3000/v1/hr/groups \
  -H "Authorization: Bearer {token}" \
  -d limit=10 \
  -d source=azure_ad

Response

{
  "has_more": true,
  "data": [
    {
      "id": "grp_8mWqR3nT5vXp",
      "name": "IT-Infrastructure",
      "display_name": "IT Infrastructure Team",
      "description": "All members of the IT Infrastructure department",
      "source": "azure_ad",
      "external_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "is_security_group": true,
      "member_count": 42,
      "synced_at": 1708732800,
      "created_at": 1640995200
    },
    {
      "id": "grp_2kNpL7mS9wYr",
      "name": "Cloud-Admins",
      "display_name": "Cloud Platform Administrators",
      "description": "Members with administrative access to AWS, Azure, and GCP",
      "source": "azure_ad",
      "external_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "is_security_group": true,
      "member_count": 8,
      "synced_at": 1708732800,
      "created_at": 1643673600
    },
    {
      "id": "grp_6jHtK4pR8uWn",
      "name": "On-Call-Rotation",
      "display_name": "On-Call Rotation Group",
      "description": "Engineers currently in the on-call rotation schedule",
      "source": "azure_ad",
      "external_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
      "is_security_group": false,
      "member_count": 15,
      "synced_at": 1708732800,
      "created_at": 1646352000
    }
  ]
}

GET/v1/hr/groups/:id/members

Get group members

This endpoint returns the list of employees who are members of a specific directory group. Supports nested group resolution for Active Directory environments where groups contain other groups as members.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of members returned. Default is 50, maximum is 200.
Name
resolve_nested
Type
boolean
Description
When true, recursively resolves nested group memberships to return all effective members. Defaults to true.

Request

GET

/v1/hr/groups/grp_2kNpL7mS9wYr/members

curl -G http://localhost:3000/v1/hr/groups/grp_2kNpL7mS9wYr/members \
  -H "Authorization: Bearer {token}" \
  -d resolve_nested=true

Response

{
  "group_id": "grp_2kNpL7mS9wYr",
  "group_name": "Cloud-Admins",
  "member_count": 8,
  "resolved_nested": true,
  "data": [
    {
      "id": "emp_7xKpQ2mR4wVb",
      "employee_id": "EMP25048172",
      "email": "jane.smith@acmecorp.com",
      "display_name": "Jane Smith",
      "job_title": "Sr. DevOps Engineer",
      "department": "IT Infrastructure",
      "status": "active",
      "membership_type": "direct"
    },
    {
      "id": "emp_4rTnM6kW2xPq",
      "employee_id": "EMP25052841",
      "email": "david.okafor@acmecorp.com",
      "display_name": "David Okafor",
      "job_title": "Systems Administrator III",
      "department": "IT Infrastructure",
      "status": "active",
      "membership_type": "direct"
    },
    {
      "id": "emp_9wLsK3mR7vNb",
      "employee_id": "EMP25019384",
      "email": "sarah.park@acmecorp.com",
      "display_name": "Sarah Park",
      "job_title": "Cloud Platform Engineer",
      "department": "IT Infrastructure",
      "status": "on_leave",
      "membership_type": "nested",
      "via_group": "Cloud-Platform-Team"
    }
  ]
}