Skip to content
English
Contact Support
Sign In
  • There are no suggestions because the search field is empty.

API Employee synchronization

The Employee Sync API allows you to programmatically synchronize your institution's employee list with FaceUp.

Keeping employee data up to date is critical for effective case management, investigations, and compliance processes. FaceUp’s Employee Synchronization API allows organizations to automatically sync their employee directory from an external system into FaceUp, ensuring that case handling and investigations always reflect the current organizational structure.

While FaceUp offers native integrations that allow you to connect employee data in just a few clicks (see our native integrations here: https://www.faceup.com/en/integrations), the Employee Synchronization API provides a flexible alternative for connecting systems we do not yet support natively, including Workday, ADP, SAP, and Oracle.

For HR, compliance, and ethics teams, employee synchronization helps ensure that:

  • Cases and investigations are connected to the right people, whether an employee is the reporter, the subject of a report, or a witness

  • Cases are handled with the correct organizational context, including departments, teams, and specific personnel within your org

  • Administrators can view cases linked to specific employees and more easily identify trends or recurring issues within a team or department

  • Manual administration and data inconsistencies are reduced, especially in larger or fast-changing organizations

By automating employee synchronization, organizations can maintain a reliable, audit-ready reporting environment without relying on manual updates or spreadsheets. This is particularly valuable for growing companies and enterprise environments where employee data changes frequently.

The following section explains how to implement employee synchronization using FaceUp’s API.

Prerequisites

To communicate with the FaceUp API, you need to obtain your institution's API key and data hosting region. To do so, check the related article.

Endpoint

URL: https://www.api.faceup.com/graphql

Method: POST

Required headers

Header Description Example
Authorization Your API key fui_abc123...
Content-Type Must be application/json application/json
X-Region Your data hosting region eu-west-1, us-east-1, ...

GraphQL mutation

mutation SyncEmployees($input: SyncEmployeesInput!) {
syncEmployees(input: $input) {
success
}
}

Input types

input SyncEmployeesInput {
employees: [EmployeeAttributesInput!]!
}

input EmployeeAttributesInput {
name: String!
email: Email!
status: EmployeeStatus!
location: String
department: String
jobTitle: String
supervisor: String
}

enum EmployeeStatus {
Active
Inactive
}

Employee fields

Field Type Required Max length Description
name String Yes 255 Employee's full name
email Email Yes - Employee's email address (used as unique identifier)
status Enum Yes - Active or Inactive
location String No 255 Office location or city
department String No 255 Department name
jobTitle String No 255 Job title or position
supervisor String No 255 Name of the employee's supervisor

Behavior

All-or-nothing behavior

The sync operation uses an all-or-nothing approach:
  • Success: If all employees pass validation, the entire batch is synced and success: true is returned
  • Failure: If any employee fails validation, no employees are synced and an errors array is returned

Upsert logic

The operation uses upsert (update or insert) logic based on the employee's email address:
  • New employee: If no employee with the given email exists, a new record is created
  • Existing employee: If an employee with the given email already exists, their data is updated
  • Unchanged employees: Employees not included in the sync request remain unchanged

Limits & rate limiting

  • Rate limit: 10 requests per second
  • Maximum employees per request: 1,000
If you need to sync more than 1,000 employees, split them into multiple requests.

Example cURL request

curl -X POST https://www.api.faceup.com/graphql \
-H "Content-Type: application/json" \
-H"Authorization: fui_your-api-key-here"\
-H "X-Region: your-region-here" \
-d'{
"query": "mutation SyncEmployees($input: SyncEmployeesInput!) { syncEmployees(input: $input) { success } }",
"variables": {
"input": {
"employees": [
{
"name": "John Smith",
"email": "john.smith@example.com",
"status": "Active",
"location": "New York",
"department": "Marketing",
"jobTitle": "Marketing Specialist",
"supervisor": "Jane Wilson"
},
{
"name": "Emily Johnson",
"email": "emily.johnson@example.com",
"status": "Inactive"
}
]
}
}
}'

Response

Success response

{
"data": {
"syncEmployees": {
"success": true
}
}
}

Error response

{
"errors": [
{
"message": "You can only import up to 1000 employees at once."
}
]
}