People & profiles
Submit Hris Change Request
Validates and creates a profile, compensation or termination change request, auto-applying eligible ones and notifying reviewers.
Not available to API keys.
curl --request POST \
--url 'https://api.toku.com/hris/submit-hris-change-request' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"roleInOrgID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"category": "NEW_HIRE",
"changes": {},
"effectiveDate": "string",
"terminationNoticeAcknowledged": true,
"usdSalaryConversion": {
"usdAmount": "string",
"rateDate": "string"
}
}'{
"changeRequestId": "string",
"status": "PENDING",
"approvalReason": "string",
"effectiveDate": "string",
"supersededChangeRequestIds": [
"string"
],
"grantTermination": {
"action": "terminate",
"status": "success",
"roleInOrgID": "string",
"orgID": "string",
"terminationDate": "string",
"grantIDs": [
"string"
],
"message": "string"
}
}Authorizations
AuthorizationstringheaderrequiredBearer authentication header of the form Bearer <token>, where <token> is an access token from a Toku sign-in. See Authentication in the API reference.
Body
application/json
roleInOrgIDstring<uuid>requiredcategorystringrequiredNOTE(ck): a .refine() rule is not mirrored here; TGA still enforces it
The kind of change. Keys for each are listed under changes. TERMINATION, WALLET and BENEFITS_NETWORK
always wait for review; the others apply at once unless a salary change reaches the approval threshold
or a bank account is in another country than the worker.
Available options: NEW_HIRE, PERSONAL_INFO, BUSINESS_ENTITY, EMERGENCY_CONTACT, COMPENSATION, EMPLOYMENT, TAX_INFO, TERMINATION, EMPLOYMENT_TYPE, WORK_AUTH, WALLET, BENEFITS_NETWORK, ADDITIONAL_COMPENSATION, STABLECOIN_ALLOCATION, PROVIDENT_FUND
changesobjectrequiredA legal name change (givenName, middleName, familyName) from anyone but a Toku admin waits for review and needs an
effectiveDate and legalNameDocuments: a JSON list of uploaded files, [{"fileKey","fileName"}], from getDocumentUploadUrl.
One entry per field to change, keyed by field name. Every value is a string or null: booleans as
"true"/"false", dates as YYYY-MM-DD, amounts as decimal strings. displayLabel is the field's
human-readable name for the review record. Keys each category takes:
PERSONAL_INFO: givenName, middleName, familyName, legalNameDocuments, preferredName, phoneNumber, contactEmail, personalEmail, dateOfBirth, addressLine1, addressLine2, city, state, postalCode, country, gender, maritalStatus, nationality
BUSINESS_ENTITY (contractors only): entityName, entityRegisteredAddress, entityCountry, entityTaxId
EMERGENCY_CONTACT: emergencyContactName, emergencyContactRelationship, emergencyContactPhone, emergencyContactEmail
COMPENSATION (bank details, not pay): bankAccountOperation, bankAccountId, bankAccountIsPrimary, bankCurrencyCode, bankCountryCode, bankName, bankAccountHolderName, bankAccountType, bankAccountProvider, bankAccountNumber, bankRoutingNumber, bankIban, bankBicSwiftCode, bankSortCode, bankBsb, bankIfscCode, bankClabe, bankTransitNumber, bankInstitutionNumber, bankCode, bankBranchCode, bankBranch, bankCpfNumber, bankPixKey, bankAccountHolderAddress, bankAddress
EMPLOYMENT (pay and role): title, department, location, baseSalary, baseSalaryCurrency, baseSalaryPaymentType, baseSalaryTokenTypeID, signOnBonusAmount, signOnBonusCurrency, startDate, endDate, agreementType, workSchedule, hoursPerWeek, managerRoleInOrgID, managerName, managerEmail, phoneNumber, contractEntityID
TERMINATION: terminationType, terminationReason, terminationSubReason, lastDay, lastDayGardenLeave, terminationEffectiveAt, ptoDaysTaken, ptoDaysRemaining, leavePolicyType, ptoPayoutAtTermination, severanceOffered, severanceDetails, pilonDetails, prefundingAcknowledged, performancePlan, performancePlanDetails, employeeInformed, employeeInformedDate, terminationDocuments
EMPLOYMENT_TYPE: employmentType, contractorType, employmentServiceType
WORK_AUTH: authorizationType, authorizationSubType, expiryDate, sponsorshipRequested, immigrationSupportRequested, sponsorshipNotes, immigrationSupportNotes, workAuthCountry
BENEFITS_NETWORK: healthPlan
ADDITIONAL_COMPENSATION: operation, additionalCompensationId, amount, type, currency, paymentType, tokenTypeID, isRecurring, frequency, effectiveDate, note, removalReason
TAX_INFO takes the tax identity fields of the worker's country. WALLET is accepted but cannot be applied from a change request.
To set a manager under EMPLOYMENT, send managerRoleInOrgID (the manager's roleInOrgID, which fills in their name
and email) or the free-text managerName and managerEmail, never both in one request: that is refused.
contractEntityID (Toku admins only) sets the Toku Contracting Entity: send the entity's contractEntityID from internal__toku_admin_list_contract_entities as newValue, or null for the country default. Send effectiveDate (YYYY-MM-DD) beside changes too: an entity change is refused without it.
A new termination (category TERMINATION with terminationType) is checked as a whole and refused until every
required field is there, so collect them all from the person first and send them in one request:
- terminationType: VOLUNTARY or INVOLUNTARY.
- terminationSubReason: the reason, one of VOLUNTARY: RESIGNATION, FIXED_TERM_EXPIRY, TUPE_TRANSFER;
INVOLUNTARY: MUTUAL_AGREEMENT, POOR_PERFORMANCE, REDUNDANCY, RESTRUCTURING, BUSINESS_CLOSURE, OTHER.
- terminationReason: the reason in the person's own words. Required for POOR_PERFORMANCE, REDUNDANCY,
RESTRUCTURING, BUSINESS_CLOSURE and OTHER; optional notes for the others.
- lastDay: the last working day, YYYY-MM-DD. Always required.
- ptoDaysTaken: days of paid time off taken, a number from 0 to 9999.99. Required for an employee, not
asked of a contractor. ptoDaysRemaining is in the same form.
- leavePolicyType: the company's own PTO / leave policy, ACCRUAL_BASED, UNLIMITED_OR_FLEXIBLE or
NO_WRITTEN_POLICY. ptoPayoutAtTermination: whether that policy pays out unused PTO at termination, YES,
NO or NOT_SURE (follow Toku policy). Both required for an employee, not asked of a contractor. Statutory
payout owed under local law is included in final pay whatever they say. ptoDaysRemaining is required
when leavePolicyType is ACCRUAL_BASED or ptoPayoutAtTermination is YES.
- terminationDocuments: the supporting files, a JSON array in a string, each entry { fileKey, fileName,
documentCategory }. Get each fileKey from hris__get_termination_document_upload_url and upload the file
to the url it returns first. documentCategory is RESIGNATION_LETTER (required for RESIGNATION),
PERFORMANCE_IMPROVEMENT_PLAN (required for POOR_PERFORMANCE) or TERMINATION_SUPPORTING_DOCUMENT.
- employeeInformed: "true" or "false", whether the worker has already been told. Required for INVOLUNTARY
and refused for VOLUNTARY. With "true", employeeInformedDate (YYYY-MM-DD) is required; with "false" it is refused.
- prefundingAcknowledged: "true", required for an employee in a country with statutory severance.
- terminationEffectiveAt (optional): an ISO 8601 timestamp, which must fall on the last working day.
- lastDayGardenLeave (YYYY-MM-DD), severanceOffered ("true"/"false"), severanceDetails, pilonDetails, performancePlan
("true"/"false") and performancePlanDetails are optional.
- The notice acknowledgement is not a key here: it is terminationNoticeAcknowledged, beside changes.
Once a termination is approved it is locked: only a Toku admin can correct it, sending just the fields that change.
effectiveDatestring | nullNOTE(ck): a .refine() rule is not mirrored here; TGA still enforces it
YYYY-MM-DD, a real calendar date. A future date schedules the change where the category allows
it; omit it (or send null) to apply now. Refused for TERMINATION, ADDITIONAL_COMPENSATION and BENEFITS_NETWORK.
Required when changes has contractEntityID: the entity move applies from this date.
terminationNoticeAcknowledgedbooleanTermination only. An INVOLUNTARY termination of an employee whose last working day is less than 14 days from today is refused unless this is true (a Toku admin is only warned): it records that the person submitting understands the request is not in effect until Toku reviews it, and that the termination date may change. Ask them, and send true only on their yes. Not needed for a contractor, a voluntary termination, or a later last working day.
usdSalaryConversionobjectShow child attributes
usdAmountstringrequiredAllowed: matches ^\d+(?:\.\d{1,2})?$
rateDatestringrequiredAllowed: matches ^\d{4}-\d{2}-01$
Response
200Successful response
changeRequestIdstringrequiredstatusstringrequiredAvailable options: PENDING, AUTO_APPROVED
approvalReasonstringeffectiveDatestringrequiredsupersededChangeRequestIdsstring[]requiredgrantTerminationobjectShow child attributes
actionstringrequiredAvailable options: terminate, revert
statusstringrequiredAvailable options: success, skipped, failed
roleInOrgIDstringrequiredorgIDstringrequiredterminationDatestring | nullrequiredgrantIDsstring[]requiredmessagestringrequired