> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toku.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

## OpenAPI

````yaml api-reference/openapi.json POST /hris/submit-hris-change-request
openapi: 3.1.0
info:
  title: Toku API
  version: 1.0.0
servers:
  - url: https://api.toku.com
security:
  - bearerAuth: []
paths:
  /hris/submit-hris-change-request:
    post:
      operationId: submitHrisChangeRequest
      summary: Submit Hris Change Request
      description: >-
        Validates and creates a profile, compensation or termination change
        request, auto-applying eligible ones and notifying reviewers.


        Not available to API keys.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitHrisChangeRequestRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitHrisChangeRequestResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '409':
          description: Conflict
        '429':
          description: Response 429
components:
  schemas:
    SubmitHrisChangeRequestRequest:
      type: object
      properties:
        roleInOrgID:
          type: string
          format: uuid
        category:
          type: string
          enum:
            - 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
          description: >-
            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.
        changes:
          type: object
          additionalProperties:
            type: object
            properties:
              oldValue:
                type:
                  - string
                  - 'null'
              newValue:
                type:
                  - string
                  - 'null'
              displayLabel:
                type: string
              isInternal:
                type: boolean
            required:
              - oldValue
              - newValue
              - displayLabel
          description: >-
            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.
        effectiveDate:
          type:
            - string
            - 'null'
          description: >-
            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.
        terminationNoticeAcknowledged:
          type: boolean
          description: >-
            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.
        usdSalaryConversion:
          type: object
          properties:
            usdAmount:
              type: string
              pattern: ^\d+(?:\.\d{1,2})?$
            rateDate:
              type: string
              pattern: ^\d{4}-\d{2}-01$
          required:
            - usdAmount
            - rateDate
      required:
        - roleInOrgID
        - category
        - changes
    SubmitHrisChangeRequestResponse:
      type: object
      properties:
        changeRequestId:
          type: string
        status:
          type: string
          enum:
            - PENDING
            - AUTO_APPROVED
        approvalReason:
          type: string
        effectiveDate:
          type: string
        supersededChangeRequestIds:
          type: array
          items:
            type: string
        grantTermination:
          type: object
          properties:
            action:
              type: string
              enum:
                - terminate
                - revert
            status:
              type: string
              enum:
                - success
                - skipped
                - failed
            roleInOrgID:
              type: string
            orgID:
              type: string
            terminationDate:
              type:
                - string
                - 'null'
            grantIDs:
              type: array
              items:
                type: string
            message:
              type: string
          required:
            - action
            - status
            - roleInOrgID
            - orgID
            - terminationDate
            - grantIDs
            - message
      required:
        - changeRequestId
        - status
        - effectiveDate
        - supersededChangeRequestIds
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
````
