Indeed Employer API

openapi: 3.1.0
info:
  title: Indeed Employer API
  description: >-
    The Indeed Employer API provides a RESTful interface for managing employers,
    candidates, and job postings on the Indeed platform. This API enables ATS
    partners and hiring platforms to programmatically create and update employer
    profiles, retrieve and manage candidate applications, and synchronize job
    postings with Indeed's employment ecosystem.


    Indeed's native APIs use GraphQL via the `https://apis.indeed.com/graphql`
    endpoint. This OpenAPI specification represents a RESTful abstraction of the
    key employer-facing operations available through Indeed's partner APIs,
    covering the Employer Data API, Retrieve Candidates API, and Job Sync API.


    **Authentication**: All API requests require OAuth 2.0 Bearer Token
    authentication. Partners must register through the Indeed Partner Console
    to obtain client credentials.


    **Rate Limits**: API calls are subject to rate limiting. Consult the Indeed
    Partner documentation for current rate limit policies.
  version: 1.0.0
  contact:
    name: Indeed API Support
    url: https://docs.indeed.com/support/
    email: [email protected]
  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

externalDocs:
  description: Indeed Partner Documentation
  url: https://docs.indeed.com/

servers:
- url: https://apis.indeed.com
  description: Indeed Production API Server

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.
- name: Employers
  description: >-
    Operations for creating and managing employer profiles on Indeed. Employer
    entities must be created before job postings can be associated with them.
    Supports global attributes such as employer name and type, as well as
    country-specific attributes like website URL and phone number.
- name: Jobs
  description: >-
    Operations for creating, updating, expiring, and retrieving job postings on
    Indeed. Supports qualifications, working hours, salary, benefits, employer
    information, and Indeed Apply configuration.

components:
  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

  schemas:
    Employer:
      type: object
      description: >-
        An employer entity on Indeed representing a company or organization
        that posts jobs and manages candidates.
      required:
      - id
      - employerName
      properties:
        id:
          type: string
          description: >-
            A globally unique employer identifier. For ATS partners, this
            typically combines the ATS system identifier with the employer's
            internal ID.
          example: "ats-partner_employer-12345"
        employerName:
          type: string
          description: >-
            The display name of the employer as it appears on Indeed job
            listings and company pages.
          example: "Acme Corporation"
        employerType:
          type: string
          description: The type of employer entity.
          enum:
          - DIRECT_EMPLOYER
          - STAFFING_AGENCY
          - RECRUITING_FIRM
          example: "DIRECT_EMPLOYER"
        employerAttributes:
          $ref: '#/components/schemas/EmployerAttributes'
        createdAt:
          type: string
          format: date-time
          description: The timestamp when the employer was created on Indeed.
          example: '2026-01-15T10:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: The timestamp when the employer was last updated.

          example: '2026-01-15T10:30:00Z'
    EmployerAttributes:
      type: object
      description: >-
        Additional attributes for an employer, including both global and
        country-specific settings.
      properties:
        employerType:
          type: string
          description: The type classification of the employer.
          enum:
          - DIRECT_EMPLOYER
          - STAFFING_AGENCY
          - RECRUITING_FIRM
          example: DIRECT_EMPLOYER
        countrySpecificAttributes:
          type: array
          description: >-
            Attributes that vary by country, such as website URLs, phone
            numbers, and locale-specific information.
          items:
            $ref: '#/components/schemas/CountrySpecificAttributes'
          example: []
        localeSpecificAttributes:
          type: array
          description: Locale-specific employer attributes.
          items:
            $ref: '#/components/schemas/LocaleSpecificAttributes'

          example: []
    CountrySpecificAttributes:
      type: object
      description: >-
        Country-scoped employer attributes. Provide an ISO 3166-1 two-letter
        country code to specify the country.
      required:
      - country
      properties:
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          pattern: "^[A-Z]{2}$"
          example: "US"
        websiteUrl:
          type: string
          format: uri
          description: The employer's website URL for this country.
          example: "https://www.acmecorp.com"
        phoneNumber:
          type: string
          description: The employer's contact phone number for this country.
          example: "+1-555-123-4567"
        address:
          $ref: '#/components/schemas/Address'

    LocaleSpecificAttributes:
      type: object
      description: Locale-specific employer attributes for multilingual support.
      properties:
        locale:
          type: string
          description: IETF BCP 47 language tag.
          example: "en-US"
        employerName:
          type: string
          description: Localized employer name.
          example: example_value
        employerDescription:
          type: string
          description: Localized employer description.

          example: example_value
    Address:
      type: object
      description: A physical address.
      properties:
        streetAddress:
          type: string
          description: Street address line.
          example: "123 Main Street"
        streetAddress2:
          type: string
          description: Additional street address information.
          example: "Suite 400"
        city:
          type: string
          description: City name.
          example: "Austin"
        state:
          type: string
          description: State, province, or region.
          example: "TX"
        postalCode:
          type: string
          description: Postal or ZIP code.
          example: "78701"
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: "US"

    PatchEmployerInput:
      type: object
      description: Input for creating or updating an employer on Indeed.
      required:
      - id
      properties:
        id:
          type: string
          description: >-
            A globally unique employer identifier composed of the ATS
            identifier and the employer's ID within that system.
          example: "ats-partner_employer-12345"
        employerName:
          type: string
          description: >-
            The employer's display name. Required when creating a new employer,
            optional when updating an existing one.
          example: "Acme Corporation"
        employerAttributes:
          $ref: '#/components/schemas/EmployerAttributes'

    PatchEmployerPayload:
      type: object
      description: Response payload from a successful employer create or update operation.
      properties:
        employer:
          $ref: '#/components/schemas/Employer'
        success:
          type: boolean
          description: Whether the operation succeeded.
          example: true
        errors:
          type: array
          description: Any errors encountered during the operation.
          items:
            $ref: '#/components/schemas/ApiError'

          example: []
    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: "[email protected]"
        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'
    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
    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
    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"

    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
    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'

    JobPosting:
      type: object
      description: >-
        A job posting on Indeed with all associated metadata including
        title, description, location, salary, benefits, qualifications,
        and application configuration.
      required:
      - jobPostingId
      - title
      - description
      - location
      properties:
        jobPostingId:
          type: string
          description: >-
            A unique identifier for the job posting within the source system.
            Used in combination with sourceName for upsert operations.
          example: "JOB-2024-001"
        title:
          type: string
          description: >-
            The title of the job posting. Maximum length of 75 characters.
          maxLength: 75
          example: "Senior Software Engineer"
        description:
          type: string
          description: >-
            The full description of the job posting including responsibilities,
            requirements, and other details. Must be between 30 and 20,000
            characters.
          minLength: 30
          maxLength: 20000
          example: "We are looking for a Senior Software Engineer to join our growing team..."
        location:
          $ref: '#/components/schemas/JobLocation'
        salary:
          $ref: '#/components/schemas/Salary'
        benefits:
          type: array
          description: Benefits offered with the position.
          items:
            $ref: '#/components/schemas/Benefit'
          example: []
        qualifications:
          type: array
          description: Required or preferred qualifications for the position.
          items:
            $ref: '#/components/schemas/Qualification'
          example: []
        workingHours:
          $ref: '#/components/schemas/WorkingHours'
        employmentType:
          type: string
          description: The type of employment.
          enum:
          - FULL_TIME
          - PART_TIME
          - CONTRACT
          - TEMPORARY
          - INTERNSHIP
          - VOLUNTEER
          example: "FULL_TIME"
        remoteWorkPolicy:
          type: string
          description: The remote work policy for the position.
          enum:
          - ON_SITE
          - REMOTE
          - HYBRID
          example: "HYBRID"
        employer:
          type: object
          description: Reference to the employer posting this job.
          properties:
            id:
              type: string
              description: The employer's unique identifier on Indeed.
            employerName:
              type: string
              description: The employer's display name.
          example: example_value
        source:
          $ref: '#/components/schemas/JobSource'
        indeedApply:
          $ref: '#/components/schemas/IndeedApplyConfig'
        status:
          type: string
          description: The current status of the job posting on Indeed.
          enum:
          - ACTIVE
          - PAUSED
          - EXPIRED
          - CLOSED
          example: "ACTIVE"
        applicationUrl:
          type: string
          format: uri
          description: The URL where candidates can apply for the position.
          example: https://www.example.com
        createdAt:
          type: string
          format: date-time
          description: The timestamp when the job posting was created.
          example: '2026-01-15T10:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: The timestamp when the job posting was last updated.
          example: '2026-01-15T10:30:00Z'
        expiresAt:
          type: string
          format: date-time
          description: The timestamp when the job posting expires.

          example: '2026-01-15T10:30:00Z'
    JobLocation:
      type: object
      description: The location of the job.
      properties:
        streetAddress:
          type: string
          description: Street address of the job location.
          example: example_value
        city:
          type: string
          description: City where the job is located.
          example: "Austin"
        state:
          type: string
          description: State, province, or region.
          example: "TX"
        postalCode:
          type: string
          description: Postal or ZIP code.
          example: "78701"
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: "US"
        formattedAddress:
          type: string
          description: A human-readable formatted address string.
          example: "Austin, TX 78701, US"

    Salary:
      type: object
      description: Salary or compensation details for the job posting.
      properties:
        minimumAmount:
          type: number
          format: double
          description: The minimum salary amount.
          example: 120000
        maximumAmount:
          type: number
          format: double
          description: The maximum salary amount.
          example: 180000
        currency:
          type: string
          description: ISO 4217 currency code.
          example: "USD"
        period:
          type: string
          description: The pay period for the salary.
          enum:
          - HOURLY
          - DAILY
          - WEEKLY
          - BIWEEKLY
          - MONTHLY
          - YEARLY
          example: "YEARLY"

    Benefit:
      type: object
      description: A benefit offered with the job position.
      properties:
        type:
          type: string
          description: The type of benefit.
          enum:
          - HEALTH_INSURANCE
          - DENTAL_INSURANCE
          - VISION_INSURANCE
          - RETIREMENT_401K
          - PAID_TIME_OFF
          - PARENTAL_LEAVE
          - TUITION_REIMBURSEMENT
          - LIFE_INSURANCE
          - DISABILITY_INSURANCE
          - FLEXIBLE_SCHEDULE
          - REMOTE_WORK
          - RELOCATION_ASSISTANCE
          - EMPLOYEE_DISCOUNT
          - COMMUTER_BENEFITS
          - OTHER
          example: "HEALTH_INSURANCE"
        description:
          type: string
          description: Additional details about the benefit.

          example: A sample description.
    Qualification:
      type: object
      description: >-
        A qualification required or preferred for the job position, such as
        education level, years of experience, certifications, or skills.
      properties:
        type:
          type: string
          description: The category of the qualification.
          enum:
          - EDUCATION
          - EXPERIENCE
          - CERTIFICATION
          - SKILL
          - LICENSE
          example: "EXPERIENCE"
        description:
          type: string
          description: Description of the qualification.
          example: "5+ years of software development experience"
        required:
          type: boolean
          description: Whether this qualification is required or preferred.
          example: true

    WorkingHours:
      type: object
      description: Working hours and schedule information for the position.
      properties:
        hoursPerWeek:
          type: number
          format: double
          description: Expected number of hours per week.
          example: 40
        schedule:
          type: string
          description: Description of the work schedule.
          example: "Monday through Friday, 9 AM to 5 PM"
        shiftType:
          type: string
          description: The type of shift.
          enum:
          - DAY
          - NIGHT
          - EVENING
          - ROTATING
          - FLEXIBLE
          example: "DAY"

    JobSource:
      type: object
      description: >-
        Information about the source system for the job posting, used to
        identify the originating ATS or job board.
      required:
      - sourceName
      properties:
        sourceName:
          type: string
          description: >-
            The name of the source system. Must remain consistent across all
            job postings from the same source.
          example: "my-ats-platform"
        sourceUrl:
          type: string
          format: uri
          description: The URL of the original job posting on the source system.

          example: https://www.example.com
    IndeedApplyConfig:
      type: object
      description: Configuration for Indeed Apply integration on the job posting.
      properties:
        enabled:
          type: boolean
          description: Whether Indeed Apply is enabled for this job posting.
          example: true
        postUrl:
          type: string
          format: uri
          description: >-
            The URL where Indeed sends application data when a candidate
            applies through Indeed Apply.
          example: https://www.example.com
        screenerQuestions:
          type: array
          description: Screener questions to present to candidates during application.
          items:
            $ref: '#/components/schemas/ScreenerQuestion'
          example: []
        eeoEnabled:
          type: boolean
          description: >-
            Whether EEO compliance questions are enabled. Available for
            US employers only.

          example: true
    ScreenerQuestion:
      type: object
      description: A screener question configured on a job posting.
      properties:
        id:
          type: string
          description: Unique identifier for the screener question.
          example: abc123
        question:
          type: string
          description: The text of the question.
          example: "Are you authorized to work in the United States?"
        type:
          type: string
          description: The type of expected response.
          enum:
          - TEXT
          - BOOLEAN
          - SINGLE_SELECT
          - MULTI_SELECT
          - NUMERIC
          example: "BOOLEAN"
        required:
          type: boolean
          description: Whether the candidate must answer this question.
          example: true
        options:
          type: array
          description: Available options for select-type questions.
          items:
            type: string

          example: []
    CreateJobPostingInput:
      type: object
      description: >-
        Input for creating one or more job postings on Indeed via the Job
        Sync API.
      required:
      - jobPostings
      properties:
        jobPostings:
          type: array
          items:
            $ref: '#/components/schemas/JobPosting'
          description: Array of job posting objects to create.

          example: []
    CreateJobPostingPayload:
      type: object
      description: Response payload from a job posting creation operation.
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              jobPostingId:
                type: string
                description: The ID of the created or updated job posting.
              status:
                type: string
                enum:
                - CREATED
                - UPDATED
                - FAILED
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/ApiError'
          example: []
        totalCreated:
          type: integer
          description: Total number of job postings successfully created.
          example: 10
        totalFailed:
          type: integer
          description: Total number of job postings that failed to create.

          example: 10
    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
    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
    ApiError:
      type: object
      description: An error returned by the Indeed API.
      properties:
        code:
          type: string
          description: A machine-readable error code.
          example: "INVALID_INPUT"
        message:
          type: string
          description: A human-readable description of the error.
          example: "The employer name field is required."
        field:
          type: string
          description: The field that caused the error, if applicable.
          example: "employerName"

    JobPostingList:
      type: object
      description: A paginated list of job postings.
      properties:
        jobPostings:
          type: array
          items:
            $ref: '#/components/schemas/JobPosting'
          example: []
        totalCount:
          type: integer
          description: Total number of job postings matching the query.
          example: 10
        pageInfo:
          $ref: '#/components/schemas/PageInfo'

    EmployerRegistration:
      type: object
      description: >-
        Registration of an employer for Candidate Sync integration, enabling
        candidate data synchronization between the ATS and Indeed.
      properties:
        employerId:
          type: string
          description: The employer's unique identifier.
          example: '500123'
        registrationStatus:
          type: string
          description: The current registration status.
          enum:
          - ACTIVE
          - PENDING
          - INACTIVE
          example: ACTIVE
        features:
          type: array
          description: Enabled Candidate Sync features for this employer.
          items:
            type: string
            enum:
            - RETRIEVE_CANDIDATES
            - DISPOSITION_SYNC
            - INDEED_APPLY
          example: []
        registeredAt:
          type: string
          format: date-time
          description: When the employer was registered for Candidate Sync.

          example: '2026-01-15T10:30:00Z'
security:
- BearerAuth: []

paths:
  /v1/employers:
    post:
      operationId: createEmployer
      summary: Indeed Create an Employer
      description: >-
        Creates a new employer entity on Indeed. The employer name is required
        when creating a new employer. An employer must be created before job
        postings can be associated with it. Uses the patchEmployer mutation
        internally.
      tags:
      - Employers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchEmployerInput'
            example:
              id: "ats-partner_employer-12345"
              employerName: "Acme Corporation"
              employerAttributes:
                employerType: "DIRECT_EMPLOYER"
                countrySpecificAttributes:
                - country: "US"
                  websiteUrl: "https://www.acmecorp.com"
                  phoneNumber: "+1-555-123-4567"
      responses:
        '201':
          description: Employer created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchEmployerPayload'
        '400':
          description: Invalid input. Check the errors array for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchEmployerPayload'
        '401':
          description: Authentication credentials are missing or invalid.
        '403':
          description: Insufficient permissions to create employers.
        '409':
          description: An employer with the given ID already exists.
        '429':
          description: Rate limit exceeded. Retry after the specified delay.

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/employers/{employerId}:
    get:
      operationId: getEmployer
      summary: Indeed Retrieve an Employer
      description: >-
        Retrieves the details of an existing employer by their unique
  

# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/indeed/refs/heads/main/openapi/indeed-employer-api-openapi.yml