Workday Recruiting Candidates API

openapi: 3.1.0
info:
  title: Workday Recruiting REST Applicants Candidates 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: Candidates
  description: Create, retrieve, and update candidate profiles including personal information, attachments, photos, and assessment data.
paths:
  /candidates:
    get:
      operationId: listCandidates
      summary: Workday Recruiting List Candidates
      description: Retrieve a collection of candidates with optional filtering. Returns candidate profile information including name, contact details, source, and associated job applications.
      tags:
      - Candidates
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - name: updatedFrom
        in: query
        description: Return candidates updated on or after this date-time
        schema:
          type: string
          format: date-time
        example: '2026-05-03T14:30:00Z'
      - name: name
        in: query
        description: Filter candidates by name (partial match supported)
        schema:
          type: string
        example: Senior Software Engineer
      - name: email
        in: query
        description: Filter candidates by email address
        schema:
          type: string
          format: email
        example: candidate@example.com
      responses:
        '200':
          description: Candidates retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of matching candidates
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Candidate'
              examples:
                ListCandidates200Example:
                  summary: Default listCandidates 200 response
                  x-microcks-default: true
                  value:
                    total: 3
                    data:
                    - id: 11111111-2222-3333-4444-555555555555
                      firstName: Jordan
                      lastName: Reyes
                      fullName: Jordan 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
                      tags:
                      - priority
                      jobApplications:
                      - id: 11111111-2222-3333-4444-555555555555
                        descriptor: Senior Software Engineer
                      isInternal: false
                      createdOn: '2026-05-03T14:30:00Z'
                      updatedOn: '2026-05-03T14:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createCandidate
      summary: Workday Recruiting Create a Candidate
      description: Add a new candidate record to the Workday recruiting system. Includes personal information, contact details, and optionally associates the candidate with a job application.
      tags:
      - Candidates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CandidateCreate'
            examples:
              CreateCandidateRequestExample:
                summary: Default createCandidate request
                x-microcks-default: true
                value:
                  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
      responses:
        '201':
          description: Candidate created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Candidate'
              examples:
                CreateCandidate201Example:
                  summary: Default createCandidate 201 response
                  x-microcks-default: true
                  value:
                    id: 11111111-2222-3333-4444-555555555555
                    firstName: Jordan
                    lastName: Reyes
                    fullName: Jordan 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
                    tags:
                    - priority
                    jobApplications:
                    - id: 11111111-2222-3333-4444-555555555555
                      descriptor: Senior Software Engineer
                    isInternal: false
                    createdOn: '2026-05-03T14:30:00Z'
                    updatedOn: '2026-05-03T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /candidates/{id}:
    get:
      operationId: getCandidate
      summary: Workday Recruiting Get a Candidate
      description: Retrieve detailed information for a specific candidate including personal information, contact details, source, tags, and associated job applications.
      tags:
      - Candidates
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Candidate retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Candidate'
              examples:
                GetCandidate200Example:
                  summary: Default getCandidate 200 response
                  x-microcks-default: true
                  value:
                    id: 11111111-2222-3333-4444-555555555555
                    firstName: Jordan
                    lastName: Reyes
                    fullName: Jordan 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
                    tags:
                    - priority
                    jobApplications:
                    - id: 11111111-2222-3333-4444-555555555555
                      descriptor: Senior Software Engineer
                    isInternal: false
                    createdOn: '2026-05-03T14:30:00Z'
                    updatedOn: '2026-05-03T14:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateCandidate
      summary: Workday Recruiting Update a Candidate
      description: Update an existing candidate record with new personal information, contact details, or other profile attributes.
      tags:
      - Candidates
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CandidateCreate'
            examples:
              UpdateCandidateRequestExample:
                summary: Default updateCandidate request
                x-microcks-default: true
                value:
                  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
      responses:
        '200':
          description: Candidate updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Candidate'
              examples:
                UpdateCandidate200Example:
                  summary: Default updateCandidate 200 response
                  x-microcks-default: true
                  value:
                    id: 11111111-2222-3333-4444-555555555555
                    firstName: Jordan
                    lastName: Reyes
                    fullName: Jordan 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
                    tags:
                    - priority
                    jobApplications:
                    - id: 11111111-2222-3333-4444-555555555555
                      descriptor: Senior Software Engineer
                    isInternal: false
                    createdOn: '2026-05-03T14:30:00Z'
                    updatedOn: '2026-05-03T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /candidates/{id}/attachments:
    get:
      operationId: listCandidateAttachments
      summary: Workday Recruiting List Candidate Attachments
      description: Retrieve attachments associated with a candidate, including resumes, cover letters, and other supporting documents.
      tags:
      - Candidates
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Candidate attachments retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Attachment'
              examples:
                ListCandidateAttachments200Example:
                  summary: Default listCandidateAttachments 200 response
                  x-microcks-default: true
                  value:
                    total: 3
                    data:
                    - id: 11111111-2222-3333-4444-555555555555
                      fileName: resume.pdf
                      category: Resume
                      contentType: Full time
                      fileSize: 245678
                      uploadedOn: '2026-05-03T14:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: addCandidateAttachment
      summary: Workday Recruiting Add a Candidate Attachment
      description: Upload an attachment such as a resume, cover letter, or portfolio document to a candidate record.
      tags:
      - Candidates
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              - category
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload
                category:
                  type: string
                  description: Attachment category (e.g., Resume, Cover Letter)
                  enum:
                  - Resume
                  - Cover Letter
                  - Portfolio
                  - Other
      responses:
        '201':
          description: Attachment uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attachment'
              examples:
                AddCandidateAttachment201Example:
                  summary: Default addCandidateAttachment 201 response
                  x-microcks-default: true
                  value:
                    id: 11111111-2222-3333-4444-555555555555
                    fileName: resume.pdf
                    category: Resume
                    contentType: Full time
                    fileSize: 245678
                    uploadedOn: '2026-05-03T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /candidates/{id}/photo:
    get:
      operationId: getCandidatePhoto
      summary: Workday Recruiting Get a Candidate Photo
      description: Retrieve the photo associated with a candidate record.
      tags:
      - Candidates
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Candidate photo retrieved successfully
          content:
            image/*:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateCandidatePhoto
      summary: Workday Recruiting Update a Candidate Photo
      description: Upload or replace the photo for a candidate record.
      tags:
      - Candidates
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          image/*:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Candidate photo updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /candidates/{id}/assess:
    post:
      operationId: assessCandidate
      summary: Workday Recruiting Assess a Candidate
      description: Create or modify a candidate assessment and optionally advance the candidate through job application stages based on the assessment outcome.
      tags:
      - Candidates
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CandidateAssessment'
            examples:
              AssessCandidateRequestExample:
                summary: Default assessCandidate request
                x-microcks-default: true
                value:
                  id: 11111111-2222-3333-4444-555555555555
                  assessmentCategory:
                    id: 11111111-2222-3333-4444-555555555555
                    descriptor: Senior Software Engineer
                  result: Pass
                  score: 87.5
                  comments: Strong technical background with 8+ years of experience in distributed systems.
                  assessedOn: '2026-05-03T14:30:00Z'
      responses:
        '200':
          description: Candidate assessment submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandidateAssessment'
              examples:
                AssessCandidate200Example:
                  summary: Default assessCandidate 200 response
                  x-microcks-default: true
                  value:
                    id: 11111111-2222-3333-4444-555555555555
                    assessmentCategory:
                      id: 11111111-2222-3333-4444-555555555555
                      descriptor: Senior Software Engineer
                    result: Pass
                    score: 87.5
                    comments: Strong technical background with 8+ years of experience in distributed systems.
                    assessedOn: '2026-05-03T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /candidates/{id}/refer:
    post:
      operationId: referCandidate
      summary: Workday Recruiting Refer a Candidate
      description: Submit a candidate referral from an existing worker. Associates the referred candidate with a job requisition and records the referral source.
      tags:
      - Candidates
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - jobRequisition
              - referrer
              properties:
                jobRequisition:
                  $ref: '#/components/schemas/Reference'
                  description: Job requisition for the referral
                referrer:
                  $ref: '#/components/schemas/Reference'
                  description: Worker making the referral
                referralComments:
                  type: string
                  description: Comments from the referrer about the candidate
            examples:
              ReferCandidateRequestExample:
                summary: Default referCandidate request
                x-microcks-default: true
                value:
                  jobRequisition:
                    id: 11111111-2222-3333-4444-555555555555
                    descriptor: Senior Software Engineer
                  referrer:
                    id: 11111111-2222-3333-4444-555555555555
                    descriptor: Senior Software Engineer
                  referralComments: Strong technical background with 8+ years of experience in distributed systems.
      responses:
        '201':
          description: Candidate referral 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
    Attachment:
      type: object
      description: A file attachment associated with a candidate or job application
      properties:
        id:
          type: string
          description: Workday ID (WID) of the attachment
          example: 11111111-2222-3333-4444-555555555555
        fileName:
          type: string
          description: Original file name
          example: resume.pdf
        category:
          type: string
          enum:
          - Resume
          - Cover Letter
          - Portfolio
          - Other
          description: Attachment category
          example: Resume
        contentType:
          type: string
          description: MIME type of the attachment
          example: Full time
        fileSize:
          type: integer
          description: File size in bytes
          example: 245678
        uploadedOn:
          type: string
          format: date-time
          description: Timestamp when the attachment was uploaded
          example: '2026-05-03T14:30:00Z'
    CandidateAssessment:
      type: object
      description: A candidate assessment captures evaluation results from screening tools or manual review processes during the recruiting workflow.
      properties:
        id:
          type: string
          description: Workday ID (WID) of the assessment
          example: 11111111-2222-3333-4444-555555555555
        assessmentCategory:
          $ref: '#/components/schemas/Reference'
          description: Assessment category
        result:
          type: string
          enum:
          - Pass
          - Fail
          - Pending
          description: Assessment outcome
          example: Pass
        score:
          type: number
          description: Numeric assessment score
          example: 87.5
        comments:
          type: string
          description: Assessment comments or notes
          example: Strong technical background with 8+ years of experience in distributed systems.
        assessedOn:
          type: string
          format: date-time
          description: Date and time the assessment was completed
          example: '2026-05-03T14:30:00Z'
    Candidate:
      type: object
      description: A candidate represents an individual being considered for employment, including their personal information, contact details, source, and associated job applications.
      properties:
        id:
          type: string
          description: Workday ID (WID) uniquely identifying the candidate
          example: 11111111-2222-3333-4444-555555555555
        firstName:
          type: string
          description: Candidate first name
          example: Jordan
        lastName:
          type: string
          description: Candidate last name
          example: Reyes
        fullName:
          type: string
          description: Candidate full display name
          example: Jordan 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
              description: Street address line 1
              example: 123 Market Street
            addressLine2:
              type: string
              description: Street address line 2
              example: 123 Market Street
            city:
              type: string
              description: City
              example: San Francisco
            stateProvince:
              type: string
              description: State or province
              example: CA
            postalCode:
              type: string
              description: Postal or ZIP code
              example: '94105'
            country:
              $ref: '#/components/schemas/Reference'
              description: Country reference
          description: Candidate mailing address
        source:
          $ref: '#/components/schemas/Reference'
          description: Candidate source (e.g., Career Site, Referral, Agency)
        tags:
          type: array
          items:
            type: string
          description: Tags applied to the candidate record
        jobApplications:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
          description: Job applications associated with this candidate
        isInternal:
          type: boolean
          description: Whether the candidate is an existing Workday worker
          example: false
        createdOn:
          type: string
          format: date-time
          description: Timestamp when the candidate record was created
          example: '2026-05-03T14:30:00Z'
        updatedOn:
          type: string
          format: date-time
          description: Timestamp when the candidate was last updated
          example: '2026-05-03T14:30:00Z'
    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
    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
  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