---
title: "Bulk create or update candidates (Upsert)"
method: POST
path: "/v1/candidates/bulk"
tags: ["Bulk Candidates"]
---

# Bulk create or update candidates (Upsert)

`POST /v1/candidates/bulk`

Bulk create or update candidates by unique ID. All valid attributes, including null values, will be written to the candidate.

## Request body

- object
  - `candidates` object[], required
    - `name` string, nullable
    - `email` string, email, nullable, required
    - `phone_number` string, nullable
    - `opted_in` boolean, nullable
    - `unsubscribed_at` string, date-time, nullable

## Response `200`

successful

- object
  - `data` BackgroundTask, required
    - `id` integer, required
    - `account_id` integer, required
    - `project_id` integer, nullable
    - `user_id` integer, required
    - `status` 'pending' | 'processing' | 'finished' | 'failed' | 'cancelled' | 'failed_internal', required
    - `finished_at` string, date-time, nullable, required
    - `error_message` string, nullable, required
    - `action` 'bulk_delete' | 'bulk_edit_candidates' | 'bulk_create_candidates' | 'bulk_shortlist' | 'create_and_shortlist', required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `401` — unauthorized
- `422` — request candidate limit exceeded

---

[API](https://skmtc.dev/greatquestion/apis/api-reference-v1.md) · [All operations](https://skmtc.dev/greatquestion/apis/api-reference-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/greatquestion/api-reference-v1/revisions/f263ec4858a6/schema)