Articles on: Integrations

Developer API v2 Overview

Introduction


The 100Hires Developer API v2 is a REST API for building custom integrations on top of your recruiting workflow. Use it to programmatically create candidates, move applications through pipeline stages, send messages, trigger AI scoring, or sync data with another system.


The API is designed for developers and technical teams. If you want a conversational interface that AI assistants (Claude, ChatGPT, Cursor) can drive for you, see the MCP server section below. MCP sits on top of the same API and exposes recruiting actions as natural-language tools. Use the Developer API directly when you need code, deterministic behavior, or a tight loop with your own systems.


Typical users:


  • Engineering teams building a custom recruiter dashboard
  • HR systems that need a two-way sync with 100Hires
  • Staffing agencies running white-label career sites for clients
  • Automation owners pushing candidates in from sourcing tools


Getting Started


Generate an API key


  1. Open your 100Hires account.
  2. Go to Settings, then Integrations.
  3. Locate the API section and generate a new key.
  4. Copy the key once. Treat it like a password.


Keys are tied to a user and inherit that user's permissions. For a service-style key, create a dedicated user for the integration.


Account verification


API keys only work for verified accounts. Unverified accounts get an authorization error even with a valid key. Complete account verification first, then generate the key.


Base URL and authentication


All requests go to:


https://api.100hires.com/v2/


Authenticate every request with a bearer token:


Authorization: Bearer YOUR_API_KEY


A minimal request to list jobs:


curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.100hires.com/v2/jobs


Responses are JSON. Write requests must send Content-Type: application/json and a JSON body. Form-encoded payloads are not supported.


Capability Categories


The API covers the full recruiting lifecycle. Each category maps to a set of endpoints in the OpenAPI spec.


  • Candidate Management - create, read, update, delete candidates; manage tags, sources, custom profile fields.
  • Job Management - full CRUD on jobs, status changes, custom variables.
  • Application & Pipeline - move applications between stages, disqualify, hire, list stage history.
  • AI Scoring - trigger an AI score on a candidate against a job, and fetch existing scores.
  • Messages - send candidate emails and SMS, batch send, retrieve message history.
  • Email Templates - create, list, update reusable templates with placeholder support.
  • Workflows & Automations - list and create workflows and the pipeline stages inside each.
  • Webhooks - subscribe to events at the company level or per job.
  • Career Site - read public job listings and submit applications from a custom career page.
  • Company Management - companies and users, plus read-only billing.


OpenAPI Specification


The authoritative, machine-readable reference for every endpoint and schema lives at:


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


It is regenerated whenever the API changes. Import it into Postman or any OpenAPI client, feed it into an SDK generator for typed clients, or browse it in a Swagger UI viewer. If behavior differs from the spec, the spec is the source of truth.


Use Case Examples


Teams commonly use the Developer API to build:


  • Recruiting automation bots that move applications, send templated outreach, and broadcast events to chat tools.
  • Custom career pages that read open jobs from 100Hires and submit applications without candidates leaving your domain.
  • CRM sync with HubSpot, Salesforce, or any internal CRM, so hires and source attribution land alongside revenue data.
  • Outreach at scale by pushing sourced leads into 100Hires as candidates with the right tags, then triggering nurture sequences.
  • Custom dashboards that pull pipeline metrics and AI scores into your BI tool.
  • Multi-location management for organizations running parallel pipelines per region.
  • Staffing-agency white-label portals where each client sees their own jobs and candidates from a single backend.


Notes and @mentions


When you post a note via POST /notes, you can tag a teammate so they get a notification. Two things must line up:


  1. The note body uses @<FullName> syntax, exactly as it appears on the teammate's profile. For example, @Alex Kravets, not @Alex or @alex.
  2. The request payload includes a mention_user_ids array listing the user IDs of every teammate mentioned in the body.


If you write @<FirstName> only, or you forget mention_user_ids, the note is created but no notification is sent. Both pieces are required.


Example payload:


{
  "candidate_id": "abc123",
  "body": "Heads up @Alex Kravets, strong fit for the senior role.",
  "mention_user_ids": [42],
  "visibility": "all"
}


MCP Server


MCP, the Model Context Protocol, is a newer way to expose your 100Hires data and actions to AI assistants. The 100Hires MCP server sits on top of the same Developer API, but instead of writing code, your team runs recruiting workflows by chatting with Claude, ChatGPT, Cursor, or any MCP-compatible assistant.


Examples once MCP is connected:


  • "Find every candidate who applied this week with a portfolio link, then move them to screening."
  • "Draft a rejection note for everyone disqualified yesterday and queue it for my review."
  • "Show me open jobs in Berlin with fewer than five applications."


MCP Server URL:


https://mcp.100hires.com/mcp


The MCP server has its own setup article. If your team prefers natural language over code, start there. For precise, repeatable, programmatic control, stay with the Developer API.


Rate Limits


The API enforces per-account rate limits to protect platform stability. Limits apply across all keys belonging to your company, not per key, so creating multiple keys does not give you more throughput. If you hit the limit, requests return HTTP 429 with a Retry-After header. Build retry with exponential backoff into any production integration, and use batch endpoints (batch messages, batch tags) instead of looping single calls.


Authentication Errors


The two most common errors are HTTP 401 (token missing, malformed, or revoked) and HTTP 403 (token is valid but the user lacks permission, or the account is not verified). If you see 401, regenerate the key and confirm it is sent as Authorization: Bearer YOUR_KEY. If you see 403, check the user's role for the endpoint, and confirm account verification is complete.


Support


If something is not covered by the OpenAPI spec, or you need help designing an integration, contact 100Hires support through the in-app chat. Include the endpoint, the request body, the response status code, and the response body.



  • 100Hires MCP server setup and usage
  • Webhook setup and event reference
  • Email templates and placeholders


Updated on: 14/06/2026

Was this article helpful?

Share your feedback

Cancel

Thank you!