People & profiles

Submit Hris Change Request

Validates and creates a profile, compensation or termination change request, auto-applying eligible ones and notifying reviewers.

POSThttps://api.toku.com/hris/submit-hris-change-request

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"
  }
}'
200 response
{
  "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

Authorizationstringheaderrequired

Bearer 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>required
categorystringrequired

NOTE(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

changesobjectrequired

A 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 | null

NOTE(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.

terminationNoticeAcknowledgedboolean

Termination 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.

usdSalaryConversionobject
Show child attributes
usdAmountstringrequired

Allowed: matches ^\d+(?:\.\d{1,2})?$

rateDatestringrequired

Allowed: matches ^\d{4}-\d{2}-01$

Response

200Successful response
changeRequestIdstringrequired
statusstringrequired

Available options: PENDING, AUTO_APPROVED

approvalReasonstring
effectiveDatestringrequired
supersededChangeRequestIdsstring[]required
grantTerminationobject
Show child attributes
actionstringrequired

Available options: terminate, revert

statusstringrequired

Available options: success, skipped, failed

roleInOrgIDstringrequired
orgIDstringrequired
terminationDatestring | nullrequired
grantIDsstring[]required
messagestringrequired
400Bad request
401Unauthorized
403Forbidden
404Not found
409Conflict
429Response 429
Was this page helpful? Suggest edits