100Hires Taxonomy API

openapi: 3.2.0
info:
  title: 100Hires Taxonomy API
  version: 2.0.0
  description: '## Introduction to the 100Hires ATS API

    The 100Hires ATS API (v2) helps you automate recruiting workflows end-to-end: candidates, applications, jobs, forms, notes, and partner-company operations. All endpoints return JSON and use bearer authentication. ## OpenAPI Spec

    The 100Hires ATS API follows the OpenAPI 3.x specification. Download the machine-readable spec for use in MCP servers, Cursor, Claude Code, or any OpenAPI tooling:


    `GET https://api.100hires.com/v2/openapi.json`


    ## Authentication

    Send API token in the `Authorization` header for every request:


    `Authorization: Bearer `


    Each API key is tied to a specific **user + company** pair. If the same user belongs to multiple companies, they need a separate key for each company. All actions performed through the API are attributed to the key owner. You can generate or view your API key at https://app.100hires.com/settings/integrations


    ### API Key Verification

    API keys for **unverified companies** are created in a disabled state and will return `401 Unauthorized` until the company passes verification. Once your company is verified, API keys start working automatically — no action required. If your key returns `401` and you believe your company should be verified, contact **support@100hires.com**. ## Rate Limits

    API keys that are not yet approved, such as keys created during the free trial, are subject to a hard rate limit of **1,000 requests per 10 minutes** per company. All API keys and MCP connections of a company share this limit. If your company is managed by a partner, it shares the partner''s limit. Personal API keys are approved automatically when the company starts a paid subscription. Requests over the limit receive a `429 Too Many Requests` response. ### Rate limit headers

    Unapproved keys include these headers on every response:


    | Header | Description |

    |--------|-------------|

    | `X-RateLimit-Limit` | Maximum requests allowed in the current window |

    | `X-RateLimit-Remaining` | Requests remaining in the current window |

    | `X-RateLimit-Reset` | Unix timestamp (seconds) when the window resets |


    ### Handling 429 responses

    When you receive a `429` response, wait until `X-RateLimit-Reset` before retrying. Do not retry immediately — repeated 429s may extend the cooldown. To remove rate limits for your integration, contact **support@100hires.com** with your use case. ## Content-Type

    All request bodies **must** use `Content-Type: application/json`. Sending `application/x-www-form-urlencoded`, `multipart/form-data`, or any other content type

    will result in a `415 Unsupported Media Type` error. ## Responses and Errors

    Standard HTTP status codes are used (`2xx`, `4xx`, `5xx`). All error responses are wrapped in an `error` object containing `name`, `message`, `code`, and `status`. Validation errors additionally include field-level details in `error.validation_errors`. See the Error handling section below for the full format and status table. ## Pagination

    List endpoints use `page` (1-based) and `size` (1-100, default 20). Paginated responses follow:

    `{ "": [...], "pagination": { "page_size", "page_count", "page", "total_count" } }`. ## Lists

    List routes are optimized for synchronization and operational dashboards. Most list endpoints support tenant scoping through optional `company_id` (when allowed by API key context). ## Confidential Data

    Some candidate profile values can be masked by account-level pricing/access rules. Integrations should not assume all profile fields are always fully visible. ## Customizing the Response

    Use endpoint filters (`status`, `job_id`, timestamps, taxonomy IDs, etc.) to minimize payload size and improve sync efficiency. Build incremental sync flows around timestamp filters where available. ## Supported File Formats

    File uploads use base64 payloads with metadata:

    `data`, `file_name`, `mime_type` (and optionally `size`). This format is used for candidate files, resumes, attachments, and logos.'
servers:
- url: https://api.100hires.com/v2
  description: Production API endpoint
security:
- BearerAuth: []
tags:
- name: Taxonomy
  description: Reference dictionaries used across jobs, candidates, and workflow orchestration.
paths:
  /tags:
    get:
      tags:
      - Taxonomy
      summary: List company tags
      operationId: listTags
      parameters:
      - $ref: '#/components/parameters/CompanyIdQuery'
      responses:
        '200':
          description: Tags
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagListResponse'
              example:
                tags:
                - Senior
                - Remote
                - Urgent
                pagination:
                  page_size: 25
                  page_count: 1
                  page: 1
                  total_count: 3
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Returns all tags available for the target company. Recommended to cache for fast tagging UX and validation.
  /workflows:
    get:
      tags:
      - Taxonomy
      summary: List workflows
      operationId: listWorkflows
      parameters:
      - $ref: '#/components/parameters/CompanyIdQuery'
      responses:
        '200':
          description: Workflows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowListResponse'
              example:
                workflows:
                - id: 1
                  name: Default Pipeline
                  stages:
                  - id: 10
                    name: Applied
                    order: 1
                  - id: 11
                    name: Interview
                    order: 2
                  - id: 12
                    name: Offer
                    order: 3
                pagination:
                  page_size: 25
                  page_count: 1
                  page: 1
                  total_count: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Returns workflows and embedded stages for the target company. Use to build stage-aware integrations and routing rules.
  /workflows/stages:
    get:
      tags:
      - Taxonomy
      summary: List workflow stages
      operationId: listWorkflowStages
      parameters:
      - $ref: '#/components/parameters/CompanyIdQuery'
      - name: workflow_id
        in: query
        description: Filter stages by workflow ID (from GET /taxonomy/workflows).
        schema:
          type: integer
      - name: job_id
        in: query
        description: Filter stages by job ID (returns stages from the job's assigned workflow).
        schema:
          type: integer
      responses:
        '200':
          description: Stages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowStagesResponse'
              example:
                stages:
                - id: 10
                  name: Applied
                  order: 1
                - id: 11
                  name: Interview
                  order: 2
                - id: 12
                  name: Offer
                  order: 3
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Returns pipeline stages filtered by workflow or job when provided. Useful for transition UIs and workflow validation.
  /workflows/{id}/stages:
    get:
      tags:
      - Taxonomy
      summary: List stages for a specific workflow
      operationId: listWorkflowStagesById
      parameters:
      - name: id
        in: path
        required: true
        description: Workflow ID
        schema:
          type: integer
      - $ref: '#/components/parameters/CompanyIdQuery'
      responses:
        '200':
          description: Stages for the specified workflow
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowStagesResponse'
              example:
                stages:
                - id: 10
                  name: Applied
                  order: 1
                - id: 11
                  name: Interview
                  order: 2
                - id: 12
                  name: Offer
                  order: 3
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Returns stages for a specific workflow by ID. Equivalent to `GET /workflows/stages?workflow_id={id}`.
  /statuses:
    get:
      tags:
      - Taxonomy
      summary: List statuses
      operationId: listStatuses
      responses:
        '200':
          description: Statuses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusesResponse'
              example:
                statuses:
                - draft
                - published
                - on_hold
                - closed
                - archived
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Returns job status labels used by the platform. Cache this taxonomy to validate job status updates.
  /languages:
    get:
      tags:
      - Taxonomy
      summary: List languages
      operationId: listLanguages
      responses:
        '200':
          description: Languages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LanguagesResponse'
              example:
                languages:
                - locale: en-US
                  language: en
                  native_name: English
                  is_default: true
                - locale: de-DE
                  language: de
                  native_name: Deutsch
                  is_default: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Returns the languages available for career site content. The `locale` value is the wire format accepted by the `language` parameter of career site applications; underscore aliases (de_DE) are normalized on input. The default language is what a career site renders in when no language is picked.
  /categories:
    get:
      tags:
      - Taxonomy
      summary: List categories
      operationId: listCategories
      responses:
        '200':
          description: Categories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoriesResponse'
              example:
                categories:
                - id: 1
                  name: Engineering
                - id: 2
                  name: Design
                - id: 3
                  name: Marketing
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Returns global job categories. Use for job classification and consistent taxonomy mapping.
  /employment-types:
    get:
      tags:
      - Taxonomy
      summary: List employment types
      operationId: listEmploymentTypes
      responses:
        '200':
          description: Employment types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmploymentTypesResponse'
              example:
                employment_types:
                - id: 1
                  name: Full-time
                - id: 2
                  name: Part-time
                - id: 3
                  name: Contract
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Returns supported employment types. Use for validation and external system normalization.
  /education-levels:
    get:
      tags:
      - Taxonomy
      summary: List education levels
      operationId: listEducationLevels
      responses:
        '200':
          description: Education levels
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EducationLevelsResponse'
              example:
                education_levels:
                - id: 1
                  name: High School
                - id: 2
                  name: Bachelor's
                - id: 3
                  name: Master's
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Returns education level taxonomy values. Useful for job requirements and structured matching.
  /experience-levels:
    get:
      tags:
      - Taxonomy
      summary: List experience levels
      operationId: listExperienceLevels
      responses:
        '200':
          description: Experience levels
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperienceLevelsResponse'
              example:
                experience_levels:
                - id: 1
                  name: Entry Level
                - id: 2
                  name: Mid Level
                - id: 3
                  name: Senior
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Returns experience level taxonomy values for role seniority modeling.
  /origins:
    get:
      tags:
      - Taxonomy
      summary: List origins
      operationId: listOrigins
      responses:
        '200':
          description: Origins
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OriginsResponse'
              example:
                origins:
                - id: 1
                  name: Applied
                - id: 2
                  name: Sourced
                - id: 3
                  name: Referred
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Returns candidate origin taxonomy values. Use for attribution analytics and source normalization.
  /sources:
    get:
      tags:
      - Taxonomy
      summary: List sources
      operationId: listSources
      parameters:
      - $ref: '#/components/parameters/CompanyIdQuery'
      responses:
        '200':
          description: Sources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourcesResponse'
              example:
                sources:
                - id: 1
                  name: LinkedIn
                - id: 2
                  name: Indeed
                - id: 3
                  name: Company Website
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Returns company-specific source list. Recommended for attribution sync and reporting consistency.
  /boards:
    get:
      tags:
      - Taxonomy
      summary: List boards
      operationId: listBoards
      responses:
        '200':
          description: Boards
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoardsResponse'
              example:
                boards:
                - name: indeed
                  title: Indeed
                - name: linkedin
                  title: LinkedIn
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Returns available publishing boards with board metadata. Use for distribution setup and board selection UIs.
  /rejection-reasons:
    get:
      tags:
      - Taxonomy
      summary: List rejection reasons
      operationId: listRejectionReasons
      parameters:
      - $ref: '#/components/parameters/CompanyIdQuery'
      responses:
        '200':
          description: Rejection reasons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RejectionReasonsResponse'
              example:
                rejection_reasons:
                - id: 1
                  name: Not enough experience
                - id: 2
                  name: Position filled
                - id: 3
                  name: Salary expectations too high
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Returns configured rejection reasons for the target company. Use to validate rejection actions and analytics.
  /departments:
    get:
      tags:
      - Taxonomy
      summary: List departments
      operationId: listDepartments
      parameters:
      - $ref: '#/components/parameters/CompanyIdQuery'
      responses:
        '200':
          description: Departments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepartmentsResponse'
              example:
                departments:
                - id: 1
                  name: Engineering
                - id: 2
                  name: Product
                - id: 3
                  name: Sales
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: Returns departments for the target company. Use for job organization filters and reporting dimensions.
components:
  schemas:
    IdName:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: integer
          description: Unique identifier.
        name:
          type: string
          description: Display name.
    RejectionReasonsResponse:
      type: object
      required:
      - rejection_reasons
      properties:
        rejection_reasons:
          type: array
          description: Array of rejection reasons.
          items:
            $ref: '#/components/schemas/IdName'
    JobBoardItem:
      type: object
      properties:
        name:
          type: string
          description: Board identifier.
        title:
          type: string
          description: Board display name.
        indeed_posting_url:
          type: string
          nullable: true
          description: Public Indeed posting URL when the job has been sourced/posted to Indeed; null otherwise. Populated only for the Indeed board.
        ziprecruiter_posting_url:
          type: string
          nullable: true
          description: Public ZipRecruiter posting URL (the API `preview_url`) when the job has been posted to ZipRecruiter; null otherwise. Populated only for the ZipRecruiter board.
        user_error:
          type: string
          nullable: true
          description: Why the last posting attempt to this board failed, in plain English. Null when the last attempt succeeded or no attempt was made yet. The text stays until the job is edited and posted again, the board posting succeeds, or the company name shown on the board changes.
    Workflow:
      type: object
      required:
      - id
      - name
      - stages
      properties:
        id:
          type: integer
          description: Workflow ID.
        name:
          type: string
          description: Workflow name.
        stages:
          type: array
          description: Array of stages in this workflow.
          items:
            $ref: '#/components/schemas/WorkflowStage'
    SourcesResponse:
      type: object
      required:
      - sources
      properties:
        sources:
          type: array
          description: Array of candidate sources.
          items:
            $ref: '#/components/schemas/IdName'
    OriginsResponse:
      type: object
      required:
      - origins
      properties:
        origins:
          type: array
          description: Array of candidate origins.
          items:
            $ref: '#/components/schemas/IdName'
    EmploymentTypesResponse:
      type: object
      required:
      - employment_types
      properties:
        employment_types:
          type: array
          description: Array of employment types.
          items:
            $ref: '#/components/schemas/IdName'
    EducationLevelsResponse:
      type: object
      required:
      - education_levels
      properties:
        education_levels:
          type: array
          description: Array of education levels.
          items:
            $ref: '#/components/schemas/IdName'
    BoardsResponse:
      type: object
      required:
      - boards
      properties:
        boards:
          type: array
          description: Array of job boards.
          items:
            $ref: '#/components/schemas/JobBoardItem'
    TagListResponse:
      type: object
      required:
      - tags
      - pagination
      properties:
        tags:
          type: array
          description: Array of tags.
          items:
            type: string
        pagination:
          $ref: '#/components/schemas/Pagination'
    WorkflowStage:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: integer
          description: Stage ID.
        name:
          type: string
          description: Stage name.
        order:
          type:
          - integer
          - 'null'
          description: Stage position in the pipeline.
    Pagination:
      type: object
      required:
      - page_size
      - page_count
      - page
      - total_count
      properties:
        page_size:
          type: integer
          description: Items per page.
        page_count:
          type: integer
          description: Total number of pages.
        page:
          type: integer
          description: Current page number.
        total_count:
          type: integer
          description: Total number of items.
    WorkflowStagesResponse:
      type: object
      required:
      - stages
      properties:
        stages:
          type: array
          description: Array of pipeline stages.
          items:
            $ref: '#/components/schemas/WorkflowStage'
    WorkflowListResponse:
      type: object
      required:
      - workflows
      - pagination
      properties:
        workflows:
          type: array
          description: Array of workflows.
          items:
            $ref: '#/components/schemas/Workflow'
        pagination:
          $ref: '#/components/schemas/Pagination'
    CategoriesResponse:
      type: object
      required:
      - categories
      properties:
        categories:
          type: array
          description: Array of job categories.
          items:
            $ref: '#/components/schemas/IdName'
    LanguagesResponse:
      type: object
      required:
      - languages
      properties:
        languages:
          type: array
          description: Array of languages available for career site content.
          items:
            type: object
            required:
            - locale
            - language
            - native_name
            - is_default
            properties:
              locale:
                type: string
                example: de-DE
                description: Locale in the ll-RR wire format; the identifier to send in API parameters.
              language:
                type: string
                example: de
                description: Two-letter language subtag.
              native_name:
                type: string
                example: Deutsch
                description: Language name in the language itself, as shown to applicants.
              is_default:
                type: boolean
                description: True for the language a career site renders in when none is picked.
    StatusesResponse:
      type: object
      required:
      - statuses
      properties:
        statuses:
          type: array
          description: Array of job statuses.
          items:
            type: string
    ExperienceLevelsResponse:
      type: object
      required:
      - experience_levels
      properties:
        experience_levels:
          type: array
          description: Array of experience levels.
          items:
            $ref: '#/components/schemas/IdName'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          description: Error details object.
          required:
          - name
          - message
          - code
          - status
          properties:
            name:
              type: string
              description: Human-readable error type (e.g. "Not Found", "Bad Request", "Forbidden")
              example: Not Found
            message:
              type: string
              description: Detailed error message
              example: Candidate not found
            code:
              type: integer
              description: Application error code (0 for generic errors)
              example: 0
            status:
              type: integer
              description: HTTP status code
              example: 404
      example:
        error:
          name: Not Found
          message: Candidate not found
          code: 0
          status: 404
    DepartmentsResponse:
      type: object
      required:
      - departments
      properties:
        departments:
          type: array
          description: Array of departments.
          items:
            $ref: '#/components/schemas/IdName'
  headers:
    RateLimitRemaining:
      description: Remaining requests in the current rate-limit window. Returned for unapproved API keys.
      schema:
        type: integer
    RateLimitReset:
      description: Unix timestamp when the current rate-limit window resets. Returned for unapproved API keys.
      schema:
        type: integer
        format: int64
    RateLimitLimit:
      description: Request limit for the current rate-limit window. Returned for unapproved API keys.
      schema:
        type: integer
  responses:
    Unauthorized:
      description: Unauthorized
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              name: Unauthorized
              message: Your request was made with invalid credentials.
              code: 0
              status: 401
    TooManyRequests:
      description: Too many requests
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              name: Too Many Requests
              message: Rate limit exceeded
              code: 0
              status: 429
    Forbidden:
      description: Forbidden
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              name: Forbidden
              message: You are not allowed to perform this action.
              code: 0
              status: 403
  parameters:
    CompanyIdQuery:
      name: company_id
      in: query
      required: false
      schema:
        type: integer
      description: Optional target company ID. Since each API key is already bound to one company, this is only needed when the key owner has access to multiple companies.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: APIKey
      description: 'Provide API token in header: `Authorization: Bearer <token>`. Each key is scoped to a specific user + company pair.'
    CompanySlugAuth:
      type: apiKey
      in: header
      name: X-Company-Slug
      description: 'Company slug for career site public endpoints. Alternative: pass as query param `company_slug`.'
x-tagGroups:
- name: Recruiting Operations
  tags:
  - Candidates
  - Applications
  - Interviews
  - Jobs
  - Evaluations
  - Notes
  - Messages
  - Notification Messages
  - Forms
  - Questions
  - Email Templates
  - Nurture Campaigns
  - Template Placeholders
  - Users
  - Attachments
- name: Organization and Settings
  tags:
  - Companies
  - Taxonomy
  - Billing
  - Feedback
- name: Career Site (Public)
  tags:
  - Career Site