100Hires ATS API Documentation

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

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

New API keys are subject to a hard rate limit of 100 requests per 10 minutes per key. Requests over the limit receive a 429 Too Many Requests response.

Rate limit headers

Unapproved keys include these headers on every response:

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: { "<resource>": [...], "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.

Webhooks

Webhook subscriptions can be managed per job and per company.

Set up

Use webhook endpoints to register destination URLs for events in your integration.

Securing webhooks

Every delivery is signed with the x-hires-signature-v2 header: base64(HMAC_SHA256(rawBody, secret)), computed over the raw request body with the webhook's signing secret (returned once when you create or rotate the webhook). Verify it before trusting a request and reject anything that does not match.

During a secret rotation, x-hires-signature-v2 may carry multiple space-separated signatures (one per currently-valid secret). Treat the header as a space-separated list and accept the request if any entry matches a secret you hold.

Verification example for x-hires-signature-v2 (Node.js):

const crypto = require('crypto');
const expected = crypto.createHmac('sha256', signingSecret).update(rawBody).digest('base64');
const provided = (req.headers['x-hires-signature-v2'] || '').split(' ');
const verified = provided.includes(expected);

Signing secrets and rotation

Each webhook owns its own signing secret, independent of your API key. The secret is returned once as signing_secret when you create the webhook (POST /jobs/{id}/webhooks, POST /companies/{id}/webhooks) — store it securely, it is never shown again. To rotate with zero downtime, call POST /jobs/{id}/webhooks/{webhook_id}/rotate-secret (or the company equivalent): the previous secret stays valid for a grace window while both old and new signatures are sent, so you can switch the secret on your side without dropping any deliveries.

Receiving webhooks

Always respond quickly with 2xx, then process asynchronously to avoid retries/timeouts.

Event payloads

On each new application, 100hires sends a POST to your registered URL with a JSON body describing the application. Verify the signature (see "Securing webhooks") before processing, and parse defensively — fields may be null and new fields may be added over time.

Webhooks registered through this API (v2) receive the payload below. (Webhooks created via the legacy v1 API receive a different, legacy payload — register through v2 to receive this richer shape.)

Example delivery payload:

{
  "id": 845112,
  "candidate_id": 390217,
  "job_id": 4821,
  "job_alias": "senior-backend-engineer",
  "internal_job_id": 12,
  "company_id": 1007,
  "stage": { "id": 3, "name": "Applied" },
  "status": "active",
  "is_disqualified": false,
  "url_backoffice": "https://app.100hires.com/candidate/default/view?candidate=390217&application=845112",
  "cv": {
    "url": "https://api.100hires.com/v2/files/9f1c2e7a-3b4c-4d5e-8f90-1a2b3c4d5e6f/download",
    "uuid": "9f1c2e7a-3b4c-4d5e-8f90-1a2b3c4d5e6f",
    "relative_time": "2 hours ago",
    "file": {
      "is_image": false,
      "orig_file_name": "jane_doe_resume.pdf",
      "file_ext": "pdf",
      "file_type": "application/pdf",
      "readable_size": "100kB"
    },
    "text": "Jane Doe — Senior Backend Engineer\n8 years building distributed systems…"
  },
  "rejected_at": null,
  "rejection_reason": null,
  "hired_at": null,
  "hiring_team": null,
  "custom_fields": null,
  "created_at": 1781434800,
  "updated_at": 1781434800,
  "last_message_at": null,
  "days_since_last_message": null,
  "ai_score": null,
  "ai_recommendation": null,
  "ai_scoring_updated_at": null,
  "candidate": {
    "id": 390217,
    "alias": "jane-doe",
    "company_id": 1007,
    "first_name": "Jane",
    "last_name": "Doe",
    "emails": ["jane.doe@example.com"],
    "phones": ["+1 555 123 4567"],
    "source": { "id": 5, "name": "LinkedIn" },
    "origin": { "id": 2, "name": "Career site" },
    "profile": [
      { "question_id": 1, "question_text": "First name", "value": "Jane" },
      { "question_id": 3, "question_text": "Email", "value": "jane.doe@example.com" }
    ]
  }
}

Field reference:

• id — application id. candidate_id, job_id, company_id — related entity ids.
• job_alias — the job's URL slug; internal_job_id — human-facing job number (present when set).
• stage — current pipeline stage { id, name }, or null. status — active, rejected, or hired.
• is_disqualified — true when the application has been rejected/disqualified.
• url_backoffice — deep link to the application in the 100hires back office.
• cv — résumé { url, uuid, relative_time, file { … }, text }, or null when there is no résumé. text is the parsed résumé content (can be large).
• rejected_at / hired_at — Unix timestamps, or null. rejection_reason — array of { id, name }, or null.
• created_at / updated_at / last_message_at — Unix timestamps (seconds; nullable where noted).
• ai_score / ai_recommendation / ai_scoring_updated_at — AI scoring fields, null when not scored.
• candidate — the full applicant object (name, emails, phones, source/origin, profile answers) — same shape as GET /candidates/{id}. Use it to create the lead on your side.

Parse payloads defensively and keep backward compatibility in your consumer.

Event configuration

Event availability can vary by endpoint scope (job/company) and account configuration.

Responding to webhooks

Use idempotent handlers so duplicate deliveries do not create duplicate side effects.

Delivery history

Log incoming webhook IDs and processing results for replay, debugging, and audit.

Common Workflows

Search and review a candidate

Using the 100Hires ATS API you can search for candidates and review their full profile, application history, and communication timeline.

1. GET /candidates?q=John — find candidate by name or email
2. GET /candidates/{id} — full profile with application history
3. GET /candidates/{id}/activities — timeline (notes, calls, AI scoring)
4. GET /candidates/{id}/messages — email conversation history

Manage hiring pipeline

Using the 100Hires ATS API you can manage your hiring pipeline by filtering candidates by stage, advancing or rejecting applications, and performing bulk stage transitions.

1. GET /applications?job_id=123&stage_id=456 — candidates at a specific stage
2. POST /applications/{id}/move with {"stage_id": 789} — advance candidate
3. POST /applications/{id}/reject — reject with optional reason
4. POST /applications/batch/move — bulk stage transition

Publish a job

Using the 100Hires ATS API you can create job drafts, publish them, and distribute to multiple job boards in one request.

1. POST /jobs — create job draft
2. POST /jobs/{id}/status with {"status": "Public"} — publish
3. GET /jobs/{id}/job-boards — available boards
4. POST /jobs/batch-job-boards — publish to multiple boards

Schedule an interview

Using the 100Hires ATS API you can check interviewer availability and schedule interviews for application candidates.

1. GET /interviews?interviewer_user_id=5 — check interviewer availability
2. POST /applications/{id}/interviews — create interview for application

Evaluate a candidate

Using the 100Hires ATS API you can retrieve evaluation forms and review candidate scores and feedback.

1. GET /applications/{id}/evaluation-forms — list filled evaluations
2. GET /evaluation-forms/{id} — detailed form with answers and scores

Send an email

Using the 100Hires ATS API you can send emails to candidates, schedule bulk messages, and cancel pending deliveries.

1. GET /candidates/{id}/messages — check conversation history
2. (Optional) GET /users/{user_id}/mail-accounts — find mail_account_id to send from a specific user's mailbox
3. POST /candidates/{id}/messages — schedule email (use from_account_id to send from a specific mailbox; 15-min cancel window by default)
4. POST /messages/batch/create — schedule up to 100 emails in one request (each with its own candidate_id)
5. DELETE /messages/{id} — cancel before send

Monitor outreach by mail account

Using the 100Hires ATS API you can monitor outreach by tracking messages sent from specific mail accounts.

1. GET /companies/mail-accounts or GET /users/{user_id}/mail-accounts — find mail_account_id
2. GET /messages?from_account_id={id} — list all messages sent/scheduled from that account
3. Filter by status=scheduled to see pending queue, status=sent for delivery history
4. Use date_from / date_to (unix timestamps) to narrow the time range

Send an email from another team member's mailbox

Using the 100Hires ATS API you can send emails from any team member's connected mailbox.

1. GET /users — find the user_id of the team member
2. GET /users/{user_id}/mail-accounts — get their mail_account_id
3. POST /candidates/{id}/messages with from_account_id — send from their mailbox

Tag and organize candidates

Using the 100Hires ATS API you can tag candidates individually or in bulk for better organization.

1. POST /candidates/{id}/tags with ["senior", "remote"] — add tags
2. POST /candidates/batch/tags — bulk add tags
3. DELETE /candidates/batch/tags — bulk remove tags

IDs, aliases, and building UI links

Every candidate and job has a short alias (e.g. dtGeby2, 79SZHfT) — the same string used in 100Hires UI URLs.

Using aliases in API requests

For candidates and jobs, the {id} path parameter accepts either a numeric ID or an alias:

• GET /candidates/42 and GET /candidates/dtGeby2 both return the same candidate.
• GET /jobs/1 and GET /jobs/79SZHfT both return the same job.
• This also works for their sub-resources: GET /candidates/dtGeby2/activities, PUT /jobs/79SZHfT, etc.
• All other endpoints (applications, notes, interviews, etc.) accept only numeric IDs.

Alias fields in responses

• GET /candidates and GET /candidates/{id} return alias field for each candidate.
• GET /jobs and GET /jobs/{id} return alias field for each job.
• GET /applications and GET /applications/{id} return job_alias field alongside job_id.

Building UI links from API data

Use aliases to construct direct links to 100Hires UI:

• Candidate profile: https://app.100hires.com/candidate/{candidate_alias}
• Candidate on a specific job pipeline: https://app.100hires.com/candidate/{candidate_alias}/{job_alias}
• Job pipeline: https://app.100hires.com/job/{job_alias}/candidates/pipeline

This is useful for generating clickable links in reports, sales pipeline audits, and automation outputs.

Error handling

All errors are wrapped in an error object. The format is consistent across all endpoints:

{"error": {"name": "Not Found", "message": "Candidate not found", "code": 0, "status": 404}}

Validation errors include field-level details in validation_errors:

{"error": {"name": "Validation Error", "message": "", "code": 0, "status": 400, "validation_errors": {"email": "Email cannot be blank."}}}