---
title: "Create an applicant"
method: POST
path: "/external-hires/applicants"
tags: ["Applicants"]
---

# Create an applicant

`POST /external-hires/applicants`

## Request

- Base URL: `https://api.hibob.com/v1`
- URL: `https://api.hibob.com/v1/external-hires/applicants`
- Auth: HTTP bearer

Submits a hired candidate into Bob as a pending hire. The record is added to
ATS Pending Hires; an employee is created only after HR activates the New Hire
flow. Only fields that are part of that New Hire flow are populated on the
employee. One applicant per request.

A 201 response does not guarantee all documents were uploaded. Always inspect
warnings. When every document downloads successfully (or the request carries
none), the body is `{ "id": ... }` with no `warnings` key. When one or more
documents fail to download, `warnings` lists each failed file; the applicant
is still stored.

**OAuth scopes (app-user):** `applicants:write`

**Rate limit:** 10 requests per minute per authenticated company.

## Request body

- CreateApplicantInput
  - `fields` object, required: Flat map of Bob employee field `id` to value. Keys come from `GET /v1/company/people/fields` (for example `root.firstName`). The supported value shape depends on the field type: JSON scalars (`string`, `number`, `boolean`) or nested objects for complex types (for example `payroll.salary.payment: { "value": 85000, "currency": "GBP" }`). Dates use `YYYY-MM-DD` strings. See <a href="https://apidocs.hibob.com/docs/fields-metadata#field-types">Field types</a> for the full catalog. **Required:** `root.firstName` (string), `root.surname` (string). **Recommended:** `root.email` (string), `work.startDate` (`YYYY-MM-DD`), `work.title` (string), `work.department` (string), `work.siteId` (site name string, for example `"London"`, not a numeric id). Computed fields (for example `work.durationOfEmployment`) are ignored and logged. Unresolved complex values are dropped and logged; the request still succeeds when the required fields are present.
  - `documents` ApplicantDocument[], nullable: Files to attach to the pending hire. Each item is an object with `name` (string), `url` (string), and `folderId` (int64 JSON number). Each file is downloaded from `url` and stored under the Bob folder `folderId` (from `GET /v1/docs/folders/metadata`). When omitted, no documents are attached.
    - `name` string, required: File name as it should appear in Bob, including the extension.
    - `url` string, required: HTTPS URL Bob can fetch the file from.
    - `folderId` integer, required: Bob document folder id the file is stored in, sent as a JSON number, not a quoted string.

## Response `201`

Success

- CreateApplicantOutput
  - `id` integer, required: Identifier of the stored pending hire, sent as a JSON number (not a quoted string).
  - `warnings` ApplicantWarning[], nullable: Non-fatal issues with the otherwise accepted applicant. Present only when at least one document failed to download; omitted entirely when every document succeeded or the request carried no documents.
    - `code` string, required: Machine-readable reason. Currently `document_upload_failed` when Bob could not download a file from the partner URL.
    - `message` string, required: Human-readable detail, including the file name. For a failed download the text is `Document upload failed for <filename>`.

## Other responses

- `400`: Bad request, the request was malformed, missing required fields, or did not match the schema
- `401`: Unauthorized, authentication credentials are missing or invalid
- `403`: Forbidden, the authenticated user does not have permission to perform this operation
- `429`: Too many requests, rate limit exceeded, retry after the indicated delay
- `500`: Internal server error, an unexpected error occurred on the server

---

[API](https://skmtc.dev/hibob/apis/applicant-api.md) - [All operations](https://skmtc.dev/hibob/apis/applicant-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hibob/apis/applicant-api/revisions/2272de5903a4?raw)