Employees

GET /2023-03-01/xhr/employees

List the individuals (employees, contractors, accountants, and others) listed in the HRIS/Payroll software

Query parameters

  • Optional query parameter. Use to enable server-side filtering of the employment_status attribute. Will only include individuals with that attribute explicitly set (ie if an individuals has a null, it will not be returned if this parameter is set)

    Values are active, inactive, pending, or leave.

Responses

  • 200 application/json

    Success

    Hide response attributes Show response attributes object
    • id string Required

      The Affix-assigned id of the individual

    • remote_id string Required

      the remote system-assigned id of the individual

    • employee_number string | null Required
    • first_name string Required

      the first name of the individual

    • last_name string Required

      the last name of the individual

    • display_full_name string | null Required
    • nationality string | null Required
    • job_title string | null Required
    • work_email string | null Required

      the work email of the individual

    • personal_email string | null Required

      the personal email of the individual

    • mobile_phone_number string | null Required

      +1234567890

    • tax_id string | null Required
    • gender string | null Required

      Values are male, female, not_specified, or null.

    • ethnicity string | null Required

      Values are null, asian, black, hispanic, mixed, not_specified, other, or white.

    • marital_status string | null Required

      other option can include co-habitating, civil partnership, separated, widowed, etc

      Values are single, married, divorced, not_specified, other, or null.

    • date_of_birth string(date) | null Required
    • employment_status string | null Required

      Values are null, active, inactive, pending, or leave.

    • employment_type string | null Required

      Values are null, full_time, part_time, contractor, or other.

    • start_date string(date) | null Required
    • remote_created_at string(date) | null Required
    • termination_date string(date) | null Required
    • avatar string | null Required
    • home_location object | null Required
      Hide home_location attributes Show home_location attributes
      • street_address string | null Required
      • locality string | null Required
      • administrative_area string | null Required

        The administrative area of the address. If US or CA, the two-letter state or province abbreviation. Else, the province / administrative area; such as, Dublin 2 or County Cork

      • country string | null Required

        The ISO-3166-2 two-letter abbreviation of the country. Reference https://en.wikipedia.org/wiki/ISO_3166-2 for more details

        Values are null, BZ, CA, CR, GT, MX, PA, SV, US, AR, BR, CL, PE, AT, BE, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, IE, IM, IS, IT, LI, LT, LU, LV, NL, NO, PL, RO, RU, SE, SK, CN, HK, ID, IL, IN, JP, KR, MO, MY, PH, PS, SG, TH, TR, TW, VN, ZA, AU, or NZ.

      • post_code string | null Required
    • work_location object | null Required
      Hide work_location attributes Show work_location attributes
      • id string | null Required

        The Affix-assigned id of the individual

      • remote_id string | null Required

        the remote system-assigned id of the individual

      • name string | null Required

        System assigned description of the location

      • type string | null Required

        The location's type. In cases where there is no clear mapping, the original value passed through will be returned.

      • address object | null Required
        Hide address attributes Show address attributes
        • street_address string | null Required
        • locality string | null Required
        • administrative_area string | null Required

          The administrative area of the address. If US or CA, the two-letter state or province abbreviation. Else, the province / administrative area; such as, Dublin 2 or County Cork

        • country string | null Required

          The ISO-3166-2 two-letter abbreviation of the country. Reference https://en.wikipedia.org/wiki/ISO_3166-2 for more details

          Values are null, BZ, CA, CR, GT, MX, PA, SV, US, AR, BR, CL, PE, AT, BE, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, IE, IM, IS, IT, LI, LT, LU, LV, NL, NO, PL, RO, RU, SE, SK, CN, HK, ID, IL, IN, JP, KR, MO, MY, PH, PS, SG, TH, TR, TW, VN, ZA, AU, or NZ.

        • post_code string | null Required
    • manager object | null Required
      Hide manager attributes Show manager attributes
      • first_name string | null Required
      • last_name string | null Required
      • id string | null Required

        the Affix-assigned ID of the individual. Nullable if the system only reports the name of the manager; not their ID

      • work_email string | null Required
      • remote_id string | null Required
    • bank_account object | null Required
      Hide bank_account attributes Show bank_account attributes
    • employment_history array[object] | null Required
      Hide employment_history attributes Show employment_history attributes object
    • compensation_history array[object] | null Required
      Hide compensation_history attributes Show compensation_history attributes object
    • custom_fields object | null Required
    • groups array[object] | null Required
      Hide groups attributes Show groups attributes object
      • id string | null Required
      • remote_id string | null Required
      • name string | null Required
      • type string | null Required

        Values are null, department, team, cost_centre, or pay_group.

    • dependents array[object] | null Required
      Hide dependents attributes Show dependents attributes object
    • emergency_contacts array[object] | null Required
      Hide emergency_contacts attributes Show emergency_contacts attributes object
  • 202 application/json

    Accepted + pending (async job started)

    Hide headers attribute Show headers attribute
    • Retry your call after the specified amount of seconds

    Hide response attribute Show response attribute object
  • 401 application/json

    Authentication Error

    Hide response attributes Show response attributes object
    • error string Required

      The type of error

      Value is authentication_error.

    • message string Required

      A descriptive description of the error

    • code string Required

      Values are incorrect_username_or_password, incorrect_mfa_or_otp, reauthentication_required // cookies are now expired, additional_account_setup_required // password reset, etc, captcha_challenge // amazon type1 captcha challenge (currently unsovable), no_valid_accounts // not used currently but reserved for future use, or insufficient_permission // not enough privileges (ie not an admin, or not enough provider scopes on a provider api token for the Affix scopes requested).

  • 429 application/json

    Rate Limited / Too Many Requests

    Hide headers attribute Show headers attribute
    • Retry your call after the specified amount of seconds

    Hide response attribute Show response attribute object
  • 500 application/json

    Server Error

    Hide response attribute Show response attribute object
  • 501 application/json

    Not Implemented

    Hide response attribute Show response attribute object
GET /2023-03-01/xhr/employees
curl \
 -X GET https://api.affixapi.com/2023-03-01/xhr/employees \
 -H "Authorization: $API_KEY"
Response examples (200)
[
  {
    "id": "cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw",
    "remote_id": "19202938",
    "employee_number": "2",
    "first_name": "Greg",
    "last_name": "Hirsch",
    "display_full_name": "Hirsch",
    "nationality": "Irish",
    "job_title": "Software developer",
    "work_email": "[email protected]",
    "personal_email": "[email protected]",
    "mobile_phone_number": "Hirsch",
    "tax_id": "1234567890",
    "gender": "male",
    "ethnicity": "white",
    "marital_status": "single",
    "date_of_birth": "1990-11-10",
    "employment_status": "active",
    "employment_type": "full_time",
    "start_date": "2020-10-11",
    "remote_created_at": "2020-10-11",
    "termination_date": "2021-10-12",
    "avatar": "http://alturl.com/h2h8m",
    "home_location": {
      "street_address": "221 S Main Street",
      "locality": "Yuma",
      "administrative_area": "AZ",
      "country": "IE",
      "post_code": "30691"
    },
    "work_location": {
      "id": "cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw",
      "remote_id": "19202938",
      "name": "NYC Office",
      "type": "office",
      "address": {
        "street_address": "221 S Main Street",
        "locality": "Yuma",
        "administrative_area": "AZ",
        "country": "IE",
        "post_code": "30691"
      }
    },
    "manager": {
      "first_name": "string",
      "last_name": "string",
      "id": "string",
      "work_email": "string",
      "remote_id": "string"
    },
    "bank_account": {
      "account_number": "string",
      "bank_name": "string",
      "bic": "string",
      "holder_name": "string",
      "iban": "string"
    },
    "employment_history": [
      {
        "job_title": "Software Developer",
        "effective_date": "2020-10-11",
        "group_id": "4B9bKBpX5tnwjiG93TAqF7ci",
        "group_remote_id": "49",
        "group_name": "Engineering",
        "manager_id": "string",
        "manager_remote_id": "string"
      }
    ],
    "compensation_history": [
      {
        "pay_rate": 85000,
        "pay_period": "year",
        "pay_frequency": "semimonthly",
        "employment_type": "full_time",
        "currency": "eur",
        "effective_date": "2020-10-11",
        "notes": "Salary Adjustment"
      }
    ],
    "custom_fields": {
      "t_shirt_size": "medium"
    },
    "groups": [
      {
        "id": "4B9bKBpX5tnwjiG93TAqF7ci",
        "remote_id": "df6c28e8",
        "name": "backend",
        "type": "team"
      },
      {
        "id": "132Xpnw2a38aaQG93TAqF7ci",
        "remote_id": "355c65922637",
        "name": "engineering",
        "type": "department"
      }
    ],
    "dependents": [
      {
        "name": "string",
        "relationship": "string"
      }
    ],
    "emergency_contacts": [
      {
        "first_name": "string",
        "last_name": "string",
        "relationship": "string",
        "mobile_phone_number": "string",
        "primary_contact": true
      }
    ]
  }
]
Response examples (202)
# Headers
Retry-After: 42

# Payload
{
  "message": "string"
}
Response examples (401)
{
  "error": "authentication_error",
  "message": "Your password is incorrect",
  "code": "incorrect_username_or_password"
}
Response examples (429)
# Headers
Retry-After: 42

# Payload
{
  "message": "string"
}
Response examples (500)
{
  "message": "string"
}
Response examples (501)
{
  "message": "string"
}