Create Employees
/unified/hris/employees
Partial response — use the "get" endpoint for the full object.
Query Parameters
Refer Specifying query parameters in Truto APIs
This represents the company
2 supported2 notes
The company to use, referencing companies.id. Optional: when omitted the account's company is looked up automatically. The request fails if the account can see more than one company and none is given.
The Paychex company to use, referencing companies.id (Paychex companyId). A company pinned on the connection (company_id in the integrated account context) always wins and this parameter is then ignored. Otherwise, when omitted, the credential's companies are looked up and the single company with API permission is used. The request fails with a 400 when no company can be resolved (the credential sees more than one company with API permission, none, or 100 or more companies).
The unique identifier for companies
Flat alternative to company.id.
2 supported
Show Truto-specific parameters
The ID of the integrated account to use for the request.
62f44730-dd91-461e-bd6a-aedd9e0ad79dThe format of the response.
unifiedreturns the response with unified mappings applied.rawreturns the unprocessed, raw response from the remote API.normalizedapplies the unified mappings and returns the data in a normalized format.streamreturns the response as a stream, which is ideal for transmitting large datasets, files, or binary data. Using streaming mode helps to efficiently handle large payloads or real-time data flows without requiring the entire data to be buffered in memory.debugreturns the final unified result alongside raw remote fetch information. The response is an envelope containingresult(identical to unified mode output) anddebug(withrequestUrl,requestOptions,data,responseHeaders, and for list operations:nextCursor,isLooping,isEmptyResult,resultCount). When the upstream body exceeds 1 MiB,datais replaced by{ truto_truncated: true, truto_max_bytes, truto_excerpt }.debugisnullfor static responses or whentruto_skip_api_call=true.
Defaults to unified.
unifiedunifiedrawnormalizedstreamdebug
Excludes the remote_data attribute from the response.
Validates the request body against this method's request_body_schema before the request is sent to the underlying integration. When a field marked required is missing, Truto responds 400 with the missing field names under truto_error_insight.missing_required_body_fields instead of forwarding the call. Only the fields documented in request_body_schema are checked. A body carrying a non-empty remote_data object is forwarded unchecked, because remote_data is merged into the provider request and may already carry the required values. A field the mapping always supplies through its default body is treated as present, and a field that is only conditionally required is reported under truto_error_insight.conditionally_required_body_fields rather than rejected. Some integrations declare fields required on update that the provider only requires on create; check meta/{method} for the resource before enabling this on update calls. If you sent an Idempotency-Key and the request was rejected, use a fresh key when you retry with a corrected body: the idempotency cache is keyed on the integrated account, path and key only — it ignores the query string and the body — so reusing the key replays the rejection. Defaults to false, which forwards the request as-is.
Array of fields to exclude from the response.
truto_exclude_fields[]=id&truto_exclude_fields[]=nameQuery parameters to pass to the underlying API without any transformations. Refer this guide to see how to structure the query parameters.
remote_query[foo]=barRequest Body
Refer Writing data using Unified APIs
Optional. The Sesame company (companies.id). When omitted, Truto reads the token's company from GET /core/v3/info (one extra call).
7 supported1 required
The unique identifier for companies
Deel-specific: the country the employee is hired in (Deel employee.country, ISO 3166-1 alpha-2). Falls back to work_location.country.
1 supported
1 supported
Date of birth, YYYY-MM-DD.
9 supported
Email addresses. type is required and must be one of the tenant's UKG contact type names (for example Work); UKG keeps one address per contact type.
12 supported5 required
Google WorkspaceThe email address
Whether the email address is primary
The type of email address
The UKG person number (unique in the tenant). The created employee is mapped from UKG's own answer to this call (UKG returns the person it created, with its personKey), so a create never loses the new employee's ID.
11 supported3 required
Google Workspaceactive (default) or inactive. An active employee takes one of the company's Sesame licences (a disabled employee frees it) and can sign in; Truto sends active when this is omitted, because Sesame requires a status. Prefer this over employees.delete: deleting a Sesame employee is irreversible — Sesame permanently removes the profile and all data associated with it (clock entries, time off, documents), and getting it back is a paid Sesame support request (29,99 EUR at the time of writing), not an API call (https://help.sesamehr.com/es_ES/gestion-de-empleados/puedo-eliminar-usuarios-de-mi-cuenta).
activeinactivependingactiveinactiveactiveinactivependingactiveinactiveactiveinactive
9 supported1 required
activeinactivependingactiveinactiveactiveinactiveRepresents a role or employment of the employee in the company
6 supported1 required
The unique identifier for employments
This represents the date when the employments was created
Represents the effective date of the employment
Employee associated with this employment
1 property
The unique identifier for employees
This represents the employment type
full_timepart_timecontractinternshiptemporarytraineevolunteerper_diemfull_timepart_timefull_timepart_timecontract+ 1 more
Represents the end date of the employment
Represents why the employment ended
This represents the flsa status
Job title of the employee
This represents the pay currency
This represents the pay frequency
This represents the pay group
This represents the pay period
annuallymonthlysemimonthlybiweeklyweeklydailyhourly
This represents the pay rate
This represents the date when the employments was updated
Ethnicity code. Paychex rejects changes for ACTIVE workers.
american_indian_or_alaskan_nativeasianblack_or_african_americanhispanic_or_latinonative_hawaiian_or_other_pacific_islandprefer_not_to_answertwo_or_more_raceswhite_not_of_hispanic_origin
1 supported
american_indian_or_alaskan_nativeasianblack_or_african_americanhispanic_or_latinonative_hawaiian_or_other_pacific_islandprefer_not_to_answertwo_or_more_raceswhite_not_of_hispanic_originFirst name.
13 supported10 required
Google WorkspaceGender. Sesame accepts female, male, non_binary_gender and no_response; companies in Mexico with an ADP or Nomitek integration accept only female and male.
malefemalenon_binarynot_specifiedmalefemalenot_specifiedmalefemalefemalemalenon_binaryprefer_not_to_disclose+ 1 more
6 supported
malefemalenon_binarynot_specifiedmalefemalenot_specifiedfemalemalenon_binaryprefer_not_to_discloseThe organization (groups.id); only the first entry is used. On create, Paychex can create the worker yet reject a value like this one: it answers 207 Multi-Status, Truto returns the created employee as a normal success, and Paychex's per-field errors are only in remote_data.errors (check them after a create).
9 supported1 required
Google WorkspaceThe unique identifier for groups
Group's name
Type of the group. Some underlying providers use this to differentiate between in-built and user created groups.
Postal addresses. name is the UKG address contact type name (for example Home) and is required; street_1, city, state, postal_code and country map to UKG's street, city, state, postalCode and country. UKG has no second street line.
8 supported
The city of the home address
The country of the home address
The unique identifier for locations
This represents the name of the location
The postal code of the home address
The state/province of the home address
The first line of home address
The second line of home address
The name of an existing Omni position (job_roles.name), matched exactly (case-insensitive). A title that matches no position, or more than one, is refused with a 400 before anything is written to Omni HR; create the position first with job_roles create.
10 supported2 required
Last name.
13 supported10 required
Google WorkspaceThe manager (employees.id). UKG assigns a supervisor by person number, so the manager is read first (one extra call) and UKG's supervisorPersonNumber and supervisorName are sent; the manager must already exist in UKG.
6 supported
Google WorkspaceManager's primary email.
This represents the name of the employee
Marital status, stored as sent (Sesame has no fixed list; its app uses single, married, divorced, widowed, separated, domestic_partnership and religious).
singlemarrieddivorcedwidowed
3 supported
singlemarrieddivorcedwidowedMiddle name. Paychex only stores an initial through the API, so only the first character is sent.
5 supported
Deel-specific: the nationality of the employee (Deel employee.nationality, e.g. US).
1 supported1 required
Deel-specific: required when employment_type is part_time (1-99).
1 supported
Initial password. A random one is generated when omitted and the user must change it at first login.
1 supported
Google WorkspaceTelephone numbers. type is required and must be one of the tenant's UKG telephone contact type names (for example Phone 1); UKG keeps one number per contact type and has no extension field.
9 supported
Google WorkspaceThe phone number
The type of phone number
workmobile
The extension of the phone number
Any additional data that should be passed as part of the request body. This data is not transformed by Truto and is passed as is to the remote API.
Not a unified field. true makes Sesame email an invitation to the work email (which is then required). Defaults to false: no email is sent.
1 supported
Deel-specific: the seniority of the employment (Deel employment.seniority, e.g. Senior).
1 supported1 required
Social Security number.
3 supported
Hire date (only the date part is sent, as UKG hireDate).
9 supported3 required
The state of the employee.
publisheddraft
1 supported1 required
publisheddraftEnd of employment (Kallidus leaveDate); only the date part (first 10 characters) is sent. Kallidus disables the account when the date is reached, so a future date schedules the leave.
6 supported
Represents the reason for termination
3 supported
Represents the type of termination. If no clear mapping exists, then raw value is returned.
voluntarydismissedredundancyend_of_contractretirementmutual
2 supported
The UKG user account name. UKG requires a password with it (send remote_data.user.userAccount.userPassword) and a logon profile.
4 supported2 required
Work location (locations.id). Paychex requires the organization (groups) to be sent together with the location. On create, Paychex can create the worker yet reject a value like this one: it answers 207 Multi-Status, Truto returns the created employee as a normal success, and Paychex's per-field errors are only in remote_data.errors (check them after a create).
6 supported2 required
The city of the work address
The country of the work address
The unique identifier for locations
This represents the name of the location
The postal code of the work address
The state/province of the work address
The first line of work address
The second line of work address
Response Body
The unique identifier for employees
13 supported
Google WorkspaceThis represents the avatar
6 supported
This represents the company
6 supported
The unique identifier for companies
This represents the date when the Employee was created
4 supported
Google WorkspaceThis represents date of birth
9 supported
The emails of the user
11 supported
Google WorkspaceThe email address
Whether the email address is primary
The type of email address
This represents the employee number
10 supported
Google WorkspaceThis represents the employment status. If no clear mapping is available, then the raw value is returned.
activeinactivepending
8 supported
Represents a role or employment of the employee in the company
6 supported
The unique identifier for employments
This represents the date when the employments was created
Represents the effective date of the employment
Employee associated with this employment
1 property
The unique identifier for employees
This represents the employment type
full_timepart_timecontractinternshiptemporarytraineevolunteerper_diem
Represents the end date of the employment
Represents why the employment ended
This represents the flsa status
Job title of the employee
This represents the pay currency
This represents the pay frequency
This represents the pay group
This represents the pay period
This represents the pay rate
This represents the date when the employments was updated
The unique identifier for the specific version of the resource.
1 supported
This represent ethnicity
1 supported
This represents the first name of the employee
11 supported
Google WorkspaceThis represents gender
6 supported
This represents the groups
8 supported
Google WorkspaceThe unique identifier for groups
Group's name
Type of the group. Some underlying providers use this to differentiate between in-built and user created groups.
This represents the home location
8 supported
The city of the home address
The country of the home address
The unique identifier for locations
This represents the name of the location
The postal code of the home address
The state/province of the home address
The first line of home address
The second line of home address
Job title of the employee
9 supported
This represents the last name of the employee
11 supported
Google WorkspaceRepresents the manager of the employee. Is also an employee.
6 supported
Google WorkspaceThe unique identifier for employees
This represents the name of the employee
This represents marital status
3 supported
This represents the middle name of the employee
5 supported
This represents the name of the employee
11 supported
Google WorkspaceThis represents the pay group
The unique identifier for pay groups
The phones of the user
9 supported
Google WorkspaceThe extension of the phone number
The phone number
The type of phone number
Raw data returned from the remote API call.
This represents the ssn
3 supported
This represents the start date
9 supported
The employee's tags
The tag's unique identifier
The tag's name
This represents the termination date
6 supported
Represents the reason for termination
3 supported
Represents the type of termination. If no clear mapping exists, then raw value is returned.
voluntarydismissedredundancyend_of_contractretirementmutual
2 supported
This represents the date when the Employee was updated
4 supported
This represents the username
3 supported
This represents the work location
6 supported
The city of the work address
The country of the work address
The unique identifier for locations
This represents the name of the location
The postal code of the work address
The state/province of the work address
The first line of work address
The second line of work address
truto unified hris employees \
-m create \
-a '<integrated_account_id>' \
-b '{
"first_name": "your_first_name",
"last_name": "your_last_name",
"employee_number": "your_employee_number",
"emails": [],
"phones": [],
"date_of_birth": "your_date_of_birth",
"start_date": "your_start_date",
"work_location": {},
"groups": [],
"middle_name": "your_middle_name",
"ssn": "your_ssn",
"gender": "male",
"ethnicity": "american_indian_or_alaskan_native",
"marital_status": "single",
"home_location": [],
"employments": [],
"employment_status": "active",
"termination_type": "voluntary",
"termination_reason": "your_termination_reason",
"termination_date": "your_termination_date",
"company": {},
"manager": {},
"job_title": "your_job_title",
"country": "your_country",
"nationality": "your_nationality",
"seniority": "your_seniority",
"part_time_percentage": 0,
"password": "your_password",
"username": "your_username",
"send_invitation": true,
"remote_data": {},
"state": "published"
}' \
-o jsonimport Truto from '@truto/truto-ts-sdk';
const truto = new Truto({
token: '<your_api_token>',
});
const result = await truto.unifiedApi.create(
'hris',
'employees',
{
"first_name": "your_first_name",
"last_name": "your_last_name",
"employee_number": "your_employee_number",
"emails": [],
"phones": [],
"date_of_birth": "your_date_of_birth",
"start_date": "your_start_date",
"work_location": {},
"groups": [],
"middle_name": "your_middle_name",
"ssn": "your_ssn",
"gender": "male",
"ethnicity": "american_indian_or_alaskan_native",
"marital_status": "single",
"home_location": [],
"employments": [],
"employment_status": "active",
"termination_type": "voluntary",
"termination_reason": "your_termination_reason",
"termination_date": "your_termination_date",
"company": {},
"manager": {},
"job_title": "your_job_title",
"country": "your_country",
"nationality": "your_nationality",
"seniority": "your_seniority",
"part_time_percentage": 0,
"password": "your_password",
"username": "your_username",
"send_invitation": true,
"remote_data": {},
"state": "published"
},
{ integrated_account_id: '<integrated_account_id>' }
);
console.log(result);import asyncio
from truto_python_sdk import TrutoApi
truto_api = TrutoApi(token="<your_api_token>")
async def main():
result = await truto_api.unified_api.create(
"hris",
"employees",
{
"first_name": "your_first_name",
"last_name": "your_last_name",
"employee_number": "your_employee_number",
"emails": [],
"phones": [],
"date_of_birth": "your_date_of_birth",
"start_date": "your_start_date",
"work_location": {},
"groups": [],
"middle_name": "your_middle_name",
"ssn": "your_ssn",
"gender": "male",
"ethnicity": "american_indian_or_alaskan_native",
"marital_status": "single",
"home_location": [],
"employments": [],
"employment_status": "active",
"termination_type": "voluntary",
"termination_reason": "your_termination_reason",
"termination_date": "your_termination_date",
"company": {},
"manager": {},
"job_title": "your_job_title",
"country": "your_country",
"nationality": "your_nationality",
"seniority": "your_seniority",
"part_time_percentage": 0,
"password": "your_password",
"username": "your_username",
"send_invitation": True,
"remote_data": {},
"state": "published"
},
{"integrated_account_id": "<integrated_account_id>"}
)
print(result)
asyncio.run(main())curl -X POST 'https://api.truto.one/unified/hris/employees?integrated_account_id=<integrated_account_id>' \
-H 'Authorization: Bearer <your_api_token>' \
-H 'Content-Type: application/json' \
-d '{
"first_name": "your_first_name",
"last_name": "your_last_name",
"employee_number": "your_employee_number",
"emails": [],
"phones": [],
"date_of_birth": "your_date_of_birth",
"start_date": "your_start_date",
"work_location": {},
"groups": [],
"middle_name": "your_middle_name",
"ssn": "your_ssn",
"gender": "male",
"ethnicity": "american_indian_or_alaskan_native",
"marital_status": "single",
"home_location": [],
"employments": [],
"employment_status": "active",
"termination_type": "voluntary",
"termination_reason": "your_termination_reason",
"termination_date": "your_termination_date",
"company": {},
"manager": {},
"job_title": "your_job_title",
"country": "your_country",
"nationality": "your_nationality",
"seniority": "your_seniority",
"part_time_percentage": 0,
"password": "your_password",
"username": "your_username",
"send_invitation": true,
"remote_data": {},
"state": "published"
}'const integratedAccountId = '<integrated_account_id>';
const body = {
"first_name": "your_first_name",
"last_name": "your_last_name",
"employee_number": "your_employee_number",
"emails": [],
"phones": [],
"date_of_birth": "your_date_of_birth",
"start_date": "your_start_date",
"work_location": {},
"groups": [],
"middle_name": "your_middle_name",
"ssn": "your_ssn",
"gender": "male",
"ethnicity": "american_indian_or_alaskan_native",
"marital_status": "single",
"home_location": [],
"employments": [],
"employment_status": "active",
"termination_type": "voluntary",
"termination_reason": "your_termination_reason",
"termination_date": "your_termination_date",
"company": {},
"manager": {},
"job_title": "your_job_title",
"country": "your_country",
"nationality": "your_nationality",
"seniority": "your_seniority",
"part_time_percentage": 0,
"password": "your_password",
"username": "your_username",
"send_invitation": true,
"remote_data": {},
"state": "published"
};
const response = await fetch(`https://api.truto.one/unified/hris/employees?integrated_account_id=${integratedAccountId}`, {
method: 'POST',
headers: {
'Authorization': 'Bearer <your_api_token>',
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
const data = await response.json();
console.log(data);import requests
url = "https://api.truto.one/unified/hris/employees"
headers = {
"Authorization": "Bearer <your_api_token>",
"Content-Type": "application/json",
}
params = {
"integrated_account_id": "<integrated_account_id>"
}
payload = {
"first_name": "your_first_name",
"last_name": "your_last_name",
"employee_number": "your_employee_number",
"emails": [],
"phones": [],
"date_of_birth": "your_date_of_birth",
"start_date": "your_start_date",
"work_location": {},
"groups": [],
"middle_name": "your_middle_name",
"ssn": "your_ssn",
"gender": "male",
"ethnicity": "american_indian_or_alaskan_native",
"marital_status": "single",
"home_location": [],
"employments": [],
"employment_status": "active",
"termination_type": "voluntary",
"termination_reason": "your_termination_reason",
"termination_date": "your_termination_date",
"company": {},
"manager": {},
"job_title": "your_job_title",
"country": "your_country",
"nationality": "your_nationality",
"seniority": "your_seniority",
"part_time_percentage": 0,
"password": "your_password",
"username": "your_username",
"send_invitation": True,
"remote_data": {},
"state": "published"
}
response = requests.post(url, headers=headers, params=params, json=payload)
print(response.json())