> ## 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.

# Candidate Data & Submissions

> Retrieve candidate data and form submissions for multiple applications

## Retrieve Candidate Data and Submissions

Fetch candidate details and form submissions for a set of application IDs that all belong to the same hiring flow. Also supports GET requests with query parameters.

### Endpoints

```
POST /external/v1/get_candidate_data_and_submissions/
GET  /external/v1/get_candidate_data_and_submissions/
```

### Authentication

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

### Request Body (POST)

| Field             | Type             | Required | Description                                                                                                             |
| ----------------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `application_ids` | array of strings | Yes      | Array of application IDs. All must belong to the same hiring flow                                                       |
| `variable_ids`    | array of strings | No       | Array of variable IDs to retrieve values for. If not provided, values for all variables in the hiring flow are returned |

### Query Parameters (GET)

| Parameter         | Type             | Required | Description                       |
| ----------------- | ---------------- | -------- | --------------------------------- |
| `application_ids` | array of strings | Yes      | Array of application IDs          |
| `variable_ids`    | array of strings | No       | Array of variable IDs to retrieve |

### Example Request

```bash theme={null}
curl -X POST "https://api.firstwork.com/external/v1/get_candidate_data_and_submissions/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "application_ids": [
      "3f9e3d7a-2a6b-4c3d-9b0a-1d2e3f4a5b6c",
      "7b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e"
    ],
    "variable_ids": [
      "HIRING_FLOW.ba6760f8-6686-473f-aac2-be0b8d997907.FORM.83435706-5efe-44ce-ba40-c994d982649b",
      "USER.PERSONAL_INFORMATION.last_name"
    ]
  }'
```

### Response Structure

| Field                         | Type   | Description                                                           |
| ----------------------------- | ------ | --------------------------------------------------------------------- |
| `labels_map`                  | object | Mapping of data keys to human-readable labels                         |
| `data`                        | array  | Array of application records with key/value pairs for each data point |
| `unavailable_application_ids` | array  | Application IDs for which data could not be fetched                   |
| `errored_request_variables`   | array  | Invalid variable IDs that were requested                              |

### Responses

#### 200: OK

Successfully retrieved candidate data and submissions.

#### 400: Bad Request

Invalid ID, number of applications exceeds the cap (50), no matching applications found, or IDs span multiple flows.

#### 404: Not Found

Referenced flow does not exist or no applications could be fetched.

#### 500: Internal Server Error

Unexpected error.

### Notes

* Maximum of 50 applications per request
* All application IDs must belong to the same hiring flow