Employee

Authentication: All endpoints require an Authorization: Bearer <access token> header.

Most endpoints require an X-Company-ID: <company_id> header to scope requests to a specific company. This is the recommended header for most API operations.

Some endpoints require an X-Location-ID: <location_id> header when the query doesn't accept a locationId parameter.

See Authentication for details on how to obtain and use these headers.

Query All Employees

Get a list of employees by status.

Query Parameters:

Parameter Type Required Description
$statuses EmployeeStatus! No Filter by employee status
$rosterable Boolean No Only include rosterable employees
$visible Boolean No Only include visible employees
$onlyDeleted Boolean No Only include archived employees

Employee Status Values:

Status Description
Active Active employee
Terminated Employment ended
Onboarding In the process of onboarding
Invited Invited but not yet accepted their onboarding invite
Draft Employee shell record, can be converted into an invite

GraphQL Query

query ListEmployees($statuses: [EmployeeStatus!], $rosterable: Boolean, $visible: Boolean) {
  employees(statuses: $statuses, rosterable: $rosterable, visible: $visible) {
    id
    fullName
    workEmail
    status
    rosterable
    visible
    person {
      mobile
      email
      dateOfBirth
    }
    location {
      id
      name
    }
    position {
      id
      name
    }
    startDate
    terminatedAt
    modifiedAt
  }
}

Example Variables

{
  "statuses": ["Active", "Terminated", "Onboarding", "Invited"],
  "rosterable": true,
  "visible": true
}

Example Response

{
  "data": {
    "employees": [
      {
        "id": "72908",
        "fullName": "Craig Bussell",
        "workEmail": "craig_bussell_8hs54fg7@example.com",
        "status": "Active",
        "rosterable": true,
        "visible": true,
        "person": {
          "mobile": "0493811112",
          "email": "craig_bussell_8hs54fg7@gmail.com",
          "dateOfBirth": "2023-09-21"
        },
        "location": {
          "id": "12325",
          "name": "Integration Sandbox"
        },
        "position": {
          "id": "18101",
          "name": "General Manager"
        },
        "startDate": "2024-05-22",
        "terminatedAt": null,
        "modifiedAt": "2024-06-06T22:18:42.422Z"
      },
      {
        "id": "74444",
        "fullName": "James Invited-from-reserve-bench",
        "workEmail": "jamie_87a234wsdfgvqe@example.com",
        "status": "Invited",
        "rosterable": true,
        "visible": true,
        "person": {
          "mobile": "0423888192",
          "email": "7e65c421-d91e-48b0-b925-b4950aa8da3b@invite.roubler.com",
          "dateOfBirth": "2000-06-26"
        },
        "location": {
          "id": "12325",
          "name": "Integration Sandbox"
        },
        "position": {
          "id": "18100",
          "name": "Full Stack Developer"
        },
        "startDate": "2024-04-15",
        "terminatedAt": null,
        "modifiedAt": "2024-06-06T22:18:42.262Z"
      },
      {
        "id": "73542",
        "fullName": "Kate Mallone",
        "workEmail": "Kate_Mallone_4278930qh@example.com",
        "status": "Onboarding",
        "rosterable": true,
        "visible": true,
        "person": {
          "mobile": "0435728441",
          "email": "kate_mallone_4278930qh@gmail.com",
          "dateOfBirth": "2000-06-01"
        },
        "location": {
          "id": "12325",
          "name": "Integration Sandbox"
        },
        "position": {
          "id": "18102",
          "name": "Product Manager"
        },
        "startDate": null,
        "terminatedAt": null,
        "modifiedAt": "2024-06-07T04:42:46.299Z"
      }
    ]
  }
}

Query Archived Employees

Get a list of archived employees.

Query Parameters:

Parameter Type Required Description
$onlyDeleted Boolean Yes Set to true to get deleted employees

GraphQL Query

query ListEmployees($onlyDeleted: Boolean!) {
  employees(onlyDeleted: $onlyDeleted) {
    id
    fullName
    workEmail
    status
    rosterable
    visible
    person {
      mobile
      email
      dateOfBirth
    }
    location {
      id
      name
    }
    position {
      id
      name
    }
    startDate
    terminatedAt
    modifiedAt
  }
}

Example Variables

{
  "onlyDeleted": true
}

Example Response

{
  "data": {
    "employees": [
      {
        "id": "73545",
        "fullName": "Ken Robertson",
        "workEmail": "ken_robertson_a7890qwehcc@roubler.com",
        "status": "Active",
        "rosterable": true,
        "visible": true,
        "person": {
          "mobile": null,
          "email": "2256f406-a769-4f9f-b6cf-bc3745da98c7@invite.roubler.com",
          "dateOfBirth": null
        },
        "location": {
          "id": "12325",
          "name": "Integration Sandbox"
        },
        "position": null,
        "startDate": null,
        "terminatedAt": null,
        "modifiedAt": "2024-06-06T22:10:45.174Z"
      }
    ]
  }
}

Query Comprehensive Employee Details

Query employees with comprehensive details including pay rules, bank accounts, superannuation, and custom fields (Australian context example).

Additional Fields Available:

  • Person Details: firstName, lastName, gender, alternatePhone, residentialAddress, postalAddress (Person)
  • Regional Information: Region-specific tax and compliance fields (see note below)
  • Pay Information: payLevel, payRule with version history (PayLevel, PayRule)
  • Financial: bankAccounts, superAccounts (BankAccount, SuperAccount)
  • Custom Data: userDefinedFields (UserDefinedField)
  • Compliance: employeeRequirements (EmployeeRequirement)
  • Status Fields: hasBiometricConsent, residencyStatus, anniversaryDate

Regional Fields Note:

The example below uses regionalAU for Australian tax and compliance data. Similar regional fields are available for other regions:

Each regional field contains country-specific information such as tax file numbers, national insurance details, CPF information, etc.

For the complete Employee type reference and all available fields, see the GraphQL Schema Reference.

GraphQL Query

query ListEmployees($statuses: [EmployeeStatus!], $rosterable: Boolean, $visible: Boolean) {
  employees(statuses: $statuses, rosterable: $rosterable, visible: $visible) {
    id
    startDate
    anniversaryDate
    workEmail
    status
    rosterable
    visible
    hasBiometricConsent
    residencyStatus
    person {
      firstName
      lastName
      fullName
      gender
      mobile
      alternatePhone
      email
      dateOfBirth
      residentialAddress {
        line1
        line2
        city
        suburb
        state
        postalCode
        country
      }
      postalAddress {
        line1
        line2
        city
        suburb
        state
        postalCode
        country
      }
      regionalAU {
        australiaHomeAddress
        doesWantToClaimCarerTax
        doesWantToClaimSeniorPensionerTax
        hasFsDebt
        hasHelpSslTsl
        isAustralianForTaxPurposes
        paidBasis
        previousFamilyName
        taxDeclaration
        taxFileNumber
        title
        hasWorkingHolidayVisa
        previousResidentialCountry
        hasWithholdingVariation
        taxVariation
      }
    }
    location {
      id
      name
    }
    position {
      id
      name
    }
    payLevel {
      id
      name
      description
      versions {
        id
        name
        description
        commencedAt
      }
    }
    payRule {
      id
      name
      description
      versions {
        id
        name
        description
        commencedAt
      }
    }
    bankAccounts {
      id
      accountName
      accountNumber
      branch
    }
    superAccounts {
      id
      selfManaged
      fundName
    }
    userDefinedFields {
      userDefinedFieldSetting {
        name
        label
        dataType
        fieldLevel
        available
      }
      value
      ownerId
      ownerType
    }
    employeeRequirements {
      id
      name
      state
      requirement {
        id
        name
        abbreviation
        evidence
        expires
      }
    }
    terminatedAt
    modifiedAt
  }
}

Example Variables

{
  "statuses": ["Active", "Terminated", "Onboarding", "Invited"],
  "rosterable": true,
  "visible": true
}

Example Response

{
  "data": {
    "employees": [
      {
        "id": "72908",
        "startDate": "2024-05-22",
        "anniversaryDate": null,
        "workEmail": "craig_bussell_8hs54fg7@example.com",
        "status": "Active",
        "rosterable": true,
        "visible": true,
        "hasBiometricConsent": false,
        "residencyStatus": null,
        "person": {
          "firstName": "Craig",
          "lastName": "Bussell",
          "fullName": "Craig Bussell",
          "gender": "Male",
          "mobile": "0493811112",
          "alternatePhone": null,
          "email": "craig_bussell_8hs54fg7@gmail.com",
          "dateOfBirth": "2023-09-21",
          "residentialAddress": {
            "line1": "123 Real Place",
            "line2": "Suites on Real Place",
            "city": "Brisbane",
            "suburb": "Brisbane",
            "state": "QLD",
            "postalCode": "4000",
            "country": "AU"
          },
          "postalAddress": null,
          "regionalAU": {
            "australiaHomeAddress": null,
            "doesWantToClaimCarerTax": null,
            "doesWantToClaimSeniorPensionerTax": null,
            "hasFsDebt": null,
            "hasHelpSslTsl": null,
            "isAustralianForTaxPurposes": true,
            "paidBasis": null,
            "previousFamilyName": null,
            "taxDeclaration": "NotClaimingException",
            "taxFileNumber": "123456782",
            "title": null,
            "hasWorkingHolidayVisa": null,
            "previousResidentialCountry": null,
            "hasWithholdingVariation": null,
            "taxVariation": null
          }
        },
        "location": {
          "id": "12325",
          "name": "Integration Sandbox"
        },
        "position": {
          "id": "18101",
          "name": "General Manager"
        },
        "payLevel": null,
        "payRule": {
          "id": "538",
          "name": "Standard",
          "description": "Standard pay rules",
          "versions": [
            {
              "id": "521",
              "name": "Ordinary, overtime (8+) and weekend hours",
              "description": null,
              "commencedAt": "2021-01-01"
            }
          ]
        },
        "bankAccounts": [
          {
            "id": "98310",
            "accountName": "CraigB",
            "accountNumber": "123123123",
            "branch": "013013"
          }
        ],
        "superAccounts": [
          {
            "id": "23851",
            "selfManaged": false,
            "fundName": "AustralianSuper"
          }
        ],
        "userDefinedFields": [
          {
            "userDefinedFieldSetting": {
              "name": "Has relevant qualifications?",
              "label": "Do you have the latest qualification?",
              "dataType": "checkbox",
              "fieldLevel": "optional",
              "available": true
            },
            "value": "true",
            "ownerId": "72908",
            "ownerType": "employee"
          }
        ],
        "employeeRequirements": [],
        "terminatedAt": null,
        "modifiedAt": "2024-06-06T22:18:42.422Z"
      }
    ]
  }
}

Add Employee

Create a new employee record.

Input Fields:

Field Required Description
locationId Yes The location where the employee will be assigned
permissionGroupId Yes The permission group for the employee (typically "1" for employee permissions)
person.firstName Yes Employee's first name
person.lastName Yes Employee's last name
person.email Yes Employee's email address
positionId No Job position/title
startDate No Employment start date
anniversaryDate No Anniversary date
bankAccounts No Banking information for payroll
person.dateOfBirth No Date of birth
person.residentialAddress No Residential address
person.regionalAU No Region-specific tax/compliance data (or other regional fields)

Regional Fields Note:

The example below uses regionalAU for Australian tax and compliance data. Similar regional fields are available for other regions:

For the complete input type reference, see AddEmployeeInput and AddEmployeePersonInput.

GraphQL Mutation

mutation AddEmployee($input: AddEmployeeInput!) {
  addEmployee(input: $input) {
    id
    fullName
    modifiedAt
  }
}

Example Variables

{
  "input": {
    "anniversaryDate": "2024-05-30",
    "bankAccounts": {
      "accountName": "BSnell",
      "branch": "013013",
      "accountNumber": "123432121"
    },
    "locationId": "12326",
    "permissionGroupId": "1",
    "payLevelId": null,
    "payRuleId": null,
    "positionId": "18103",
    "onboardedAt": null,
    "visible": true,
    "probationDate": "2024-09-24",
    "recordProbationPeriod": true,
    "person": {
      "dateOfBirth": "2000-04-23",
      "firstName": "Bridget",
      "lastName": "Snell",
      "email": "bridget.snell@example.com",
      "postalAddress": {},
      "residentialAddress": {
        "line1": "123 Real Place",
        "line2": null,
        "suburb": "Brisbane",
        "state": "Queensland",
        "postalCode": "4000",
        "country": "Australia"
      },
      "preferredName": null,
      "regionalAU": {
        "australiaHomeAddress": null,
        "doesWantToClaimCarerTax": null,
        "doesWantToClaimSeniorPensionerTax": null,
        "hasFsDebt": null,
        "hasHelpSslTsl": null,
        "isAustralianForTaxPurposes": true,
        "paidBasis": null,
        "previousFamilyName": null,
        "taxDeclaration": "NotClaimingException",
        "taxFileNumber": "123456782",
        "title": null,
        "hasWorkingHolidayVisa": null,
        "previousResidentialCountry": null,
        "hasWithholdingVariation": null,
        "taxVariation": null,
        "hasClaimExemptionUnderEighteen": null,
        "hasClaimExemptionPension": null
      }
    }
  }
}

Example Response

{
  "data": {
    "addEmployee": {
      "id": "76144",
      "fullName": "Bridget Snell",
      "modifiedAt": "2024-06-11T02:43:14.538Z"
    }
  }
}

Add Draft Employee

Create a draft employee record. Draft employees can later be converted into full employee invites or used to reserve a spot for potential hires. This method replaces adding applicants to the reserve bench.

Mutation Parameters:

Parameter Type Required Description
input AddEmployeeInput! Yes Input object containing employee details
input.locationId ID! Yes ID of the location to assign the employee to
input.permissionGroupId ID! Yes Permission group ID (typically "1" for employee permissions)
input.recordProbationPeriod Boolean! Yes Whether to record probation period (typically false for drafts)
input.probationDate Date No End date of probation period (if recordProbationPeriod is true)
input.person.firstName String! Yes Employee's first name
input.person.lastName String! Yes Employee's last name
input.person.email String! Yes Employee's email address
input.status EmployeeStatus No Employee status (set to "Draft" for draft employees)

Response Fields:

Field Description
id Unique identifier for the created employee
fullName Full name of the employee
status Employee status (will be "Draft")

Implementation Notes:

  • Set status to "Draft" to create a draft employee
  • Draft employees can later be converted to invites by managers
  • The email address must be unique and not already associated with an existing employee
  • This is the preferred method for adding applicants to the reserve bench
  • Draft employees do not have access to the system until converted to an invite
  • locationId, permissionGroupId, and recordProbationPeriod are required fields
  • For draft employees, typically set recordProbationPeriod to false
  • To create a full employee record with all details, see the Add Employee section

GraphQL Mutation

mutation AddEmployee($input: AddEmployeeInput!) {
  addEmployee(input: $input) {
    id
    fullName
    status
  }
}

Example Variables

{
  "input": {
    "locationId": "12325",
    "permissionGroupId": "1",
    "recordProbationPeriod": false,
    "person": {
      "firstName": "Marcus",
      "lastName": "Connell",
      "email": "marcus.connell@example.com"
    },
    "status": "Draft"
  }
}

Example Response

{
  "data": {
    "addEmployee": {
      "id": "77435",
      "fullName": "Marcus Connell",
      "status": "Draft"
    }
  }
}

Update Employee

Update an existing employee record. Only include the fields you want to change - partial updates are supported.

Input Fields:

Only include the fields you want to change - partial updates are supported.

Field Required Description
id Yes The employee ID to update
startDate No Employment start date
anniversaryDate No Anniversary date
rosterable No Whether the employee can be rostered
visible No Whether the employee is visible
positionId No Job position/title
payLevelId No Pay level
payRuleId No Pay rule
bankAccounts No Banking information
person.firstName No Employee's first name
person.lastName No Employee's last name
person.email No Employee's email address
person.residentialAddress No Residential address
person.postalAddress No Postal address
person.regionalAU No Australian tax/compliance data (or other regional fields)

Regional Fields Note:

The example below uses regionalAU for Australian tax and compliance data. Similar regional fields are available for other regions:

For the complete input type reference, see UpdateEmployeeInput and UpdateEmployeePersonInput.

GraphQL Mutation

mutation UpdateEmployee($input: UpdateEmployeeInput!) {
  updateEmployee(input: $input) {
    id
    fullName
    modifiedAt
  }
}

Example Variables

{
  "input": {
    "id": "76144",
    "anniversaryDate": "2024-05-30",
    "startDate": "2024-05-30",
    "rosterable": true,
    "bankAccounts": {
      "accountName": "BSnell",
      "branch": "013013",
      "accountNumber": "123432121"
    },
    "person": {
      "dateOfBirth": "2000-04-23",
      "firstName": "Bridget",
      "lastName": "Snell",
      "email": "bridget.snell@example.com",
      "postalAddress": {},
      "residentialAddress": {
        "line1": "456 Real Place",
        "line2": null,
        "suburb": "Brisbane",
        "state": "Queensland",
        "postalCode": "4000",
        "country": "Australia"
      },
      "preferredName": null,
      "regionalAU": {
        "australiaHomeAddress": null,
        "doesWantToClaimCarerTax": null,
        "doesWantToClaimSeniorPensionerTax": null,
        "hasFsDebt": null,
        "hasHelpSslTsl": null,
        "isAustralianForTaxPurposes": true,
        "paidBasis": null,
        "previousFamilyName": null,
        "taxDeclaration": "NotClaimingException",
        "taxFileNumber": "123456782",
        "title": null,
        "hasWorkingHolidayVisa": null,
        "previousResidentialCountry": null,
        "hasWithholdingVariation": null,
        "taxVariation": null,
        "hasClaimExemptionUnderEighteen": null,
        "hasClaimExemptionPension": null
      }
    }
  }
}

Example Response

{
  "data": {
    "updateEmployee": {
      "id": "76144",
      "fullName": "Bridget Snell",
      "modifiedAt": "2024-06-11T03:36:04.538Z"
    }
  }
}