Workday Advanced Compensation Workers API

openapi: 3.2.0
info:
  title: compensation Workers API
  description: The Compensation service enables applications to extend Workday's HCM Compensation features.
  version: v3
  x-workday-confidence-level: Production
  x-workday-internal-source: xo
  x-workday-internal-routing: Public
  x-workday-internal-protected-usage-enabled: false
  x-workday-internal-service-container-id: 2d8b79dba7251000105e1cc54b0a13e1
servers:
- url: https://<tenantHostname>/compensation/v3
tags:
- name: Workers
paths:
  /workers:
    get:
      tags:
      - Workers
      summary: Retrieves a collection of workers
      description: 'Retrieves all workers. Use the search parameter to search for workers by name. The search is case-insensitive.


        Secured By Domain: FLW Service, Self-Service: Current Staffing Information, Worker Data: Public Worker Reports


        Scope: Staffing'
      parameters:
      - name: includeTerminatedWorkers
        in: query
        description: Include terminated workers in the output
        schema:
          type: boolean
      - name: limit
        in: query
        description: The maximum number of objects in a single response. The default is 20. The maximum is 100.
        schema:
          type: integer
          format: int64
      - name: offset
        in: query
        description: 'The zero-based index of the first object in a response collection. The default is 0. Use offset with the limit parameter to control paging of a response collection. Example: If limit is 5 and offset is 9, the response returns a collection of 5 objects starting with the 10th object.'
        schema:
          type: integer
          format: int64
      - name: search
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Successful response. A successful response can return no matched data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    format: int32
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/workerSummary_a489aef739484c13a59e6d502a9e7b68'
        '400':
          description: Invalid request. (https://community.workday.com/rest/error-messages)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        '401':
          description: 'Unauthorized: Missing or invalid credentials. (https://community.workday.com/rest/error-messages)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        '403':
          description: User has insufficient permissions. (https://community.workday.com/rest/error-messages)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        '404':
          description: Resource not found. (https://community.workday.com/rest/error-messages)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ERROR_MODEL_REFERENCE'
      x-workday-internal-try-enabled: 'true'
      x-workday-operation-id: 94a39e71541b468fa895955508287acd
      x-workday-secured-by-domains:
      - FLW Service
      - 'Self-Service: Current Staffing Information'
      - 'Worker Data: Public Worker Reports'
      operationId: getWorkers
      x-operation-id-source: derived
  /workers/{ID}/requestOneTimePayment:
    post:
      tags:
      - Workers
      summary: Request a one-time payment for a worker with the specified ID
      description: 'Creates a one-time payment for a worker with the specified ID, and initiates the Request One-Time Payment business process. In the request body, specify at least these required fields: reason{id}, position{id}, oneTimePayments[ paymentCurrency{id}, oneTimePaymentPlan {id}].


        Sample format for paymentAmount:

        "payment Amount": {

        "value": "2500"

        }


        Secured By Business Process Type: Request One-Time Payment


        Scope: Core Compensation'
      parameters:
      - name: ID
        in: path
        description: 'The Workday ID of the resource.


          Accepts:

          - **Workday ID**: Workday ID (32-character lowercase hexadecimal string).

          - **Reference ID**: Workday reference ID (Type=Value). Valid types: Employee_ID, Contingent_Worker_ID

          - **Named entry**: Valid values: `me`.'
        required: true
        schema:
          $ref: '#/components/schemas/ResourceIdPathValue_workers'
        examples:
          wid:
            summary: Specific resource WID
            value: a3f5b554007d20e98360015c5e6daf6
          referenceId:
            summary: Reference ID
            value: Employee_ID=21002
          me:
            summary: Named entry
            value: me
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/oneTimePaymentPlanEventInput_ada36316d338100011ac2ed696990026'
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oneTimePaymentPlanEventInput_ada36316d338100011ac2ed696990026'
        '400':
          description: 'Invalid request. (https://community.workday.com/rest/error-messages)


            A One-Time Payment plan is required.


            At least 1 One-Time Payment is required.


            Based on the worktag type configuration following worktag types are not valid for taggable type [tt]: [awt]. Please remove all worktags for the invalid worktag types.


            Compensation Change cannot take place before \~Employee\~ Hire Date.


            Coverage Start Date and Coverage End Date can not be entered for a One-Time Payment Plan that does not have Coverage Dates enabled.


            Effective Date is required.


            Either an amount or a percent for the One-Time Payment is required.


            If specifying a Coverage Date range, then both dates must be specified.


            Multiple One-Time Payment is not enabled. Please enable Multiple One-Time Payment in HCM Tenant Setup - Compensation.


            Only one worktag for each type is allowed for each document line.


            Please use a valid One-Time Payment plan.


            Position submitted is not filled as of the effective date.


            Scheduled Payment Date cannot take place before the One Time Payment Effective Date.


            Scheduled Payment Date must be equal to Event Effective Date when Multiple One-Time Payment is not enabled in Edit Tenant Setup - HCM.


            Select a balancing worktag for Worktags of the following type: [type]


            The coverage period End Date must be on or after Start Date.


            The following Accounting Worktags are required but have not been assigned: [missing].


            The job is not valid for the \~employee\~.


            The \~Employee\~ Visibility Date has been set to a value, but the \~Employee\~ Visibility Feature has not been activated in the HCM Tenant settings. Please leave the date blank or activate the feature in the tenant level settings.


            The \~Employee\~ Visibility Date must be on or after the Effective Date.


            The \~employee\~ you have selected has more than one job. You must supply the job to which this operation applies.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        '401':
          description: 'Unauthorized: Missing or invalid credentials. (https://community.workday.com/rest/error-messages)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        '403':
          description: User has insufficient permissions. (https://community.workday.com/rest/error-messages)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        '404':
          description: Resource not found. (https://community.workday.com/rest/error-messages)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ERROR_MODEL_REFERENCE'
      x-workday-internal-try-enabled: 'false'
      x-workday-operation-id: e809fdba72fd100010a1871c11070017
      x-workday-secured-by-business-process-types:
      - Request One-Time Payment
      operationId: postWorkersByIDRequestOneTimePayment
      x-operation-id-source: derived
  /workers/{ID}:
    get:
      tags:
      - Workers
      summary: Retrieves a worker instance
      description: 'Retrieves a worker instance with the specific ID.


        Secured By Domain: FLW Service, Self-Service: Current Staffing Information, Worker Data: Public Worker Reports


        Scope: Staffing'
      parameters:
      - name: ID
        in: path
        description: 'The Workday ID of the resource.


          Accepts:

          - **Workday ID**: Workday ID (32-character lowercase hexadecimal string).

          - **Reference ID**: Workday reference ID (Type=Value). Valid types: Employee_ID, Contingent_Worker_ID

          - **Named entry**: Valid values: `me`.'
        required: true
        schema:
          $ref: '#/components/schemas/ResourceIdPathValue_workers'
        examples:
          wid:
            summary: Specific resource WID
            value: a3f5b554007d20e98360015c5e6daf6
          referenceId:
            summary: Reference ID
            value: Employee_ID=21002
          me:
            summary: Named entry
            value: me
      responses:
        '200':
          description: Successful response. A successful response can return no matched data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/workerProfile_c0a0dce56eb142d39dbffeb505becf7a'
        '400':
          description: Invalid request. (https://community.workday.com/rest/error-messages)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        '401':
          description: 'Unauthorized: Missing or invalid credentials. (https://community.workday.com/rest/error-messages)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        '403':
          description: User has insufficient permissions. (https://community.workday.com/rest/error-messages)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        '404':
          description: Resource not found. (https://community.workday.com/rest/error-messages)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ERROR_MODEL_REFERENCE'
      x-workday-internal-try-enabled: 'true'
      x-workday-operation-id: 94a39e71541b468fa895955508287acd
      x-workday-secured-by-domains:
      - FLW Service
      - 'Self-Service: Current Staffing Information'
      - 'Worker Data: Public Worker Reports'
      operationId: getWorkersByID
      x-operation-id-source: derived
components:
  schemas:
    reason_ada36316d338100012078240be64002b:
      description: The business process type, reason category and reason associated with the business process (e.g. Hire \~Employee\~ > New Hire > New Position).
      allOf:
      - $ref: '#/components/schemas/INSTANCE_MODEL_REFERENCE'
      - type: object
    oneTimePaymentPlanEventInput_ada36316d338100011ac2ed696990026:
      allOf:
      - type: object
        properties:
          oneTimePayments:
            type: array
            description: All one-time payments associated with the event.
            items:
              $ref: '#/components/schemas/oneTimePayments_74e74326e3da1000191f2a639d170046'
            x-workday-type: Multi-instance
          position:
            $ref: '#/components/schemas/position_aa655adbcee910002fcec09dadb70084'
          reason:
            $ref: '#/components/schemas/reason_ada36316d338100012078240be64002b'
          effectiveDate:
            type: string
            description: The date this business process takes effect.
            format: date
            x-workday-type: Date
          employeeVisibilityDate:
            type: string
            description: Returns the date that a compensation change is visible to a \~worker\~.
            format: date
            x-workday-type: Date
          descriptor:
            type: string
            description: The display name of the instance
            example: Lorem ipsum dolor sit ame
          id:
            type: string
            description: Workday Id or Reference Id of the instance.
    oneTimePaymentInput_ada36316d338100012347e847126002d:
      allOf:
      - type: object
        properties:
          additionalInformation:
            type: string
            description: Additional information for this compensation payment
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
          coverageEndDate:
            type: string
            description: The end date of the Coverage Period for the payment, which enables Workday Payroll or Payroll Integration to associate dates with the one-time payment for Fair Labor Standards Act (FLSA) reporting requirements.
            format: date
            x-workday-type: Date
          oneTimePaymentPlan:
            $ref: '#/components/schemas/oneTimePaymentPlan_ada36316d33810001344646d1df60036'
          paymentPercent:
            type: number
            description: The actual amount for the \~bonus\~ payment represented as a percentage.  The percentage is usually calculated as a percentage of base pay, but on the \~bonus\~ plan setup it is possible to override the calculation basis to calculate as a percentage of a set of compensation elements.
            format: double
            example: 100000000000
            x-workday-type: Numeric
          sendToPayroll:
            type: boolean
            description: This is true if you selected Send to Payroll on the \~bonus\~ payment, future payment, or one-time payment. If false, Workday Payroll doesn't process the payment.
            example: true
            x-workday-type: Boolean
          scheduledPaymentDate:
            type: string
            description: The payment date scheduled for the one-time payment request.
            format: date
            x-workday-type: Date
          payrollWorktags:
            type: array
            description: One-Time Payment Worktags for REST API
            items:
              $ref: '#/components/schemas/payrollWorktags_65d8813baebc100013a5391af084022b'
            x-workday-type: Multi-instance
          coverageStartDate:
            type: string
            description: The start date of the Coverage Period for the payment, which enables Workday Payroll or Payroll Integration to associate dates with the one-time payment for Fair Labor Standards Act (FLSA) reporting requirements.
            format: date
            x-workday-type: Date
          paymentCurrency:
            $ref: '#/components/schemas/paymentCurrency_ada36316d33810001344647d7c610037'
          paymentAmount:
            type: object
            description: Amount of compensation payment
            example: '99999999999.999999'
            x-workday-type: Currency
          descriptor:
            type: string
            description: The display name of the instance
            example: Lorem ipsum dolor sit ame
          id:
            type: string
            description: The id for One-Time Payment Representation
    workerProfile_c0a0dce56eb142d39dbffeb505becf7a:
      allOf:
      - type: object
        properties:
          dateOfBirth:
            type: string
            description: The birth date of the \~worker\~.
            format: date
            x-workday-type: Date
          supervisoryOrganizationsManaged:
            type: string
            description: All \~supervisory organizations\~, excluding inherited organizations, in which the \~worker\~ has a leadership role.
            format: url
            readOnly: true
            x-workday-type: Multi-instance
          businessTitle:
            type: string
            description: The business title for the \~worker's\~ primary position. If no business title is defined for a position, the position title is returned back.
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
          isManager:
            type: boolean
            description: Identifies if the \~worker\~ has a \~manager\~ role.
            example: true
            x-workday-type: Boolean
          primaryWorkEmail:
            type: string
            description: The primary work email address for the \~worker\~.
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
          location:
            $ref: '#/components/schemas/location_d6235be431f940598806053af7ba94ef'
          primaryWorkPhone:
            type: string
            description: The primary work phone number for the \~worker\~ including the area code and \~country\~ code.
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
          primaryWorkAddressText:
            type: string
            description: Returns the primary work address for the \~worker\~, or from their default primary work location, full format on a single line.
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
          primarySupervisoryOrganization:
            $ref: '#/components/schemas/primarySupervisoryOrganization_851e1342d4c2489c9680fb2a899227ca'
          yearsOfService:
            type: number
            description: The years of service for the \~worker\~.
            format: double
            example: 99999999999.99
            x-workday-type: Numeric
          descriptor:
            type: string
            description: The display name of the instance
            example: Lorem ipsum dolor sit ame
          href:
            type: string
            description: A link to the instance
          id:
            type: string
            description: Workday Id or Reference Id of the instance.
    paymentCurrency_ada36316d33810001344647d7c610037:
      description: The currency for this compensation payment
      allOf:
      - $ref: '#/components/schemas/INSTANCE_MODEL_REFERENCE'
      - type: object
    primarySupervisoryOrganization_642d7497e69c48da946fc503f66d7da1:
      description: The \~supervisory organization\~ for the \~worker's\~ primary position, if the \~supervisory organization\~ is viewable by everyone.
      allOf:
      - $ref: '#/components/schemas/INSTANCE_MODEL_REFERENCE'
      - type: object
    position_aa655adbcee910002fcec09dadb70084:
      description: Position Element
      allOf:
      - $ref: '#/components/schemas/INSTANCE_MODEL_REFERENCE'
      - type: object
    oneTimePayments_74e74326e3da1000191f2a639d170046:
      allOf:
      - $ref: '#/components/schemas/oneTimePaymentInput_ada36316d338100012347e847126002d'
      - type: object
        properties:
          id:
            type: string
            description: The id for One-Time Payment Representation
    NamedEntry_workers:
      type: string
      description: Named entry alias
      enum:
      - me
    ERROR_MODEL_REFERENCE:
      required:
      - error
      type: object
      properties:
        error:
          type: string
          description: A description of the error
        code:
          type: string
          description: The code that corresponds to the error message. Use the error code to drive programmatic error-handling behavior. Don't use error message strings for this purpose because they are subject to change
        field:
          type: string
          description: The field related to the error
        path:
          type: string
          description: The path of the field related to the error
        severity:
          type: string
          description: Severity of the validation (e.g. Critical, Warning).
        internalMessage:
          type: string
          description: Internal message providing additional context for the validation (e.g. representation content validation details).
    primarySupervisoryOrganization_851e1342d4c2489c9680fb2a899227ca:
      description: The \~supervisory organization\~ for the \~worker's\~ primary position, if the \~supervisory organization\~ is viewable by everyone.
      allOf:
      - $ref: '#/components/schemas/INSTANCE_MODEL_REFERENCE'
      - type: object
    workerSummary_a489aef739484c13a59e6d502a9e7b68:
      allOf:
      - type: object
        properties:
          isManager:
            type: boolean
            description: Identifies if the \~worker\~ has a \~manager\~ role.
            example: true
            x-workday-type: Boolean
          primaryWorkPhone:
            type: string
            description: The primary work phone number for the \~worker\~ including the area code and \~country\~ code.
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
          primaryWorkEmail:
            type: string
            description: The primary work email address for the \~worker\~.
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
          primarySupervisoryOrganization:
            $ref: '#/components/schemas/primarySupervisoryOrganization_642d7497e69c48da946fc503f66d7da1'
          businessTitle:
            type: string
            description: The business title for the \~worker's\~ primary position. If no business title is defined for a position, the position title is returned back.
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
          descriptor:
            type: string
            description: The display name of the instance
            example: Lorem ipsum dolor sit ame
          href:
            type: string
            description: A link to the instance
          id:
            type: string
            description: Workday Id or Reference Id of the instance.
    INSTANCE_MODEL_REFERENCE:
      required:
      - id
      type: object
      properties:
        id:
          pattern: ^(([0-9a-f]{32})|(\S+=\S+))$
          type: string
          description: Workday Id or Reference Id of the instance.
        descriptor:
          type: string
          description: The display name of the instance
          readOnly: true
        href:
          type: string
          description: A link to the instance
          readOnly: true
    WorkdayId:
      pattern: ^[0-9a-f]{32}$
      type: string
      description: Workday ID (32-character lowercase hexadecimal string).
      example: a3f5b554007d20e98360015c5e6daf6
    payrollWorktags_65d8813baebc100013a5391af084022b:
      allOf:
      - $ref: '#/components/schemas/payrollWorktags_65d8813baebc100013a407fcbbc6021e'
      - type: object
        properties:
          id:
            type: string
            description: The id for Tenanted Payroll Worktag Representation
    oneTimePaymentPlan_ada36316d33810001344646d1df60036:
      description: The one-time payment plan name for this one-time payment. Displays only if the payment is a one-time payment.
      allOf:
      - $ref: '#/components/schemas/INSTANCE_MODEL_REFERENCE'
      - type: object
    payrollWorktags_65d8813baebc100013a407fcbbc6021e:
      allOf:
      - type: object
        properties:
          descriptor:
            type: string
            description: The display name of the instance
            example: Lorem ipsum dolor sit ame
          id:
            type: string
            description: The id for Tenanted Payroll Worktag Representation
    ResourceIdPathValue_workers:
      oneOf:
      - $ref: '#/components/schemas/WorkdayId'
      - $ref: '#/components/schemas/WorkdayReferenceId_workers'
      - $ref: '#/components/schemas/NamedEntry_workers'
    location_d6235be431f940598806053af7ba94ef:
      description: Contains the location for the \~worker\~.
      allOf:
      - $ref: '#/components/schemas/INSTANCE_MODEL_REFERENCE'
      - type: object
    WorkdayReferenceId_workers:
      pattern: ^(Employee_ID|Contingent_Worker_ID)=\S+$
      type: string
      description: 'Workday reference ID (Type=Value). Valid types: Employee_ID, Contingent_Worker_ID'
      example: Employee_ID=21002
    VALIDATION_ERROR_MODEL_REFERENCE:
      allOf:
      - required:
        - error
        type: object
        properties:
          error:
            type: string
            description: A description of the error
          errors:
            type: array
            description: An array of validation errors
            items:
              $ref: '#/components/schemas/ERROR_MODEL_REFERENCE'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://<tenantAuthorizationHostname>
          scopes: {}