100Hires Attachments API

openapi: 3.2.0
info:
  title: 100Hires Attachments 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: Attachments
  description: 'Download attachment bytes by category and UUID.


    URLs in this format are returned in other API responses — resumes (`/candidates/{id}/resume`), candidate files (`/candidates/{id}/files`), application attachments (`/applications/{id}/attachments`), message attachments (inside `/candidates/{id}/messages`), call recordings (inside activity events).


    Authentication is the same Bearer token used for the rest of the API. The response is a binary stream with `Content-Type` from the stored MIME type, `Content-Length`, and `Content-Disposition: attachment; filename="..."` (original filename).'
paths:
  /attachments/{category}/{uuid}/{file_name}:
    get:
      tags:
      - Attachments
      summary: Download attachment bytes
      operationId: downloadAttachment
      description: 'Streams the raw file bytes for an attachment identified by `category` + `uuid`.


        The full URL is pre-built and returned in other API responses (resume, candidate files, application attachments, message attachments, call recordings). Clients should follow the URL as-is with the same `Authorization: Bearer` header used elsewhere.


        Visibility rules: the attachment must belong to a company accessible by the authenticated API key (partner + clients, or the authenticated company itself). Shadowed candidates return 404.


        The response sets `Content-Disposition: attachment; filename="..."` with the original filename (not the internal hashed name in the URL).'
      parameters:
      - name: category
        in: path
        required: true
        schema:
          type: string
          enum:
          - application
          - candidate
          - candidate_comment
          - call_recording
          - company_favicon
          - company_header
          - company_link_preview
          - email_template
          - export_csv
          - import_cv
          - job_note
          - job_preview
          - mail_attachment
          - qas
          - system
          - voicemail
        description: Attachment category (matches the segment in the returned URL).
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Attachment UUID.
      - name: file_name
        in: path
        required: true
        schema:
          type: string
        description: Internal storage filename segment from the URL. Required for the route to match; the `Content-Disposition` header on the response carries the human-readable original filename.
      responses:
        '200':
          description: Raw file bytes.
          headers:
            Content-Type:
              schema:
                type: string
              description: MIME type of the file (e.g. `application/pdf`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`).
            Content-Length:
              schema:
                type: integer
              description: File size in bytes.
            Content-Disposition:
              schema:
                type: string
              description: Always `attachment; filename="..."` with the original filename.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /attachments:
    post:
      tags:
      - Attachments
      summary: Upload attachment
      operationId: uploadAttachment
      description: 'Uploads a file and creates an attachment in the authenticated company.


        Supported categories. The attachment is stored under `company_id` (if provided — must be accessible by the API key) or the authenticated company by default. The referenced `object_id` must belong to that same company (strict `company_id` match, no cross-company uploads).

        - `voicemail` — audio file (wav/mp3, ≤20 MB). No `object_id` required. Returned `uuid` can be referenced as `attachment_uuid` in nurture-campaign voicemail steps.

        - `candidate` — generic candidate file. `object_id` = candidate ID.

        - `application` — application attachment (signed docs, offer letters, etc.). `object_id` = application ID.

        - `candidate_comment` — attachment for a candidate comment. `object_id` = comment ID.

        - `job_note` — attachment for a job note. `object_id` = job note ID.

        - `company_favicon`, `company_header`, `company_link_preview` — company branding assets. `object_id` = company ID (must match the authenticated company or a client company the API key can access).


        Returns `ApiAttachment`. Follow `url` with the same Bearer token to download the file later.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadApiAttachmentRequest'
      responses:
        '200':
          description: Uploaded attachment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAttachment'
              example:
                uuid: 9f8e7d6c-5b4a-3210-9f8e-7d6c5b4a3210
                url: https://api.100hires.com/v2/attachments/voicemail/9f8e7d6c-5b4a-3210-9f8e-7d6c5b4a3210/welcome_message.mp3
                relative_time: just now
                file:
                  is_image: false
                  orig_file_name: welcome_message.mp3
                  file_ext: mp3
                  file_type: audio/mpeg
                  readable_size: 512 KB
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    UploadApiAttachmentRequest:
      type: object
      required:
      - category
      - file
      properties:
        category:
          type: string
          enum:
          - voicemail
          - candidate
          - application
          - candidate_comment
          - job_note
          - company_favicon
          - company_header
          - company_link_preview
          description: Attachment category. Determines file-type validation rules and `object_id` requirements.
        company_id:
          type: integer
          nullable: true
          description: Target company ID. Required only for partner API keys that manage multiple client companies — pick the company the attachment belongs to. If omitted, defaults to the authenticated company. The attachment is stored under this company, and the referenced `object_id` (when present) MUST belong to this same company — mismatch returns 404.
        object_id:
          type: integer
          nullable: true
          description: Target object ID. Required for every category except `voicemail`. Resolves to candidate/application/comment/job-note/company per category. The object's company is strictly matched against `company_id` (or authenticated company when `company_id` omitted); no cross-company uploads.
        file:
          $ref: '#/components/schemas/FileData'
      additionalProperties: false
    ApiAttachment:
      type: object
      description: 'Unified attachment shape returned by apiV2 endpoints (resumes, candidate files, application attachments, message attachments, call recordings, voicemail audio in nurture campaigns).


        `url` is an absolute URL served by the API host (`https://api.100hires.com/v2/attachments/{category}/{uuid}/{file_name}`) and serves the raw file bytes with `Authorization: Bearer <API_KEY>`. The response on `url` sets `Content-Disposition: attachment; filename="..."` with the human-readable filename.


        Use `uuid` to reference the attachment in other endpoints (e.g. nurture voicemail step).

        '
      required:
      - uuid
      - url
      - relative_time
      - file
      properties:
        uuid:
          type: string
          format: uuid
          description: Unique attachment identifier. Stable across API calls; use in referencing endpoints.
        url:
          type: string
          format: uri
          nullable: true
          description: 'Absolute download URL (e.g. `https://api.100hires.com/v2/attachments/application/{uuid}/{file_name}`). Hit with `Authorization: Bearer <API_KEY>`.'
        relative_time:
          type: string
          description: Human-readable time since upload (e.g. `"2 days ago"`).
        file:
          $ref: '#/components/schemas/AttachmentFile'
    FileData:
      type: object
      required:
      - data
      - file_name
      - mime_type
      properties:
        data:
          type: string
          description: Base64 content
        file_name:
          type: string
          description: Original file name.
        mime_type:
          type: string
          description: MIME type (e.g. application/pdf).
        size:
          type: integer
          description: Optional for uploads, returned in responses
    AttachmentFile:
      type: object
      required:
      - is_image
      - orig_file_name
      - file_ext
      - file_type
      - readable_size
      properties:
        is_image:
          type: boolean
          nullable: true
          description: Whether the file is an image.
        orig_file_name:
          type: string
          description: Original file name.
        file_ext:
          type: string
          description: File extension.
        file_type:
          type: string
          description: File type category.
        readable_size:
          type: string
          description: Human-readable file size.
      additionalProperties: false
    ValidationError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          description: Validation error details object.
          required:
          - name
          - validation_errors
          properties:
            name:
              type: string
              description: Always "Validation Error" for validation failures
              example: Validation Error
            message:
              type: string
            code:
              type: integer
              example: 0
            status:
              type: integer
              example: 400
            validation_errors:
              type: object
              description: Field-level validation errors (field name to error message)
              additionalProperties:
                type: string
              example:
                email: Email cannot be blank.
                first_name: First Name cannot be blank.
      example:
        error:
          name: Validation Error
          message: ''
          code: 0
          status: 400
          validation_errors:
            email: Email cannot be blank.
            first_name: First Name cannot be blank.
    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
  responses:
    NotFound:
      description: Not found
      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: Not Found
              message: Candidate not found
              code: 0
              status: 404
    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
    UnsupportedMediaType:
      description: Content-Type must be application/json
      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: Unsupported Media Type
              message: Content-Type must be application/json
              code: 0
              status: 415
    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
    ValidationError:
      description: Validation error
      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/ValidationError'
    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
  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
  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