# Create and manage draft hires

> Use the Draft Hires REST API to create draft hires and hire them in bulk.

## Overview

A draft hire is a record for a candidate who has received or accepted an offer. Pushing them to Rippling via the API does **not** hire them automatically. Instead, it creates a pending record that a manager or HR admin must review and finalize inside Rippling.

> **Supported countries:**
> Direct hire and employer-of-record (EOR) hires are currently supported in Australia (`AU`), Canada (`CA`), Switzerland (`CH`), China (`CN`), Germany (`DE`), Spain (`ES`), France (`FR`), the United Kingdom (`GB`), Hong Kong (`HK`), Ireland (`IE`), India (`IN`), the Netherlands (`NL`), New Zealand (`NZ`), and the United States (`US`).

### Available endpoints

| Endpoint | Description |
| --- | --- |
| [POST Create hire](https://developer.rippling.com/documentation/rest-api/reference/create-hires) | Creates or continues hire records for admin review using shared and country-specific hiring fields. |
| [GET Get hire requirements](https://developer.rippling.com/documentation/rest-api/reference/get-hire-requirements) | Retrieves required fields, versioning, and validation for a given country code and hire type. |
| [POST Create bulk draft hire](https://developer.rippling.com/documentation/rest-api/reference/create-draft-hires) | Use only for existing integrations built on this contract. For new integrations, use [POST Create hire](https://developer.rippling.com/documentation/rest-api/reference/create-hires). |

Related endpoints:

| Endpoint | Description |
| --- | --- |
| [GET List employment types](https://developer.rippling.com/documentation/rest-api/reference/list-employment-types) | Lists employment types. |
| [GET List work locations](https://developer.rippling.com/documentation/rest-api/reference/list-work-locations) | Lists work locations. |
| [GET List departments](https://developer.rippling.com/documentation/rest-api/reference/list-departments) | Lists departments. |
| [GET List workers](https://developer.rippling.com/documentation/rest-api/reference/list-workers) | Lists workers. |
| [GET List custom fields](https://developer.rippling.com/documentation/rest-api/reference/list-custom-fields) | Lists custom fields. |
| [POST Create a new file](https://developer.rippling.com/documentation/rest-api/reference/create-files) | Uploads a file. Use the file ID for country fields such as `resume_file_id`. |

### Suggested workflow

1.  [Get hire requirements](https://developer.rippling.com/documentation/rest-api/reference/get-hire-requirements) for the hire’s country.
2.  List employment types, work locations, and any other IDs marked as required from GET hire requirements.
3.  [Create the hire](https://developer.rippling.com/documentation/rest-api/reference/create-hires).
4.  Read `status` on each result. `ready_for_review` means the required public fields are present, and `incomplete` lists the remaining paths in `missing_required_fields`.
5.  In Rippling, finish the hire from the **People** tab.

* * *

## Requirements

-   The Rippling API SKU
-   An API token with the following scopes:
    -   `hires.read-write` for [POST Create hire](https://developer.rippling.com/documentation/rest-api/reference/create-hires)
    -   `hire-requirements.read` for [GET Get hire requirements](https://developer.rippling.com/documentation/rest-api/reference/get-hire-requirements)
    -   `draft-hires.read-write` for legacy integrations using [POST Create bulk draft hire](https://developer.rippling.com/documentation/rest-api/reference/create-draft-hires)
    -   Other relevant scopes for listing employment types, departments, work locations, etc.

* * *

## Fetch hire requirements

Use [GET Get hire requirements](https://developer.rippling.com/documentation/rest-api/reference/get-hire-requirements) to return baseline required fields for a country and hire type. `country_code` and `hire_type=direct_hire` are required query parameters.

_Request:_

```json
curl -L -X GET 'https://rest.ripplingapis.com/hire-requirements/?country_code=US&hire_type=direct_hire'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'
```

_Response:_

```json
{
  "requirements_version": "2026-09-25.us-direct-hire.v10",
  "country_code": "US",
  "hire_type": "direct_hire",
  "required_groups": [
    "personal",
    "work_location",
    "employment",
    "compensation"
  ],
  "fields_by_group": {
    "personal": [
      {
        "field": "last_name",
        "type": "string",
        "requiredness": "required"
      }
    ],
    "work_location": [
      {
        "field": "location_id",
        "type": "string",
        "requiredness": "optional",
        "description": "Office this person will work from. Skip this if they work remotely."
      },
    ],
    "employment": [
      {
        "field": "title",
        "type": "string",
        "requiredness": "required"
      },
   ],
    "compensation": [
      {
        "field": "base_pay_amount",
        "type": "object",
        "requiredness": "required",
        "description": "Salary as currency (such as USD) and value (such as 120000)."
      },
    ],
  },
}
```

| Response field | Description |
| --- | --- |
| `requirements_version` | Catalog snapshot ID. Also returned as the `ETag` header. |
| `country_code` | Country used for the lookup. |
| `hire_type` | Hire type used for the lookup. [POST Create hire](https://developer.rippling.com/documentation/rest-api/reference/create-hires) uses the same value. |
| `required_groups` | Groups you must send for this country. |
| `fields_by_group` | Field catalog for this country, grouped by request section. |
| `unsupported_fields` | Public field paths that are not writable for this country and hire type. |
| `warnings` | Non-fatal warnings for this lookup. |

* * *

## Create a hire

Use [POST Create hire](https://developer.rippling.com/documentation/rest-api/reference/create-hires) to create or continue hire records for admin review in Rippling.

**Notes:**

-   Send `Idempotency-Key` on every API call and use the same key if retrying.
-   Each call accepts one to five hires. To create more hires, send another call with its own `Idempotency-Key`.
-   `hire_type` defaults to `direct_hire`. Send `eor` for an employer-of-record hire.
-   Include required employment fields listed from [GET Get hire requirements](https://developer.rippling.com/documentation/rest-api/reference/get-hire-requirements) for that specific country.
-   For file fields like `employment.resume_file_id`, upload the file using [POST Create a new file](https://developer.rippling.com/documentation/rest-api/reference/create-files), `PUT` the bytes to the returned URL, then confirm the upload before sending the file ID. A raw file URL is not accepted.

_Request:_

```json
curl -L -X POST 'https://rest.ripplingapis.com/hires/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer REDACTED'
-H 'Idempotency-Key: ats-offer-1001'
```

_Request body:_

```json
{
  "hires": [
    {
      "client_request_id": "ats-offer-1001",
      "hire_type": "direct_hire",
      "personal": {
        "first_name": "Carter",
        "last_name": "Gordon",
        "invite_email": "cgorden2@test.com"
      },
      "work_location": {
        "location_id": "674c178fc3f93afc69715ef4",
        "country_code": "US"
      },
      "employment": {
        "title": "Engineer",
        "start_date": "2026-12-01",
        "employment_type_id": "674c1785c3f93afc69715d93",
        "legal_entity_id": "674c17a6c3f93afc6971617e",
        "department_id": "674c17a3c3f93afc697160d2",
        "manager_id": "674c17adc3f93afc697169d5",
        "work_email": "cgorden@cooperhaley.com",
        "overtime_exemption": "EXEMPT"
      },
      "compensation": {
        "base_pay_amount": {
          "currency_type": "USD",
          "value": 120000
        },
        "base_pay_period": "YEAR"
      },
      "related_records": {
        "ats_applicant_id": "greenhouse-candidate-1001"
      }
    }
  ]
}
```

| Request body field | Required | Description |
| --- | --- | --- |
| `hires` | Yes | One to five hire objects. |
| `client_request_id` | No | Caller ID echoed on that hire’s result. |
| `hire_type` | No | `direct_hire` or `eor`. An omitted value defaults to `direct_hire`. |
| `personal.first_name` | Yes | Legal first name. |
| `personal.last_name` | Yes | Legal last name. |
| `personal.invite_email` | One of | Email used to invite this person. Send this or `personal.invite_phone`. |
| `personal.invite_phone` | One of | Mobile number, including country code, such as `+14155550123`. |
| `work_location.country_code` | Yes | Country this person works in. Required for office and remote hires. |
| `work_location.location_id` | No | Office location ID. Omit for a remote hire. |
| `employment.title` | Yes | Job title. |
| `employment.start_date` | Yes | Start date in `YYYY-MM-DD` format. |
| `employment.employment_type_id` | Yes | Employment type ID. |
| `employment.legal_entity_id` | Yes for direct hire | Legal entity ID. Omit for `eor`. |
| `employment.department_id` | No | Department ID. |
| `employment.manager_id` | No | Manager worker ID. |
| `employment.work_email` | No | Work email. |
| `employment.overtime_exemption` | No | `EXEMPT` or `NON_EXEMPT`. |
| `compensation.base_pay_amount.currency_type` | Yes | Currency code, such as `USD`. |
| `compensation.base_pay_amount.value` | Yes | Base pay amount. |
| `compensation.base_pay_period` | Yes | `YEAR`, `MONTH`, `WEEK`, `DAY`, or `HOUR`. |
| `related_records.ats_applicant_id` | No | Applicant ID from the ATS. |

_Response:_

```json
{
  "ack": true,
  "results": [
    {
      "client_request_id": "ats-offer-1001",
      "id": "68efdd0995c096c490a0012a",
      "existing_role_id": null,
      "status": "ready_for_review",
      "missing_required_fields": [],
      "pending_fields": [],
      "errors": [],
      "next_actions": []
    }
  ]
}
```

| Response field | Description |
| --- | --- |
| `ack` | `true` when the envelope was accepted for processing. |
| `results` | One result per hire, in request order. |
| `results.client_request_id` | Echo of the caller-supplied ID. |
| `results.id` | Rippling hire role ID when a role exists. |
| `results.existing_role_id` | Matching role ID for a duplicate or rehire conflict. |
| `results.status` | `ready_for_review` (required public fields are present and an admin can review the hire), `incomplete` (`missing_required_fields` lists the public field paths still required before review), or `failed` (the item was not created; refer to `errors`). |
| `results.missing_required_fields` | Public field paths still required before review. |
| `results.pending_fields` | Accepted field paths that are not active yet because progression is blocked. |
| `results.errors` | Item errors. |
| `results.errors.code` | Machine-readable error code. |
| `results.errors.field` | Public field path when the error is field-scoped. |
| `results.errors.message` | Human-readable error message. |
| `results.next_actions` | Resolution actions for a duplicate or rehire conflict. |
| `results.next_actions.code` | Machine-readable next action. |
| `results.next_actions.target_id` | Role ID to continue, when one applies. |

* * *

## Create a legacy draft hire

Use [POST Create bulk draft hire](https://developer.rippling.com/documentation/rest-api/reference/create-draft-hires) for an integration already built on this contract.

**Notes:**

-   Each draft hire requires `personal_info` (including `name` and `invite_email`), `employment_info.title`, `employment_info.employment_type_id`, and `work_location_info`.
-   `overtime_exemption` is `exempt` or `non-exempt`.
-   `custom_fields` is an array of `field_name` and `field_value`.
-   This endpoint also accepts compensation amounts on `employment_info`, `headcount_info`, and `documents`.
-   A single call supports a maximum of 5 draft hires.

_Request:_

```json
curl -L -X POST 'https://rest.ripplingapis.com/draft-hires/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer REDACTED'
```

_Request body:_

```json
{
  "draft_hires": [
    {
      "personal_info": {
        "name": {
          "first": "Carter",
          "last": "Gordon"
        },
        "invite_email": "cgorden2@test.com"
      },
      "employment_info": {
        "start_date": "2026-12-01T00:00:00",
        "title": "Engineer",
        "job_family_id": "6797e9ced6c45773dde9cdfd",
        "department_id": "674c17a3c3f93afc697160d2",
        "employment_type_id": "674c1785c3f93afc69715d93",
        "legal_entity_id": "674c17a6c3f93afc6971617e",
        "manager_id": "674c17adc3f93afc697169d5",
        "work_email": "cgorden@cooperhaley.com",
        "overtime_exemption": "exempt"
      },
      "work_location_info": {
        "location_id": "674c178fc3f93afc69715ef4"
      },
      "custom_fields": [
        {
          "field_name": "66a7d17398f2ee7f0d2aa787",
          "field_value": {}
        }
      ]
    }
  ]
}
```

| Request body field | Required | Description |
| --- | --- | --- |
| `draft_hires` | Yes | List of draft hires. A single call supports a maximum of 5. |
| `personal_info.name` | Yes | Candidate name. |
| `personal_info.name.first` | No | First name. |
| `personal_info.name.last` | No | Last name. |
| `personal_info.invite_email` | Yes | Invite email. |
| `employment_info.title` | Yes | Job title. |
| `employment_info.employment_type_id` | Yes | Employment type ID. |
| `employment_info.start_date` | No | Start date. |
| `employment_info.job_family_id` | No | Job family ID. |
| `employment_info.department_id` | No | Department ID. |
| `employment_info.legal_entity_id` | No | Legal entity ID. |
| `employment_info.manager_id` | No | Manager ID. |
| `employment_info.work_email` | No | Work email. |
| `employment_info.overtime_exemption` | No | `exempt` or `non-exempt`. |
| `work_location_info` | Yes | Work location object. |
| `work_location_info.location_id` | No | Office location ID. |
| `custom_fields` | No | Array of custom fields. |
| `custom_fields.field_name` | Yes, when a custom field is sent | Custom field ID. |
| `custom_fields.field_value` | Yes, when a custom field is sent | Custom field value. |

_Response:_

```json
{
  "invalid_items": [],
  "successful_results": [
    {
      "draft_hire_role_id": "68efdd0995c096c490a0012a",
      "status": "success",
      "message": "Draft hire created",
      "errors": [],
      "document_results": null
    }
  ]
}
```

| Response field | Description |
| --- | --- |
| `invalid_items` | Draft hires that were not created. Each item uses the same fields as `successful_results`. |
| `successful_results` | Draft hires that were created. |
| `draft_hire_role_id` | ID of the created draft hire. |
| `status` | `success`, `error`, or `warning`. |
| `message` | Success or error message. |
| `errors` | Validation error strings for that item. |
| `document_results` | Per-document attach results when `documents` were sent. null when no documents were sent. |
| `document_results.file_id` | Uploaded file ID. |
| `document_results.document_id` | Document ID created on the draft hire. |
| `document_results.status` | Per-document status, such as `success`. |
| `document_results.error` | Error for that document. null when the document attached successfully. |

* * *

## Hire the draft hires in Rippling

After the records are pushed into Rippling, an admin completes the hiring flow in the Rippling UI.

1.  Navigate to the **People** app.
2.  Select the **Hire** option on the top right of the screen.
3.  Select **Multiple people** under **Who are you hiring?**.
4.  Select that you’d like to hire **New Candidates**.
5.  An option should be available to **Select draft hires from external system**. You can select the pre-existing draft hire roles and continue with the hiring flow.

### Tips for bulk hiring

-   Bulk hiring must be done by worker type and country.
-   Contractors can only be hired in bulk with other Contractors.
-   Full-time employees can only be hired in bulk with other full-time employees from the same country.
-   You cannot mix Contractors and full-time employees in the same bulk hire.
-   You cannot hire full-time employees from multiple countries in a single bulk hire.

### Video tutorial

#### Using bulk hiring

[iframe](https://www.loom.com/embed/c12fef889d03437d86cd89f7d5f99309)

* * *

## See also

-   [Get started with the HRIS API](https://developer.rippling.com/documentation/rest-api/guides/hris-getting-started)
-   [API tokens and permissions](https://developer.rippling.com/documentation/rest-api/essentials/api-tokens)

Source: https://developer.rippling.com/documentation/rest-api/guides/drafthires

> For the complete documentation index, see [llms.txt](https://developer.rippling.com/llms.txt). Public pages have a Markdown version at the same URL with .md added.
