recruitee

Fetch the Recruitee user the API token belongs to — name, email, role, role abilities and company id. A cheap way to confirm the token and company id are right. Recruitee: GET /c/{company_id}/admin.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the company's team members (memberships): admin_id, role, whether they are a recruiter or hiring manager, and the jobs they can access. Use admin_id values for task assignees and filters. User names/emails are in the `references` array. Recruitee: GET /c/{company_id}/memberships.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Search by name or email.",
      "type": "string"
    },
    "role_id": {
      "description": "Only members with this role id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "sort_by": {
      "description": "Sort field (default name).",
      "type": "string",
      "enum": [
        "name",
        "role",
        "email"
      ]
    },
    "sort_order": {
      "description": "Sort direction (default asc).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "limit": {
      "description": "Results per page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "page": {
      "description": "Page number, starting at 1.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Search the company's candidates with Recruitee's candidate search (the same engine as the app's filters). `query` is a free-text search across name, emails, phones, tags, sources, job assignments, current stage, cover letter and CV content. `filters` accepts Recruitee filter objects verbatim, e.g. {"field":"created_at","gte":1548975600} (Unix seconds), {"field":"has_cv","eq":true}, {"filter":"tags","id":{"in":[12]}}, {"filter":"stages","name":{"in":["Phone interview"]}}. Returns `hits` (with each candidate's placements: job + current stage) and `total`. Recruitee: GET /c/{company_id}/search/new/candidates.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Free-text search (adds a {\"field\":\"all\",\"query\":...} filter).",
      "type": "string"
    },
    "filters": {
      "description": "Additional Recruitee search filter objects, sent as filters_json.",
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "sort_by": {
      "description": "Sort key with _asc or _desc suffix, e.g. created_at_desc (default), relevance_desc, candidate_name_asc, candidate_rating_desc, candidate_stage_name_asc.",
      "type": "string"
    },
    "limit": {
      "description": "Candidates per page (default 60).",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "page": {
      "description": "Page number, starting at 1.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List candidates, newest first, optionally narrowed to one job, a name/job search, qualified or disqualified only, specific ids, or those created after a date. Paginate with limit + offset (next offset = offset + limit). Recruitee: GET /c/{company_id}/candidates.

{
  "type": "object",
  "properties": {
    "offer_id": {
      "description": "Only candidates on this job/talent pool.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "query": {
      "description": "Search by candidate name or job.",
      "type": "string"
    },
    "qualified": {
      "description": "true = only qualified candidates.",
      "type": "boolean"
    },
    "disqualified": {
      "description": "true = only disqualified candidates.",
      "type": "boolean"
    },
    "ids": {
      "description": "Only these candidate ids.",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "created_after": {
      "description": "Only candidates created after this date (ISO 8601).",
      "type": "string"
    },
    "sort": {
      "description": "Sort order (default by_date).",
      "type": "string",
      "enum": [
        "by_date",
        "by_last_message"
      ]
    },
    "limit": {
      "description": "Candidates per page (default 100, max 1000).",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "offset": {
      "description": "Number of candidates to skip.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fetch one candidate's full profile: contact details, sources, tags, cover letter, CV URL, custom fields, ratings, and `placements` — one per job they are on, each with its placement id and current stage. The placement id is what recruitee_move_candidate_stage needs. Recruitee: GET /c/{company_id}/candidates/{id}.

{
  "type": "object",
  "properties": {
    "candidate_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The candidate id."
    }
  },
  "required": [
    "candidate_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the notes on a candidate's profile, with replies, author admin_id and visibility. Recruitee: GET /c/{company_id}/candidates/{candidate_id}/notes.

{
  "type": "object",
  "properties": {
    "candidate_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The candidate id."
    }
  },
  "required": [
    "candidate_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the company's jobs (Recruitee calls them offers) with id, title, status, slug, department_id, recruiter_id, hiring_manager_id and pipeline_template_id. Filter by status, department, location, recruiter, hiring manager, tag and more; add heavy fields with `include` (e.g. counters for candidate counts, description, salary, location_ids). Paginated with limit + page (default 1000 per page); `meta.total_count` gives the total. Recruitee: GET /c/{company_id}/offers.

{
  "type": "object",
  "properties": {
    "statuses": {
      "description": "Only jobs in these statuses.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "draft",
          "published",
          "internal",
          "closed",
          "archived"
        ]
      }
    },
    "offer_ids": {
      "description": "Only these job ids.",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "department_ids": {
      "description": "Only jobs in these departments.",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "location_ids": {
      "description": "Only jobs at these locations.",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "recruiter_ids": {
      "description": "Only jobs with these recruiters (admin ids).",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "hiring_manager_ids": {
      "description": "Only jobs with these hiring managers (admin ids).",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "tag_ids": {
      "description": "Only jobs with these job tags.",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "priorities": {
      "description": "Only jobs with these priorities.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "urgent",
          "high",
          "normal",
          "low"
        ]
      }
    },
    "employment_types": {
      "description": "Only these employment types, e.g. fulltime.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "categories": {
      "description": "Only these job categories, e.g. information_technology.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "lang_codes": {
      "description": "Only jobs in these languages, e.g. en.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "include": {
      "description": "Extra field groups to return.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "description",
          "requirements",
          "highlight",
          "work_models",
          "salary",
          "dynamic_fields",
          "follower_ids",
          "location_ids",
          "requisition_ids",
          "tags",
          "job_scheduler",
          "issues",
          "counters"
        ]
      }
    },
    "limit": {
      "description": "Jobs per page (default 1000).",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "page": {
      "description": "Page number, starting at 1.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fetch one job or talent pool by id with its full details: description, requirements, location, salary, employment type, candidate counters and pipeline_template_id. Recruitee: GET /c/{company_id}/offers/{id}.

{
  "type": "object",
  "properties": {
    "offer_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The job (offer) id."
    }
  },
  "required": [
    "offer_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fetch a pipeline template with its ordered stages (id, name, group, category). A job's `pipeline_template_id` (from recruitee_list_offers / recruitee_get_offer) names its pipeline; the stage ids here are what recruitee_move_candidate_stage takes. Recruitee: GET /c/{company_id}/pipeline_templates/{id}.

{
  "type": "object",
  "properties": {
    "pipeline_template_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The pipeline template id."
    }
  },
  "required": [
    "pipeline_template_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the company's departments with their ids and job counts. Recruitee: GET /c/{company_id}/departments.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the company's candidate tags with ids and usage counts. Tag ids are used in recruitee_search_candidates filters. Recruitee: GET /c/{company_id}/tags.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Search tags by name.",
      "type": "string"
    },
    "sort_by": {
      "description": "Sort field.",
      "type": "string",
      "enum": [
        "name",
        "taggings_count"
      ]
    },
    "sort_order": {
      "description": "Sort direction (default asc).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the company's configured disqualification reasons (id, name, position). Useful for reading why candidates were disqualified. Recruitee: GET /c/{company_id}/disqualify_reasons.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List recruiting tasks (title, description, due date, completed, candidate_id). With candidate_id, lists that candidate's tasks (Recruitee: GET /c/{company_id}/candidates/{candidate_id}/tasks — only `status` applies). Otherwise lists company tasks with scope, assignee, sorting and paging (Recruitee: GET /c/{company_id}/tasks).

{
  "type": "object",
  "properties": {
    "candidate_id": {
      "description": "Only this candidate's tasks.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "status": {
      "description": "Completed or open tasks only.",
      "type": "string",
      "enum": [
        "completed",
        "uncompleted"
      ]
    },
    "scope": {
      "description": "Whose tasks (company list only).",
      "type": "string",
      "enum": [
        "my",
        "unassigned",
        "all"
      ]
    },
    "admin_ids": {
      "description": "Only tasks assigned to these admin ids (company list only).",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "sort_by": {
      "description": "Sort field (company list only).",
      "type": "string",
      "enum": [
        "due_date",
        "created_at",
        "completed_at"
      ]
    },
    "sort_order": {
      "description": "Sort direction (company list only).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "limit": {
      "description": "Tasks per page (company list only).",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "page": {
      "description": "Page number, starting at 1.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List scheduled interview events (candidate_id, offer_id, stage_id, start time, duration, location, attendees). Defaults to upcoming events for the whole company; narrow by candidate, date range or interviewer. Recruitee: GET /c/{company_id}/interview/events.

{
  "type": "object",
  "properties": {
    "status": {
      "description": "Which events (default upcoming).",
      "type": "string",
      "enum": [
        "upcoming",
        "past_due",
        "all"
      ]
    },
    "scope": {
      "description": "Only mine, or all (default all).",
      "type": "string",
      "enum": [
        "my",
        "all"
      ]
    },
    "candidate_id": {
      "description": "Only this candidate's interviews.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "admin_ids": {
      "description": "Only events assigned to these admin ids.",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "start_date": {
      "description": "Range start, YYYY-MM-DD.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "end_date": {
      "description": "Range end, YYYY-MM-DD.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "timezone": {
      "description": "Timezone for the date range, e.g. Europe/Amsterdam.",
      "type": "string"
    },
    "limit": {
      "description": "Events per page (default unlimited).",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "page": {
      "description": "Page number; only used together with limit.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List interview results — evaluations (rating + note) and questionnaire scorecards — optionally for one candidate or by selected reviewers. Recruitee: GET /c/{company_id}/interview/results.

{
  "type": "object",
  "properties": {
    "candidate_id": {
      "description": "Only this candidate's evaluations.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "kind": {
      "description": "Result kind (default all).",
      "type": "string",
      "enum": [
        "evaluation",
        "questionnaire",
        "all"
      ]
    },
    "scope": {
      "description": "Only mine, or all (default all).",
      "type": "string",
      "enum": [
        "my",
        "all"
      ]
    },
    "admin_ids": {
      "description": "Only results by these admin ids.",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "limit": {
      "description": "Results per page (default unlimited).",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "page": {
      "description": "Page number; only used together with limit.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: add a candidate manually (as if a recruiter added them in the app — no auto-confirmation email is sent), optionally assigning them straight to one or more jobs in the job's default stage. Recruitee: POST /c/{company_id}/candidates.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Candidate's full name (required)."
    },
    "emails": {
      "description": "Email addresses.",
      "type": "array",
      "items": {
        "type": "string",
        "format": "email",
        "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
      }
    },
    "phones": {
      "description": "Phone numbers.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "social_links": {
      "description": "Social profile URLs (e.g. LinkedIn).",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "links": {
      "description": "Other links (portfolio, website).",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "cover_letter": {
      "description": "Cover letter text.",
      "type": "string"
    },
    "sources": {
      "description": "Source tags, e.g. [\"Referral\"].",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "remote_cv_url": {
      "description": "Public URL of the CV file for Recruitee to fetch.",
      "type": "string",
      "format": "uri"
    },
    "offer_ids": {
      "description": "Jobs/talent pools to assign the candidate to (default stage).",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: update a candidate's name or contact details. Only the fields you pass change; list fields (emails, phones, links) REPLACE the existing list, so pass the full list you want. Recruitee: PATCH /c/{company_id}/candidates/{id}.

{
  "type": "object",
  "properties": {
    "candidate_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The candidate id."
    },
    "name": {
      "description": "New full name.",
      "type": "string",
      "minLength": 1
    },
    "emails": {
      "description": "Full replacement list of email addresses.",
      "type": "array",
      "items": {
        "type": "string",
        "format": "email",
        "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
      }
    },
    "phones": {
      "description": "Full replacement list of phone numbers.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "social_links": {
      "description": "Full replacement list of social profile URLs.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "links": {
      "description": "Full replacement list of other links.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "cover_letter": {
      "description": "Cover letter text.",
      "type": "string"
    }
  },
  "required": [
    "candidate_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: add a note to a candidate's profile, visible to the team. Recruitee: POST /c/{company_id}/candidates/{candidate_id}/notes.

{
  "type": "object",
  "properties": {
    "candidate_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The candidate id."
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20000,
      "description": "The note text."
    }
  },
  "required": [
    "candidate_id",
    "body"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: add one or more tags to a candidate (existing tags are reused by name; new names create new tags). Recruitee: POST /c/{company_id}/candidates/{candidate_id}/tags.

{
  "type": "object",
  "properties": {
    "candidate_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The candidate id."
    },
    "tags": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Tag names to add, e.g. [\"Python developer\"]."
    }
  },
  "required": [
    "candidate_id",
    "tags"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: put an existing candidate on a job (or talent pool) — creates a placement in the pipeline's first stage. Pass exactly one of offer_id or talent_pool_id. Recruitee: POST /c/{company_id}/placements.

{
  "type": "object",
  "properties": {
    "candidate_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The candidate id."
    },
    "offer_id": {
      "description": "The job id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "talent_pool_id": {
      "description": "The talent pool id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "candidate_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: move a candidate to another stage of a job's pipeline. Takes the PLACEMENT id (from recruitee_get_candidate → placements[].id, one per job) and the destination stage id (from recruitee_get_pipeline_template). Moving to a 'hired' stage also requires work_location_id. Stage automations configured in Recruitee may run. Undo by moving back. Recruitee: PATCH /c/{company_id}/placements/{id}/change_stage.

{
  "type": "object",
  "properties": {
    "placement_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The placement id (candidate-on-job), not the candidate id."
    },
    "stage_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Destination stage id."
    },
    "work_location_id": {
      "description": "Location id — required by Recruitee when the destination is a hired stage.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "placement_id",
    "stage_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: create a recruiting task, optionally about a candidate, assigned to team members (admin ids from recruitee_list_team_members), with an optional due date. Recruitee: POST /c/{company_id}/tasks.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "description": "Task title (required)."
    },
    "description": {
      "description": "Task details.",
      "type": "string"
    },
    "candidate_id": {
      "description": "Candidate the task is about.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "admin_ids": {
      "description": "Assignees (admin ids).",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "due_date": {
      "description": "Due date/time (ISO 8601). Requires timezone.",
      "type": "string"
    },
    "timezone": {
      "description": "Timezone of the due date, e.g. Europe/Amsterdam.",
      "type": "string"
    }
  },
  "required": [
    "title"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}