openapi: 3.0.3
info:
  title: Workday REST API
  version: v1
  x-slurry-persona: true
  description: >-
    Community simulation based on Workday's public API documentation. Not affiliated with or endorsed by Workday.
    Covers the Workday REST API (v1) resources most used by HCM and finance integrations: workers, direct reports,
    supervisory organisations, organisations, jobs, job profiles, job families, locations, pay groups, time-off
    requests and time-off plan balances, written from Workday's public REST API directory. Resources are addressed
    under /ccx/api/v1/{tenant}; collections page with limit and offset and return total and data. References to
    other resources are instance objects with id, descriptor and href.
  license:
    name: CC-BY-4.0
    url: https://creativecommons.org/licenses/by/4.0/
  contact:
    name: Slurry
    url: https://slurry.io
externalDocs:
  description: Workday REST API directory (public)
  url: https://community.workday.com/sites/default/files/file-hosting/restapi/index.html
servers:
  - url: https://wd2-impl-services1.workday.com
security:
  - oauth2: []
paths:
  /ccx/api/v1/{tenant}/workers:
    get:
      operationId: listWorkers
      tags: [Workers]
      summary: Retrieve a collection of workers
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: search
          in: query
          description: Searches workers by name or worker id (case-insensitive)
          schema: { type: string }
        - name: includeTerminatedWorkers
          in: query
          schema: { type: boolean }
      responses:
        "200":
          description: A page of workers
          content:
            application/json:
              schema: { $ref: "#/components/schemas/WorkersPage" }
        "400":
          description: Invalid request
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/workers/{ID}:
    get:
      operationId: getWorker
      tags: [Workers]
      summary: Retrieve one of the workers by Workday ID
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/ID"
      responses:
        "200":
          description: The resource
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Worker" }
        "404":
          description: Not found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/workers/{ID}/directReports:
    get:
      operationId: getDirectReports
      tags: [Workers]
      summary: Retrieve the direct reports of a manager
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/ID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Direct reports
          content:
            application/json:
              schema: { $ref: "#/components/schemas/WorkersPage" }
  /ccx/api/v1/{tenant}/workers/{ID}/timeOffRequests:
    get:
      operationId: getWorkerTimeOffRequests
      tags: [TimeOffRequests]
      summary: Retrieve a worker's time-off requests
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/ID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Time-off requests
          content:
            application/json:
              schema: { $ref: "#/components/schemas/TimeOffRequestsPage" }
  /ccx/api/v1/{tenant}/workers/{ID}/requestTimeOff:
    post:
      operationId: requestTimeOff
      tags: [TimeOffRequests]
      summary: Submit a time-off request for a worker, starting the Request Time Off business process
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/ID"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/RequestTimeOffInput" }
      responses:
        "201":
          description: Business process started
          content:
            application/json:
              schema: { $ref: "#/components/schemas/TimeOffRequest" }
        "400":
          description: Validation error
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/workers/{ID}/timeOffPlanBalances:
    get:
      operationId: getWorkerTimeOffBalances
      tags: [TimeOffRequests]
      summary: Retrieve a worker's time-off plan balances
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/ID"
      responses:
        "200":
          description: Plan balances
          content:
            application/json:
              schema: { $ref: "#/components/schemas/BalancesPage" }
              example:
                total: 2
                data:
                  - { id: 3f1c0a7e9b6d4c2a8e5f7a1b2c3d4e5f, descriptor: Annual Leave - UK, timeOffPlan: { id: 9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d, descriptor: Annual Leave - UK }, quantity: "17.5", unitOfTime: { descriptor: Days } }
                  - { id: 4a2d1b8f0c7e5d3b9f6a8b2c3d4e5f6a, descriptor: Sick Leave, timeOffPlan: { id: 1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e, descriptor: Sick Leave }, quantity: "8", unitOfTime: { descriptor: Days } }
  /ccx/api/v1/{tenant}/supervisoryOrganizations:
    get:
      operationId: listSupervisoryOrganizations
      tags: [SupervisoryOrganizations]
      summary: Retrieve a collection of supervisory organisations
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: A page of supervisory organisations
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SupervisoryOrganizationsPage" }
        "400":
          description: Invalid request
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/supervisoryOrganizations/{ID}:
    get:
      operationId: getSupervisoryOrganization
      tags: [SupervisoryOrganizations]
      summary: Retrieve one of the supervisory organisations by Workday ID
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/ID"
      responses:
        "200":
          description: The resource
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SupervisoryOrganization" }
        "404":
          description: Not found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/supervisoryOrganizations/{ID}/workers:
    get:
      operationId: getSupervisoryOrganizationWorkers
      tags: [SupervisoryOrganizations]
      summary: Retrieve the workers in a supervisory organisation
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/ID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Workers
          content:
            application/json:
              schema: { $ref: "#/components/schemas/WorkersPage" }
  /ccx/api/v1/{tenant}/organizations:
    get:
      operationId: listOrganizations
      tags: [Organizations]
      summary: Retrieve a collection of organisations
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: organizationType
          in: query
          schema: { type: string, enum: [Cost Center, Company, Region, Supervisory, Pay Group, Location Hierarchy] }
      responses:
        "200":
          description: A page of organisations
          content:
            application/json:
              schema: { $ref: "#/components/schemas/OrganizationsPage" }
        "400":
          description: Invalid request
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/organizations/{ID}:
    get:
      operationId: getOrganization
      tags: [Organizations]
      summary: Retrieve one of the organisations by Workday ID
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/ID"
      responses:
        "200":
          description: The resource
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Organization" }
        "404":
          description: Not found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/jobs:
    get:
      operationId: listJobs
      tags: [Jobs]
      summary: Retrieve a collection of jobs (positions filled by workers)
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: A page of jobs (positions filled by workers)
          content:
            application/json:
              schema: { $ref: "#/components/schemas/JobsPage" }
        "400":
          description: Invalid request
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/jobs/{ID}:
    get:
      operationId: getJob
      tags: [Jobs]
      summary: Retrieve one of the jobs (positions filled by workers) by Workday ID
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/ID"
      responses:
        "200":
          description: The resource
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Job" }
        "404":
          description: Not found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/jobProfiles:
    get:
      operationId: listJobProfiles
      tags: [JobProfiles]
      summary: Retrieve a collection of job profiles
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: A page of job profiles
          content:
            application/json:
              schema: { $ref: "#/components/schemas/JobProfilesPage" }
        "400":
          description: Invalid request
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/jobProfiles/{ID}:
    get:
      operationId: getJobProfile
      tags: [JobProfiles]
      summary: Retrieve one of the job profiles by Workday ID
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/ID"
      responses:
        "200":
          description: The resource
          content:
            application/json:
              schema: { $ref: "#/components/schemas/JobProfile" }
        "404":
          description: Not found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/jobFamilies:
    get:
      operationId: listJobFamilies
      tags: [JobFamilies]
      summary: Retrieve a collection of job families
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: A page of job families
          content:
            application/json:
              schema: { $ref: "#/components/schemas/JobFamiliesPage" }
        "400":
          description: Invalid request
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/jobFamilies/{ID}:
    get:
      operationId: getJobFamily
      tags: [JobFamilies]
      summary: Retrieve one of the job families by Workday ID
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/ID"
      responses:
        "200":
          description: The resource
          content:
            application/json:
              schema: { $ref: "#/components/schemas/JobFamily" }
        "404":
          description: Not found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/locations:
    get:
      operationId: listLocations
      tags: [Locations]
      summary: Retrieve a collection of locations
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: A page of locations
          content:
            application/json:
              schema: { $ref: "#/components/schemas/LocationsPage" }
        "400":
          description: Invalid request
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/locations/{ID}:
    get:
      operationId: getLocation
      tags: [Locations]
      summary: Retrieve one of the locations by Workday ID
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/ID"
      responses:
        "200":
          description: The resource
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Location" }
        "404":
          description: Not found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/payGroups:
    get:
      operationId: listPayGroups
      tags: [PayGroups]
      summary: Retrieve a collection of pay groups
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: A page of pay groups
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PayGroupsPage" }
        "400":
          description: Invalid request
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/payGroups/{ID}:
    get:
      operationId: getPayGroup
      tags: [PayGroups]
      summary: Retrieve one of the pay groups by Workday ID
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/ID"
      responses:
        "200":
          description: The resource
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PayGroup" }
        "404":
          description: Not found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/timeOffRequests:
    get:
      operationId: listTimeOffRequests
      tags: [TimeOffRequests]
      summary: Retrieve a collection of time-off requests
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: status
          in: query
          schema: { type: string, enum: [In Progress, Successfully Completed, Denied, Canceled] }
      responses:
        "200":
          description: A page of time-off requests
          content:
            application/json:
              schema: { $ref: "#/components/schemas/TimeOffRequestsPage" }
        "400":
          description: Invalid request
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /ccx/api/v1/{tenant}/timeOffRequests/{ID}:
    get:
      operationId: getTimeOffRequest
      tags: [TimeOffRequests]
      summary: Retrieve one of the time-off requests by Workday ID
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/ID"
      responses:
        "200":
          description: The resource
          content:
            application/json:
              schema: { $ref: "#/components/schemas/TimeOffRequest" }
        "404":
          description: Not found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 with an API client registered in the tenant (refresh token grant).
      flows:
        authorizationCode:
          authorizationUrl: https://wd2-impl.workday.com/{tenant}/authorize
          tokenUrl: https://wd2-impl-services1.workday.com/ccx/oauth2/{tenant}/token
          scopes: {}
  parameters:
    Tenant:
      name: tenant
      in: path
      required: true
      schema: { type: string, example: acme_uk }
    ID:
      name: ID
      in: path
      required: true
      description: The Workday ID (WID) of the resource
      schema: { type: string, example: 3aa5550b7fe348b98d7b5741afc65534 }
    Limit:
      name: limit
      in: query
      schema: { type: integer, default: 20, maximum: 100 }
    Offset:
      name: offset
      in: query
      schema: { type: integer, default: 0 }
  schemas:
    Error:
      type: object
      properties:
        error: { type: string, example: "invalid request: the value supplied for 'date' is not valid" }
        errors:
          type: array
          items:
            type: object
            properties:
              error: { type: string }
              field: { type: string }
              location: { type: string }
    InstanceRef:
      type: object
      properties:
        id: { type: string }
        descriptor: { type: string }
        href: { type: string }
    Worker:
      type: object
      properties:
        id: { type: string, example: 3aa5550b7fe348b98d7b5741afc65534 }
        descriptor: { type: string, example: Priya Raman }
        href: { type: string }
        workerId: { type: string, example: "21044" }
        workerType: { type: object, properties: { id: { type: string }, descriptor: { type: string, enum: [Employee, Contingent Worker] } } }
        status: { type: string, enum: [Active, On Leave, Terminated] }
        businessTitle: { type: string }
        primaryWorkEmail: { type: string, format: email }
        primaryWorkPhone: { type: string }
        isManager: { type: boolean }
        hireDate: { type: string, format: date }
        location: { $ref: "#/components/schemas/InstanceRef" }
        primarySupervisoryOrganization: { $ref: "#/components/schemas/InstanceRef" }
        manager: { $ref: "#/components/schemas/InstanceRef" }
        primaryJob: { $ref: "#/components/schemas/InstanceRef" }
        timeType: { type: object, properties: { descriptor: { type: string, enum: [Full time, Part time] } } }
        payGroup: { $ref: "#/components/schemas/InstanceRef" }
    WorkersPage:
      type: object
      properties:
        total: { type: integer }
        data: { type: array, items: { $ref: "#/components/schemas/Worker" } }
    SupervisoryOrganization:
      type: object
      properties:
        id: { type: string }
        descriptor: { type: string, example: Finance Operations (Jane Holt) }
        href: { type: string }
        name: { type: string }
        code: { type: string, example: SUP-0142 }
        manager: { $ref: "#/components/schemas/InstanceRef" }
        superiorOrganization: { $ref: "#/components/schemas/InstanceRef" }
        location: { $ref: "#/components/schemas/InstanceRef" }
        staffingModel: { type: string, enum: [Position Management, Job Management] }
        workerCount: { type: integer }
    SupervisoryOrganizationsPage:
      type: object
      properties:
        total: { type: integer }
        data: { type: array, items: { $ref: "#/components/schemas/SupervisoryOrganization" } }
    Organization:
      type: object
      properties:
        id: { type: string }
        descriptor: { type: string }
        href: { type: string }
        name: { type: string }
        code: { type: string, example: CC-4100 }
        type: { type: object, properties: { descriptor: { type: string, enum: [Cost Center, Company, Region, Supervisory, Pay Group, Location Hierarchy] } } }
        subtype: { type: object, properties: { descriptor: { type: string } } }
        isActive: { type: boolean }
        manager: { $ref: "#/components/schemas/InstanceRef" }
    OrganizationsPage:
      type: object
      properties:
        total: { type: integer }
        data: { type: array, items: { $ref: "#/components/schemas/Organization" } }
    Job:
      type: object
      properties:
        id: { type: string }
        descriptor: { type: string, example: P-00318 Senior Accountant - Priya Raman }
        href: { type: string }
        jobTitle: { type: string }
        jobProfile: { $ref: "#/components/schemas/InstanceRef" }
        worker: { $ref: "#/components/schemas/InstanceRef" }
        supervisoryOrganization: { $ref: "#/components/schemas/InstanceRef" }
        location: { $ref: "#/components/schemas/InstanceRef" }
        jobType: { type: object, properties: { descriptor: { type: string, enum: [Regular, Fixed Term, Temporary, Intern] } } }
        timeType: { type: object, properties: { descriptor: { type: string, enum: [Full time, Part time] } } }
        startDate: { type: string, format: date }
    JobsPage:
      type: object
      properties:
        total: { type: integer }
        data: { type: array, items: { $ref: "#/components/schemas/Job" } }
    JobProfile:
      type: object
      properties:
        id: { type: string }
        descriptor: { type: string }
        href: { type: string }
        name: { type: string }
        jobCode: { type: string, example: FIN-ACC-03 }
        jobFamily: { $ref: "#/components/schemas/InstanceRef" }
        managementLevel: { type: object, properties: { descriptor: { type: string, enum: [Individual Contributor, Supervisor, Manager, Director, Vice President, Executive] } } }
        isExempt: { type: boolean }
        isInactive: { type: boolean }
    JobProfilesPage:
      type: object
      properties:
        total: { type: integer }
        data: { type: array, items: { $ref: "#/components/schemas/JobProfile" } }
    JobFamily:
      type: object
      properties:
        id: { type: string }
        descriptor: { type: string }
        href: { type: string }
        name: { type: string }
        code: { type: string }
        isInactive: { type: boolean }
    JobFamiliesPage:
      type: object
      properties:
        total: { type: integer }
        data: { type: array, items: { $ref: "#/components/schemas/JobFamily" } }
    Location:
      type: object
      properties:
        id: { type: string }
        descriptor: { type: string, example: London - Farringdon }
        href: { type: string }
        name: { type: string }
        locationType: { type: object, properties: { descriptor: { type: string, enum: [Business Site, Remote, Warehouse, Retail Store] } } }
        timeZone: { type: string, enum: [Europe/London, America/New_York, America/Chicago, America/Los_Angeles, Europe/Dublin] }
        country: { type: object, properties: { descriptor: { type: string, enum: [United Kingdom, United States of America, Ireland] } } }
        city: { type: string }
        isInactive: { type: boolean }
    LocationsPage:
      type: object
      properties:
        total: { type: integer }
        data: { type: array, items: { $ref: "#/components/schemas/Location" } }
    PayGroup:
      type: object
      properties:
        id: { type: string }
        descriptor: { type: string, example: UK Monthly }
        href: { type: string }
        name: { type: string }
        code: { type: string, example: PG-UK-M }
        frequency: { type: object, properties: { descriptor: { type: string, enum: [Monthly, Semi-monthly, Biweekly, Weekly] } } }
        country: { type: object, properties: { descriptor: { type: string, enum: [United Kingdom, United States of America] } } }
        currency: { type: string, enum: [GBP, USD] }
        nextPayDate: { type: string, format: date }
    PayGroupsPage:
      type: object
      properties:
        total: { type: integer }
        data: { type: array, items: { $ref: "#/components/schemas/PayGroup" } }
    TimeOffRequest:
      type: object
      properties:
        id: { type: string }
        descriptor: { type: string, example: "Time Off Request: Priya Raman (Annual Leave - UK)" }
        href: { type: string }
        worker: { $ref: "#/components/schemas/InstanceRef" }
        timeOffType: { type: object, properties: { id: { type: string }, descriptor: { type: string, enum: [Annual Leave - UK, Vacation - US, Sick Leave, Personal Day, Bereavement, Jury Duty, Parental Leave] } } }
        date: { type: string, format: date }
        quantity: { type: string, example: "1" }
        unit: { type: string, enum: [Days, Hours] }
        comment: { type: string }
        status: { type: string, enum: [In Progress, Successfully Completed, Denied, Canceled] }
        submittedOn: { type: string, format: date-time }
        awaitingAction: { $ref: "#/components/schemas/InstanceRef" }
    TimeOffRequestsPage:
      type: object
      properties:
        total: { type: integer }
        data: { type: array, items: { $ref: "#/components/schemas/TimeOffRequest" } }
    RequestTimeOffInput:
      type: object
      required: [days]
      properties:
        businessProcessParameters:
          type: object
          properties:
            comment: { type: string }
        days:
          type: array
          items:
            type: object
            required: [date, timeOffType]
            properties:
              date: { type: string, format: date }
              dailyQuantity: { type: string, example: "1" }
              timeOffType: { type: object, properties: { id: { type: string } } }
              comment: { type: string }
    Balance:
      type: object
      properties:
        id: { type: string }
        descriptor: { type: string }
        timeOffPlan: { $ref: "#/components/schemas/InstanceRef" }
        quantity: { type: string }
        unitOfTime: { type: object, properties: { descriptor: { type: string } } }
    BalancesPage:
      type: object
      properties:
        total: { type: integer }
        data: { type: array, items: { $ref: "#/components/schemas/Balance" } }