---
title: "Upload candidates to a study"
method: POST
path: "/v1/studies/{study_id}/candidates"
tags: ["Studies"]
---

# Upload candidates to a study

`POST /v1/studies/{study_id}/candidates`

Upload up to 5,000 candidates and add them to a study.

A `201 Created` response means the upload was accepted and is still processing. Use the returned
`data.background_task.status_url` to check its status. Wait until the status is `finished` before
uploading another batch to the same study.

## Path parameters

- `study_id` integer, required

## Request body

- object
  - `candidates` object[], required — Candidates to add, up to 5,000 per request
    - `first_name` string
    - `last_name` string
    - `email` string, email
    - `timezone` string

## Response `201`

upload accepted

- object
  - `data` object, required
    - `background_task` BackgroundTaskWithStatusUrl, 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
      - `status_url` string, required — Relative API path to poll until the candidate upload finishes or fails

## Other responses

- `401` — unauthorized
- `403` — unprocessable_entity for deleted study
- `422` — unprocessable_entity for closed study

---

[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)