openapi: 3.1.0
info:
  title: Workday Recruiting REST Applicants Recruiting Agencies API
  description: RESTful API for managing recruiting operations within Workday Human Capital Management. Provides programmatic access to job requisitions, candidates, job applications, job postings, interviews, and hiring workflows. Supports integration with external talent management and applicant tracking systems using OAuth 2.0 authentication and JSON data format.
  version: v41.2
  contact:
    name: Workday Support
    url: https://www.workday.com/en-us/services/support.html
  termsOfService: https://www.workday.com/en-us/legal.html
  x-generated-from: documentation
  x-source-url: https://community.workday.com/sites/default/files/file-hosting/restapi/index.html
  x-last-validated: '2026-05-03'
servers:
- url: https://{tenant}.workday.com/ccx/api/recruiting/v41.2
  description: Workday Recruiting Production
  variables:
    tenant:
      description: Workday tenant identifier (e.g., wd2-impl-services1)
      default: your-tenant
security:
- oauth2: []
tags:
- name: Recruiting Agencies
  description: Manage recruiting agency relationships, agency users, and agency candidate submissions.
paths:
  /recruitingAgencies:
    get:
      operationId: listRecruitingAgencies
      summary: Workday Recruiting List Recruiting Agencies
      description: Retrieve a collection of recruiting agencies configured in Workday for external candidate sourcing.
      tags:
      - Recruiting Agencies
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Recruiting agencies retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecruitingAgency'
              examples:
                ListRecruitingAgencies200Example:
                  summary: Default listRecruitingAgencies 200 response
                  x-microcks-default: true
                  value:
                    total: 3
                    data:
                    - id: 11111111-2222-3333-4444-555555555555
                      name: Senior Software Engineer
                      contactName: Senior Software Engineer
                      contactEmail: candidate@example.com
                      phone: +1-415-555-0123
                      feePercentage: 22.5
                      active: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /recruitingAgencies/{id}:
    get:
      operationId: getRecruitingAgency
      summary: Workday Recruiting Get a Recruiting Agency
      description: Retrieve detailed information for a specific recruiting agency including contact details, agency users, and fee structure.
      tags:
      - Recruiting Agencies
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Recruiting agency retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecruitingAgency'
              examples:
                GetRecruitingAgency200Example:
                  summary: Default getRecruitingAgency 200 response
                  x-microcks-default: true
                  value:
                    id: 11111111-2222-3333-4444-555555555555
                    name: Senior Software Engineer
                    contactName: Senior Software Engineer
                    contactEmail: candidate@example.com
                    phone: +1-415-555-0123
                    feePercentage: 22.5
                    active: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /recruitingAgencies/{id}/candidates:
    post:
      operationId: submitAgencyCandidate
      summary: Workday Recruiting Submit an Agency Candidate
      description: Submit a candidate from a recruiting agency for a specific job requisition. Creates the candidate record and associates it with the agency source.
      tags:
      - Recruiting Agencies
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - candidate
              - jobRequisition
              properties:
                candidate:
                  $ref: '#/components/schemas/CandidateCreate'
                jobRequisition:
                  $ref: '#/components/schemas/Reference'
                  description: Job requisition to apply the candidate to
                agencyUser:
                  $ref: '#/components/schemas/Reference'
                  description: Agency user submitting the candidate
            examples:
              SubmitAgencyCandidateRequestExample:
                summary: Default submitAgencyCandidate request
                x-microcks-default: true
                value:
                  candidate:
                    firstName: Jordan
                    lastName: Reyes
                    email: candidate@example.com
                    phone: +1-415-555-0123
                    address:
                      addressLine1: 123 Market Street
                      addressLine2: 123 Market Street
                      city: San Francisco
                      stateProvince: CA
                      postalCode: '94105'
                      country:
                        id: 11111111-2222-3333-4444-555555555555
                        descriptor: Senior Software Engineer
                    source:
                      id: 11111111-2222-3333-4444-555555555555
                      descriptor: Senior Software Engineer
                  jobRequisition:
                    id: 11111111-2222-3333-4444-555555555555
                    descriptor: Senior Software Engineer
                  agencyUser:
                    id: 11111111-2222-3333-4444-555555555555
                    descriptor: Senior Software Engineer
      responses:
        '201':
          description: Agency candidate submitted successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    offset:
      name: offset
      in: query
      description: Number of results to skip for pagination
      schema:
        type: integer
        minimum: 0
        default: 0
      example: 0
    id:
      name: id
      in: path
      required: true
      description: Workday ID (WID) of the resource
      schema:
        type: string
      example: 11111111-2222-3333-4444-555555555555
    limit:
      name: limit
      in: query
      description: Maximum number of results to return per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      example: 20
  schemas:
    Error:
      type: object
      description: API error response
      properties:
        error:
          type: string
          description: Error code
          example: string
        message:
          type: string
          description: Human-readable error message
          example: string
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                description: Field that caused the error
                example: string
              message:
                type: string
                description: Description of the field-level error
                example: string
    RecruitingAgency:
      type: object
      description: A recruiting agency represents an external staffing or recruitment firm that submits candidates for open positions.
      properties:
        id:
          type: string
          description: Workday ID (WID) of the recruiting agency
          example: 11111111-2222-3333-4444-555555555555
        name:
          type: string
          description: Agency name
          example: Senior Software Engineer
        contactName:
          type: string
          description: Primary contact name
          example: Senior Software Engineer
        contactEmail:
          type: string
          format: email
          description: Primary contact email
          example: candidate@example.com
        phone:
          type: string
          description: Agency phone number
          example: +1-415-555-0123
        feePercentage:
          type: number
          minimum: 0
          maximum: 100
          description: Agency fee as a percentage of first-year compensation
          example: 22.5
        active:
          type: boolean
          description: Whether the agency relationship is currently active
          example: true
    CandidateCreate:
      type: object
      description: Request body for creating or updating a candidate
      required:
      - firstName
      - lastName
      - email
      properties:
        firstName:
          type: string
          description: Candidate first name
          example: Jordan
        lastName:
          type: string
          description: Candidate last name
          example: Reyes
        email:
          type: string
          format: email
          description: Primary email address
          example: candidate@example.com
        phone:
          type: string
          description: Primary phone number
          example: +1-415-555-0123
        address:
          type: object
          properties:
            addressLine1:
              type: string
              example: 123 Market Street
            addressLine2:
              type: string
              example: 123 Market Street
            city:
              type: string
              example: San Francisco
            stateProvince:
              type: string
              example: CA
            postalCode:
              type: string
              example: '94105'
            country:
              $ref: '#/components/schemas/Reference'
          description: Candidate mailing address
        source:
          $ref: '#/components/schemas/Reference'
          description: Candidate source
    Reference:
      type: object
      description: A reference to a related Workday resource
      properties:
        id:
          type: string
          description: Workday ID (WID) of the referenced resource
          example: 11111111-2222-3333-4444-555555555555
        descriptor:
          type: string
          description: Display name of the referenced resource
          example: Senior Software Engineer
  responses:
    Unauthorized:
      description: Authentication required or token expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication. Register an API client in Workday, grant recruiting scopes, and obtain access tokens.
      flows:
        authorizationCode:
          authorizationUrl: https://{tenant}.workday.com/authorize
          tokenUrl: https://{tenant}.workday.com/ccx/oauth2/token
          scopes:
            recruiting:read: Read recruiting data
            recruiting:write: Modify recruiting data
externalDocs:
  description: Workday Recruiting REST API Documentation
  url: https://community.workday.com/sites/default/files/file-hosting/restapi/index.html