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

# Candidate Applications

> How candidates apply through TapTalent-hosted application pages, and how to retrieve application details and privacy-consent records for job candidates

Every `ACTIVE` job has a TapTalent-hosted application experience—a hosted application page, with a conversational chat-assisted variant—where candidates submit their details. What the form collects is configured on the job via [`applicationForm`](/api-reference/jobs#applicationform-structure) and [`screeningQuestion`](/api-reference/jobs#create-job). On submission, TapTalent creates or updates the candidate, creates a job-candidate at the pipeline's **APPLIED** stage, records the candidate's privacy consent, and fires the [`candidate.applied`](/webhooks/events#application-events) webhook event.

**Authentication:** `Authorization: Bearer YOUR_API_KEY`—see [API Keys](/authentication/api-keys).

Related: webhook setup is described in [Webhooks Overview](/webhooks/overview); the event payload is in [Application events](/webhooks/events#application-events).

<Info>
  There is no API for submitting applications—applications are accepted only through the TapTalent-hosted application experience for each job. To ingest candidates programmatically, use [Bulk Upload Resumes to Job](/api-reference/job-candidates#bulk-upload-resumes-to-job).
</Info>

## Concepts

| Term                                     | Meaning                                                                                                                                                                                                                                                     |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Hosted application page**              | The TapTalent-hosted page for each `ACTIVE` job where candidates apply. TapTalent hosts it; there is nothing for you to build.                                                                                                                              |
| **Application form**                     | Field-by-field requirement configuration (`MANDATORY`/`OPTIONAL`/`OFF`) set on the job—see [applicationForm Structure](/api-reference/jobs#applicationform-structure). `firstName`, `lastName`, and `email` are always collected.                           |
| **Screening questions**                  | Up to 15 text questions configured on the job; answers are captured at submission.                                                                                                                                                                          |
| **APPLIED stage**                        | Applicants land at the job pipeline's `APPLIED`-type stage. Resolve stage IDs and names via [Pipelines](/api-reference/pipelines).                                                                                                                          |
| **Privacy consent / DPA acknowledgment** | Before submitting, the candidate accepts your privacy notice / data privacy agreement. TapTalent records `acceptedAt` and `policyVersion` and generates a **DPA acknowledgment PDF**. This is a system-generated acknowledgment record, not an e-signature. |
| **Resume parsing**                       | Education and work experience are extracted from the uploaded resume, not asked on the form. They appear on the candidate profile ([Candidates](/api-reference/candidates)).                                                                                |
| **Time-limited URLs**                    | Resume and consent PDF URLs expire—download promptly, or re-fetch fresh URLs from the endpoints below.                                                                                                                                                      |

## How an application flows through TapTalent

1. The candidate opens the job's hosted application page (or the chat-assisted variant).
2. The candidate accepts the privacy notice / DPA.
3. The candidate submits the form: the fields required by the job's `applicationForm`, answers to any screening questions, and their resume.
4. TapTalent creates or updates the candidate, creates the job-candidate at the pipeline's APPLIED stage, records the consent, and generates the DPA acknowledgment PDF.
5. The [`candidate.applied`](/webhooks/events#application-events) event is sent to your webhook endpoint.
6. Resume parsing and AI scoring run in the background (`job.candidate.score.completed` or `.failed` follows); if the job has screening automation configured, it may then move or reject the candidate (`candidate.stage_changed` / `candidate.rejected`).

## Privacy consent at application

The consent record stores when the candidate accepted (`acceptedAt`) and which version of your privacy notice / DPA they accepted (`policyVersion`). The DPA acknowledgment PDF is delivered as a time-limited URL in the `candidate.applied` event and can be re-fetched at any time from [Get Consent Document](#get-consent-document).

Applications submitted before consent capture was enabled for your company have no consent record—`consent` is `null` for those job candidates.

***

## Get Application Details

Retrieve the application a candidate submitted for a job, including form answers, screening answers, the resume URL, and the consent record.

### `GET /job-candidates/:jobCandidateId/application`

### Path Parameters

| Parameter        | Type   | Required | Description       |
| ---------------- | ------ | -------- | ----------------- |
| `jobCandidateId` | number | Yes      | Job-candidate ID. |

### Example Request

```bash theme={null}
curl -X GET "https://partner-api.taptalent.io/v1/partner/job-candidates/101/application" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": {
    "jobCandidateId": 101,
    "jobId": 12345,
    "candidateId": "candidateId_1",
    "appliedAt": 1234567890000,
    "candidate": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+639171234567" },
    "currentJobTitle": "Senior Software Engineer",
    "company": "Tech Innovations Inc.",
    "resumeUrl": "https://cdn.taptalent.io/applications/101/resume.pdf?signature=...",
    "noticePeriod": "2 weeks",
    "isWillingToRelocate": true,
    "expectedCTC": 150000,
    "currencyExpectedCTC": "USD",
    "expectedCTCPeriod": "ANNUALLY",
    "currentCTC": 130000,
    "currencyCurrentCTC": "USD",
    "currentCTCPeriod": "ANNUALLY",
    "gender": null,
    "dateOfBirth": "1990-05-15",
    "nationality": "American",
    "screeningQuestionAnswer": [
      { "question": "How many years of experience do you have with Node.js?", "answer": "6 years" }
    ],
    "otherFiles": [
      { "name": "portfolio.pdf", "url": "https://cdn.taptalent.io/applications/101/portfolio.pdf?signature=..." }
    ],
    "consent": {
      "acceptedAt": 1234567890000,
      "policyVersion": "2025-08",
      "consentDocumentUrl": "https://cdn.taptalent.io/applications/101/dpa-acknowledgment.pdf?signature=...",
      "expiresAt": 1234571490000
    }
  }
}
```

| Field                                                                                                                   | Type            | Description                                                                                                                                            |
| ----------------------------------------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `appliedAt`                                                                                                             | number          | Unix timestamp (ms) of the submission.                                                                                                                 |
| `candidate`                                                                                                             | object          | `firstName`, `lastName`, `email`, `phone` (`phone` is `null` when the form had it `OFF`).                                                              |
| `resumeUrl`                                                                                                             | string or null  | Time-limited URL to the submitted resume; `null` when resume was `OFF` or not provided. Re-fetch this endpoint for a fresh URL.                        |
| `currentJobTitle`, `company`, `noticePeriod`, `isWillingToRelocate`, CTC fields, `gender`, `dateOfBirth`, `nationality` | varies, or null | Present when collected per the job's [`applicationForm`](/api-reference/jobs#applicationform-structure) configuration.                                 |
| `screeningQuestionAnswer`                                                                                               | array           | `{question, answer}` pairs; empty when the job has no screening questions.                                                                             |
| `otherFiles`                                                                                                            | array           | Additional files uploaded with the application (when the form's `otherFiles` field is enabled): `{name, url}` with time-limited URLs. Empty when none. |
| `consent`                                                                                                               | object or null  | `acceptedAt`, `policyVersion`, time-limited `consentDocumentUrl`, `expiresAt`. `null` for applications submitted before consent capture was enabled.   |

Education and work experience are not part of the application—they come from resume parsing and live on the candidate profile ([Candidates](/api-reference/candidates)).

### Error Responses

* **401** – Missing or invalid API key. See [API Keys](/authentication/api-keys).
* **404** – Job candidate not found. `code`: `NOT_FOUND`.
* **409** – The job candidate did not apply through the hosted application experience (e.g. sourced or bulk-uploaded). `code`: `NO_APPLICATION`.

***

## Get Consent Document

Retrieve a fresh time-limited URL for the DPA acknowledgment PDF. The same URL is delivered in the `candidate.applied` event; use this endpoint whenever that URL has expired.

### `GET /job-candidates/:jobCandidateId/application/consent-document`

### Path Parameters

| Parameter        | Type   | Required | Description       |
| ---------------- | ------ | -------- | ----------------- |
| `jobCandidateId` | number | Yes      | Job-candidate ID. |

### Example Request

```bash theme={null}
curl -X GET "https://partner-api.taptalent.io/v1/partner/job-candidates/101/application/consent-document" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": {
    "jobCandidateId": 101,
    "document": {
      "name": "Privacy Notice & DPA Acknowledgment",
      "category": "dpa_acknowledgment",
      "policyVersion": "2025-08",
      "acceptedAt": 1234567890000,
      "pdfUrl": "https://cdn.taptalent.io/applications/101/dpa-acknowledgment.pdf?signature=...",
      "expiresAt": 1234571490000
    }
  }
}
```

| Field       | Type   | Description                                                               |
| ----------- | ------ | ------------------------------------------------------------------------- |
| `pdfUrl`    | string | Time-limited URL to the PDF. Download promptly; re-fetch for a fresh URL. |
| `expiresAt` | number | Unix timestamp (ms) after which `pdfUrl` stops working.                   |

### Error Responses

* **401** – Missing or invalid API key. See [API Keys](/authentication/api-keys).
* **404** – Job candidate not found. `code`: `NOT_FOUND`.
* **409** – No consent record for this job candidate (did not apply through the hosted application experience, or the application predates consent capture). `code`: `NO_CONSENT_RECORD`.

***

## Webhook events

| Event                                                                                    | When it is sent                                                                                        |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [`candidate.applied`](/webhooks/events#application-events)                               | A candidate submitted an application on the hosted application experience (fires once per submission). |
| [`job.candidate.score.completed`](/webhooks/events#job-candidate-scoring-events)         | Resume scoring finished for the new job candidate.                                                     |
| [`candidate.stage_changed`](/webhooks/events) / [`candidate.rejected`](/webhooks/events) | Screening automation (when configured) moved or rejected the candidate after applying.                 |

## Integration sequence

1. Configure the job's application form and screening questions ([Jobs](/api-reference/jobs)), and publish the job as `ACTIVE`.
2. Generate an API key ([API Keys](/authentication/api-keys)) and configure your company webhook URL in the dashboard ([Webhooks Overview](/webhooks/overview)).
3. On `candidate.applied`, store the `jobCandidateId` and download the resume and consent PDF promptly (URLs expire), or re-fetch fresh URLs from [Get Application Details](#get-application-details) and [Get Consent Document](#get-consent-document).
4. To land the application on the right requisition in your system, resolve the event's `jobId` to your requisition reference via a job custom field—see [Correlating with your requisitions](/technical-integration/hris-delivery#correlating-with-your-requisitions).
5. Wait for `job.candidate.score.completed` for the resume score.
6. Track pipeline progress via `candidate.stage_changed`, resolving stage IDs to names and types with [Pipelines](/api-reference/pipelines).

## Notes

<Note>
  * There is no application-submission API—applications come only from the TapTalent-hosted application experience.
  * The resume is delivered as a time-limited URL, never inlined.
  * Education and work experience come from resume parsing, not the application form.
  * The DPA acknowledgment PDF is a system-generated acknowledgment record, not an e-signed document.
  * Store IDs (`jobCandidateId`), not URLs.
</Note>