Indeed Candidates API

openapi: 3.2.0
info:
  title: Indeed Employer Candidates API
  description: The Indeed Employer API provides a RESTful interface for managing employers, candidates, and job postings on the Indeed platform.
  version: 1.0.0
  contact:
    name: Indeed API Support
    url: https://docs.indeed.com/support/
    email: opensource@indeed.com
  license:
    name: Proprietary
    url: https://docs.indeed.com/legal-terms/developer-agreement
  termsOfService: https://www.indeed.com/legal/api-terms
  x-logo:
    url: https://www.indeed.com/images/indeed-logo.png
servers:
- url: https://apis.indeed.com
  description: Indeed Production API Server
security:
- BearerAuth: []
tags:
- name: Candidates
  description: Operations for retrieving and managing candidate applications. Part of the Candidate Sync APIs, these endpoints enable ATS partners to fetch candidate and application data from Indeed on behalf of registered employers.
paths:
  /v1/employers/{employerId}/candidates:
    get:
      operationId: listCandidates
      summary: Indeed List Candidates for an Employer
      description: Retrieves a paginated list of candidates who have applied to jobs posted by the specified employer. Part of the Candidate Sync APIs, this endpoint returns candidate and application information including the most recent unacknowledged applications.
      tags:
      - Candidates
      parameters:
      - name: employerId
        in: path
        required: true
        description: The unique identifier of the employer.
        schema:
          type: string
      - name: status
        in: query
        required: false
        description: Filter candidates by application status.
        schema:
          type: string
          enum:
          - NEW
          - CONTACTED
          - INTERVIEWED
          - OFFERED
          - HIRED
          - REJECTED
      - name: jobPostingId
        in: query
        required: false
        description: Filter candidates by job posting ID.
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: Cursor for forward pagination.
        schema:
          type: string
      - name: first
        in: query
        required: false
        description: Number of candidates to return (max 100).
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: since
        in: query
        required: false
        description: Return only candidates who applied after this timestamp.
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Candidates retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandidateList'
        '401':
          description: Authentication credentials are missing or invalid.
        '403':
          description: Insufficient permissions. The employer may not be registered for Candidate Sync.
        '404':
          description: Employer not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/employers/{employerId}/candidates/{candidateId}:
    get:
      operationId: getCandidate
      summary: Indeed Retrieve a Candidate
      description: Retrieves the full details of a specific candidate application, including personal information, resume, screener question responses, and EEO data if applicable.
      tags:
      - Candidates
      parameters:
      - name: employerId
        in: path
        required: true
        description: The unique identifier of the employer.
        schema:
          type: string
      - name: candidateId
        in: path
        required: true
        description: The unique identifier of the candidate application.
        schema:
          type: string
      responses:
        '200':
          description: Candidate retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Candidate'
        '401':
          description: Authentication credentials are missing or invalid.
        '403':
          description: Insufficient permissions to access this candidate.
        '404':
          description: Candidate or employer not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/employers/{employerId}/candidates/{candidateId}/disposition:
    put:
      operationId: updateCandidateDisposition
      summary: Indeed Update Candidate Disposition
      description: Updates the disposition (application status) of a candidate for a specific job posting. This syncs the hiring pipeline status from the ATS back to Indeed, enabling accurate reporting and analytics.
      tags:
      - Candidates
      parameters:
      - name: employerId
        in: path
        required: true
        description: The unique identifier of the employer.
        schema:
          type: string
      - name: candidateId
        in: path
        required: true
        description: The unique identifier of the candidate application.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DispositionUpdate'
            example:
              applicationId: app-123456
              status: INTERVIEWED
              statusUpdatedAt: '2026-03-01T14:30:00Z'
      responses:
        '200':
          description: Disposition updated successfully.
        '400':
          description: Invalid disposition status.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: Candidate or employer not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    DispositionUpdate:
      type: object
      description: An update to the disposition (application status) of a candidate for a specific job posting. Used to sync hiring pipeline status changes back to Indeed.
      required:
      - applicationId
      - status
      properties:
        applicationId:
          type: string
          description: The unique identifier for the application.
          example: '500123'
        status:
          type: string
          description: The new disposition status for the application. Must be one of Indeed's predefined categories.
          enum:
          - NEW
          - CONTACTED
          - INTERVIEWED
          - OFFERED
          - HIRED
          - REJECTED
          example: NEW
        statusUpdatedAt:
          type: string
          format: date-time
          description: The timestamp when the status change occurred.
          example: '2026-01-15T10:30:00Z'
        rejectionReason:
          type: string
          description: The reason for rejection, if the status is REJECTED.
          example: example_value
    ResumeFile:
      type: object
      description: An uploaded resume file.
      properties:
        fileName:
          type: string
          description: The original filename of the uploaded resume.
          example: jane_smith_resume.pdf
        contentType:
          type: string
          description: The MIME type of the resume file.
          example: application/pdf
        data:
          type: string
          format: byte
          description: The raw binary content of the resume file, Base64-encoded.
          example: example_value
    Resume:
      type: object
      description: A candidate's resume in multiple formats. The file field contains the uploaded resume document, while text, html, and json fields provide parsed representations.
      properties:
        file:
          $ref: '#/components/schemas/ResumeFile'
        text:
          type: string
          description: Plain text representation of the resume content.
          example: example_value
        html:
          type: string
          description: HTML-formatted representation of the resume content.
          example: example_value
        json:
          type: object
          description: Structured JSON representation of the parsed resume, including sections for work experience, education, skills, and other fields.
          additionalProperties: true
          example: example_value
    EeoResponses:
      type: object
      description: Equal Employment Opportunity (EEO) compliance responses provided by the candidate. Available only for US employers with EEO questions enabled.
      properties:
        gender:
          type: string
          description: The candidate's self-reported gender identity.
          example: example_value
        race:
          type: string
          description: The candidate's self-reported race or ethnicity.
          example: example_value
        veteranStatus:
          type: string
          description: The candidate's veteran status.
          example: example_value
        disabilityStatus:
          type: string
          description: The candidate's disability status.
          example: example_value
    Candidate:
      type: object
      description: A job candidate with personal details, resume information, and application data retrieved from Indeed.
      required:
      - id
      - name
      - email
      properties:
        id:
          type: string
          description: A unique candidate identifier. For Indeed Apply applications, this corresponds to the apply_id, a unique 64-character identifier linking the employer, candidate, and job posting.
          example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
        name:
          type: string
          description: The candidate's full name.
          example: Jane Smith
        firstName:
          type: string
          description: The candidate's first name.
          example: Jane
        lastName:
          type: string
          description: The candidate's last name.
          example: Smith
        email:
          type: string
          format: email
          description: The candidate's email address.
          example: jane.smith@example.com
        phoneNumber:
          type: string
          description: The candidate's phone number.
          example: +1-555-987-6543
        location:
          type: string
          description: The candidate's location as a freeform string.
          example: Austin, TX
        resume:
          $ref: '#/components/schemas/Resume'
        coverLetter:
          type: string
          description: The candidate's cover letter text, if provided.
          example: example_value
        applicationStatus:
          type: string
          description: The current status of the candidate's application. Must map to one of Indeed's predefined disposition categories.
          enum:
          - NEW
          - CONTACTED
          - INTERVIEWED
          - OFFERED
          - HIRED
          - REJECTED
          example: NEW
        screenerQuestionResponses:
          type: array
          description: Responses to screener questions configured on the job posting.
          items:
            $ref: '#/components/schemas/ScreenerQuestionResponse'
          example: []
        eeoResponses:
          $ref: '#/components/schemas/EeoResponses'
        appliedAt:
          type: string
          format: date-time
          description: The timestamp when the candidate submitted the application.
          example: '2026-01-15T10:30:00Z'
        source:
          type: string
          description: The source of the application, such as Indeed Apply, organic application, or other channels.
          example: indeed_apply
        jobPostingId:
          type: string
          description: The identifier of the job posting the candidate applied to.
          example: '500123'
    ScreenerQuestionResponse:
      type: object
      description: A candidate's response to a screener question on the job posting.
      properties:
        questionId:
          type: string
          description: The unique identifier of the screener question.
          example: '500123'
        question:
          type: string
          description: The text of the screener question.
          example: Do you have a valid driver's license?
        answer:
          type: string
          description: The candidate's answer to the question.
          example: 'Yes'
    PageInfo:
      type: object
      description: Pagination information for list responses.
      properties:
        hasNextPage:
          type: boolean
          description: Whether there are more results available.
          example: true
        hasPreviousPage:
          type: boolean
          description: Whether there are previous results available.
          example: true
        startCursor:
          type: string
          description: Cursor for the first item in the current page.
          example: example_value
        endCursor:
          type: string
          description: Cursor for the last item in the current page.
          example: example_value
    CandidateList:
      type: object
      description: A paginated list of candidates.
      properties:
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/Candidate'
          example: []
        totalCount:
          type: integer
          description: Total number of candidates matching the query.
          example: 42
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer Token authentication. Obtain access tokens through the Indeed OAuth 2.0 authorization flow using your partner client credentials.
    OAuth2:
      type: oauth2
      description: Indeed OAuth 2.0 authentication for partner applications.
      flows:
        clientCredentials:
          tokenUrl: https://apis.indeed.com/oauth/v2/tokens
          scopes:
            employer_access: Access and manage employer data
            candidate_read: Read candidate and application data
            job_posting_write: Create and manage job postings
externalDocs:
  description: Indeed Partner Documentation
  url: https://docs.indeed.com/