> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstwork.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create or Update Candidate

> Create a new candidate or update an existing one with form data and documents

## Create or Update Candidate

Create a new candidate or update an existing one. Supports form element data, OG variable updates, document uploads, and stage transitions.

### Endpoint

```
POST /external/v1/create_or_update_candidate
```

### Authentication

> \[!NOTE]
> Requires a valid company API key in the `Authorization` header (format: `Api-Key <key>`).

### Request Body

Send as `multipart/form-data` to support file uploads alongside data fields.

**Identification (at least one required):**

| Field                 | Type          | Required    | Description                                                                                                                |
| --------------------- | ------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
| `external_identifier` | string        | Conditional | Unique user identifier. Required if `application_id` not provided. Used with `flow_id` to create or look up an application |
| `application_id`      | string (UUID) | Conditional | ID of an existing application to update. Required if `external_identifier` not provided                                    |
| `flow_id`             | string (UUID) | Conditional | The hiring flow ID. Required if `application_id` not provided                                                              |

**Candidate data:**

| Field                       | Type          | Required | Description                                                                              |
| --------------------------- | ------------- | -------- | ---------------------------------------------------------------------------------------- |
| `full_name`                 | string        | No       | Full name of the user. First, middle, and last names are updated by splitting this value |
| `phone_number`              | string        | No       | Phone number. Only used when creating a new application                                  |
| `page_or_stage_id`          | string (UUID) | No       | Stage ID to move the candidate to                                                        |
| `stage_reason_id`           | string (UUID) | No       | Stage reason ID for the transition                                                       |
| `is_test`                   | string        | No       | Set to `"true"` to mark as a test application (only for new applications)                |
| `requires_async_processing` | string        | No       | Set to `"true"` for async processing (returns 202 instead of 200)                        |

**Form element data:** Any key that is a valid form element ID will be treated as a form element update. The value can be a string or a file upload.

**OG variable paths:** Keys containing two or more dots (e.g., `namespace.category.variable`) are treated as OG variable paths. Only updatable variables are accepted.

### Example Request

```bash theme={null}
curl -X POST "https://api.firstwork.com/external/v1/create_or_update_candidate" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -F "external_identifier=EMP-12345" \
  -F "flow_id=550e8400-e29b-41d4-a716-446655440000" \
  -F "full_name=John Doe" \
  -F "phone_number=+1234567890" \
  -F "elem-uuid-1=Some text value" \
  -F "elem-uuid-2=@/path/to/document.pdf" \
  -F "page_or_stage_id=stage-uuid"
```

### Responses

#### 200: OK

Synchronous success. All form elements processed (including OCR), application status updated, and automations triggered.

#### 202: Accepted

Async accepted. Documents uploaded but OCR, status updates, and automations run asynchronously. Returned when `requires_async_processing` is enabled.

#### 400: Bad Request

Missing identification fields, invalid flow ID, invalid file type, or form element validation failure.

#### 404: Not Found

Application not found for the given `application_id` and company.

#### 500: Internal Server Error

Failed to create/retrieve the candidate or error updating the application status.