Retrieve an employee

Updated:

GET/hris/{connection_id}/employee/{id}

Retrieves a single HrisEmployee by its id. Obtain id values from the corresponding list endpoint. Use fields to return only the fields you need.

Parameters

fieldsstring array
Fields to return
rawstring
Raw parameters to include in the 3rd-party request. Encoded as a URL component. eg. raw parameters: foo=bar&zoo=bar -> raw=foo%3Dbar%26zoo%3Dbar
connection_idstring required
ID of the connection
idstring required
ID of the Employee

Returns

Response fieldTypeRequiredDescription
idstringNo
created_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
updated_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
namestringNoThe employee's full name
first_namestringNoThe employee's first (given) name
last_namestringNoThe employee's last (family) name
emailsHrisEmail[]NoThe employee's email addresses
emails[].emailstringYes
emails[].typeenumNoValues: WORK, HOME, OTHER
titlestringNo
job_idstringNothe hris_job (position) this employee holds; their primary job when they hold more than one
manager_idstringNo
employment_statusenumNoValues: ACTIVE, INACTIVE
genderenumNoValues: MALE, FEMALE, INTERSEX, TRANS, NON_BINARY
telephonesHrisTelephone[]No
telephones[].telephonestringYes
telephones[].typeenumNoValues: WORK, HOME, OTHER, FAX, MOBILE
date_of_birthstring (date-time)NoYYYY-MM-DD
employee_numberstringNothe company's ID for this employee
hired_atstring (date-time)NoThe employee's start date (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
terminated_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
termination_reasonstringNo
marital_statusenumNoValues: MARRIED, SINGLE
employment_typeenumNoValues: FULL_TIME, PART_TIME, CONTRACTOR, INTERN, CONSULTANT, VOLUNTEER, CASUAL, SEASONAL, FREELANCE, OTHER
addressobjectNo
address.address1stringNo
address.address2stringNo
address.citystringNo
address.regionstringNo
address.region_codestringNo
address.postal_codestringNo
address.countrystringNo
address.country_codestringNoISO 2-digit country code
language_localestringNo
currencystringNo
timezonestringNo
image_urlstringNoThis link expires after 1 hour.
company_idstringNo(reference to HrisCompany)
pronounsstringNo
employee_rolesenumNoValues: ADMIN, MANAGER, RECRUITER, SALESREP, INTERVIEWER, USER, EMPLOYEE
compensationHrisCompensation[]No
compensation[].typeenumNoValues: SALARY, BONUS, STOCK_OPTIONS, EQUITY, OTHER, HOURLY, COMMISSION
compensation[].amountnumberNo
compensation[].currencystringNo
compensation[].frequencyenumNoValues: ONE_TIME, DAY, QUARTER, YEAR, HOUR, MONTH, WEEK, BIWEEKLY, SEMIMONTHLY
compensation[].group_idstringNo(reference to HrisGroup)
compensation[].notesstringNo
salutationstringNoMr. Mrs. Ms.
biostringNo
ssn_sinstringNo
groupsHrisGroup[]NoWhich groups/teams/units that this employee/user belongs to. May not have all of the Group fields present, but should have id, name, or email.
groups[].idstringNo
groups[].created_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
groups[].updated_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
groups[].namestringNoThe name of the group (e.g. a team or department)
groups[].descriptionstringNo
groups[].parent_idstringNo
groups[].typeenumNoValues: TEAM, GROUP, DEPARTMENT, DIVISION, BUSINESS_UNIT, BRANCH, SUB_DEPARTMENT, PAY_GROUP
groups[].user_idsstring[]No(reference to HrisEmployee)
groups[].manager_idsstring[]No
groups[].is_activebooleanNo
groups[].company_idstringNo(reference to HrisCompany)
groups[].pay_frequencyenumNopay cycle when type is PAY_GROUP Values: ONE_TIME, DAY, QUARTER, YEAR, HOUR, MONTH, WEEK, BIWEEKLY, SEMIMONTHLY
groups[].next_paid_atstring (date-time)Nonext pay date when type is PAY_GROUP (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
groups[].metadataHrisMetadata[]No
groups[].metadata[].idstringNoThe ID of the custom field definition (from the metadata/metadata endpoint).
groups[].metadata[].valueobjectNoThe field's value, typed by format: DATE as ISO-8601 (YYYY-MM-DD, or YYYY-MM-DDTHH:MM:SSZ for date-times); NUMBER, PRICE and CURRENCY as a number; BOOLEAN and YES_NO as true/false; MULTIPLE_SELECT as an array of option values; otherwise a string.
groups[].metadata[].namespacestringNo
groups[].metadata[].formatenumNoThe data type of the custom field, which determines how value is formatted. Values: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE_SELECT, MULTIPLE_SELECT, MEASUREMENT, PRICE, YES_NO, CURRENCY, URL
groups[].metadata[].extra_dataobjectNo
groups[].metadata[].slugstringNoThe integration's API name (key) of an existing custom field. List valid slugs for this object with the metadata/metadata endpoint; unknown slugs are rejected by the integration.
locationsHrisLocation[]No
locations[].idstringNo
locations[].created_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
locations[].updated_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
locations[].namestringNoThe name of the location
locations[].descriptionstringNo
locations[].addressHrisLocation_addressNo
locations[].address.address1stringNo
locations[].address.address2stringNo
locations[].address.citystringNo
locations[].address.regionstringNo
locations[].address.region_codestringNo
locations[].address.postal_codestringNo
locations[].address.countrystringNo
locations[].address.country_codestringNoISO 2-digit country code
locations[].parent_idstringNo
locations[].external_identifierstringNo
locations[].telephonesHrisTelephone[]No
locations[].telephones[].telephonestringYes
locations[].telephones[].typeenumNoValues: WORK, HOME, OTHER, FAX, MOBILE
locations[].timezonestringNo
locations[].currencystringNo
locations[].language_localestringNo
locations[].is_activebooleanNo
locations[].is_hqbooleanNoif this location is the headquarters of the company
locations[].company_idstringNo(reference to HrisCompany)
locations[].metadataHrisMetadata[]No
locations[].metadata[].idstringNoThe ID of the custom field definition (from the metadata/metadata endpoint).
locations[].metadata[].valueobjectNoThe field's value, typed by format: DATE as ISO-8601 (YYYY-MM-DD, or YYYY-MM-DDTHH:MM:SSZ for date-times); NUMBER, PRICE and CURRENCY as a number; BOOLEAN and YES_NO as true/false; MULTIPLE_SELECT as an array of option values; otherwise a string.
locations[].metadata[].namespacestringNo
locations[].metadata[].formatenumNoThe data type of the custom field, which determines how value is formatted. Values: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE_SELECT, MULTIPLE_SELECT, MEASUREMENT, PRICE, YES_NO, CURRENCY, URL
locations[].metadata[].extra_dataobjectNo
locations[].metadata[].slugstringNoThe integration's API name (key) of an existing custom field. List valid slugs for this object with the metadata/metadata endpoint; unknown slugs are rejected by the integration.
metadataHrisMetadata[]No
metadata[].idstringNoThe ID of the custom field definition (from the metadata/metadata endpoint).
metadata[].valueobjectNoThe field's value, typed by format: DATE as ISO-8601 (YYYY-MM-DD, or YYYY-MM-DDTHH:MM:SSZ for date-times); NUMBER, PRICE and CURRENCY as a number; BOOLEAN and YES_NO as true/false; MULTIPLE_SELECT as an array of option values; otherwise a string.
metadata[].namespacestringNo
metadata[].formatenumNoThe data type of the custom field, which determines how value is formatted. Values: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE_SELECT, MULTIPLE_SELECT, MEASUREMENT, PRICE, YES_NO, CURRENCY, URL
metadata[].extra_dataobjectNo
metadata[].slugstringNoThe integration's API name (key) of an existing custom field. List valid slugs for this object with the metadata/metadata endpoint; unknown slugs are rejected by the integration.
storage_quota_allocatednumberNo
storage_quota_usednumberNo
storage_quota_availablenumberNo
relationshipsHrisEmployeerelationship[]Nothe employee's personal relationships (eg. emergency contacts, spouse, dependants, ...)
relationships[].namestringNo
relationships[].first_namestringNo
relationships[].last_namestringNo
relationships[].emailsHrisEmail[]No
relationships[].emails[].emailstringYes
relationships[].emails[].typeenumNoValues: WORK, HOME, OTHER
relationships[].telephonesHrisTelephone[]No
relationships[].telephones[].telephonestringYes
relationships[].telephones[].typeenumNoValues: WORK, HOME, OTHER, FAX, MOBILE
relationships[].addressHrisEmployeerelationship_addressNo
relationships[].address.address1stringNo
relationships[].address.address2stringNo
relationships[].address.citystringNo
relationships[].address.regionstringNo
relationships[].address.region_codestringNo
relationships[].address.postal_codestringNo
relationships[].address.countrystringNo
relationships[].address.country_codestringNoISO 2-digit country code
relationships[].typeenumNoValues: EMERGENCY, SPOUSE, CHILD, PARENT, SIBLING, FRIEND, OTHER
relationships[].is_dependentbooleanNo
relationships[].is_beneficiarybooleanNo
relationships[].start_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
relationships[].end_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
has_mfabooleanNodoes the user/employee have multi-factor authentication enabled
timeoff_days_totalnumberNoTotal time off allowance for the current leave period, in days (when reported by the provider)
timeoff_days_usednumberNoTime off days used or booked in the current leave period (when reported by the provider)
flsa_statusenumNoUS Fair Labor Standards Act classification Values: EXEMPT, NON_EXEMPT, SALARIED_NONEXEMPT, OWNER
pay_frequencyenumNohow often the employee is paid (eg. BIWEEKLY) Values: ONE_TIME, DAY, QUARTER, YEAR, HOUR, MONTH, WEEK, BIWEEKLY, SEMIMONTHLY

Errors

Errors return the HTTP status code and a JSON body with statusCode, error (the short label) and message (a human-readable detail).

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many requests to unified.to API; max requests per minute: N"
}
StatusErrorMeaning
400Bad RequestThe request was malformed or failed validation.
401UnauthorizedThe connection is likely broken; re-authorize it.
403ForbiddenThe connection is missing permissions or scopes.
404Not FoundThe requested resource does not exist.
429Too Many RequestsRate limit exceeded (see the two sources below).
500Internal Server ErrorAn unexpected error occurred.
501Not ImplementedNot supported by this integration.

Errors from the underlying integration pass through: the integration's status comes back as ours (429, 401, 403, 404 or 5xx), usually with its message. When the integration's error body is unclear, Unified extracts what it can and returns a clearer message.

429 Too Many Requests

A 429 has two possible sources:

  • The integration's own rate limit, passed through.
  • Unified's workspace limit: a rolling 60 seconds, set by plan, with the message Too many requests to unified.to API; max requests per minute: N.
const options = {
  method: 'GET',
  url: 'https://api.unified.to/hris/5de520f96e439b002043d8dc/employee/5de520f96e439b002043d8d8',
  headers: {
    authorization: 'bearer .....'
  },
  params: {
    fields: '',
    raw: '',
  }
};

const results = await axios.request(options);
Are we missing anything? Let us know
Was this page helpful?