Create an employee

POST/hris/{connection_id}/employee

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

Payload

idstring
created_atdate-time
(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
updated_atdate-time
(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
namestring
first_namestring
last_namestring
emails array
titlestring
job_idstring
the hris_job (position) this employee holds; their primary job when they hold more than one
manager_idstring
employment_status enum
Valid values:
"ACTIVE"
"INACTIVE"
gender enum
Valid values:
"MALE"
"FEMALE"
"INTERSEX"
"TRANS"
"NON_BINARY"
telephones array
date_of_birthdate-time
YYYYMM/DD
employee_numberstring
the company's ID for this employee
hired_atdate-time
The employee's start date (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
terminated_atdate-time
(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
termination_reasonstring
marital_status enum
Valid values:
"MARRIED"
"SINGLE"
employment_type enum
Valid values:
"FULL_TIME"
"PART_TIME"
"CONTRACTOR"
"INTERN"
"CONSULTANT"
addressobject
language_localestring
currencystring
timezonestring
image_urlstring
This link expires after 1 hour.
company_idstring
(reference to HrisCompany)
pronounsstring
employee_roles enum array
Valid values:
"ADMIN"
"MANAGER"
"RECRUITER"
"SALESREP"
"INTERVIEWER"
compensation array
salutationstring
Mr. Mrs. Ms.
biostring
ssn_sinstring
groups array
Which 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.
locations array
metadata array
storage_quota_allocatednumber
storage_quota_usednumber
storage_quota_availablenumber
relationships array
the employee's personal relationships (eg. emergency contacts, spouse, dependants, ...)
has_mfaboolean
does the user/employee have multi-factor authentication enabled
timeoff_days_totalnumber
Total time off allowance for the current leave period, in days (when reported by the provider)
timeoff_days_usednumber
Time off days used or booked in the current leave period (when reported by the provider)
flsa_status enum
Valid values:
"EXEMPT"
"NON_EXEMPT"
"SALARIED_NONEXEMPT"
"OWNER"
US Fair Labor Standards Act classification
pay_frequency enum
Valid values:
"ONE_TIME"
"DAY"
"QUARTER"
"YEAR"
"HOUR"
how often the employee is paid (eg. BIWEEKLY)

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)
namestringNo
first_namestringNo
last_namestringNo
emailsHrisEmail[]No
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)NoYYYYMM/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[].namestringNo
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)
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[].namestringNo
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)
metadataHrisMetadata[]No
metadata[].idstringNo
metadata[].valueobjectNo
metadata[].namespacestringNo
metadata[].formatenumNoValues: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE_SELECT, MULTIPLE_SELECT, MEASUREMENT, PRICE, YES_NO, CURRENCY, URL
metadata[].extra_dataobjectNo
metadata[].slugstringNo
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: 'POST',
  url: 'https://api.unified.to/hris/5de520f96e439b002043d8dc/employee',
  headers: {
    authorization: 'bearer .....'
  },
  data: undefined,
  params: {
    fields: '',
    raw: '',
  }
};

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