Candidate Applications

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 and screeningQuestion. 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 webhook event. Authentication: Authorization: Bearer YOUR_API_KEY—see API Keys. Related: webhook setup is described in Webhooks Overview; the event payload is in Application events.

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.

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. `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.
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).
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

The candidate opens the job’s hosted application page (or the chat-assisted variant).
The candidate accepts the privacy notice / DPA.
The candidate submits the form: the fields required by the job’s applicationForm, answers to any screening questions, and their resume.
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.
The candidate.applied event is sent to your webhook endpoint.
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).

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

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

{
  "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` 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).

Error Responses

401 – Missing or invalid API key. See 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.

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.

Path Parameters

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

Example Request

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

{
  "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.
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`	A candidate submitted an application on the hosted application experience (fires once per submission).
`job.candidate.score.completed`	Resume scoring finished for the new job candidate.
`candidate.stage_changed` / `candidate.rejected`	Screening automation (when configured) moved or rejected the candidate after applying.

Integration sequence

Configure the job’s application form and screening questions (Jobs), and publish the job as ACTIVE.
Generate an API key (API Keys) and configure your company webhook URL in the dashboard (Webhooks Overview).
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 and Get Consent Document.
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.
Wait for job.candidate.score.completed for the resume score.
Track pipeline progress via candidate.stage_changed, resolving stage IDs to names and types with Pipelines.

Notes

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.

Get Started

Authentication

API Reference

Webhooks

Integration Notes

Technical Integration

Concepts

How an application flows through TapTalent

Get Application Details

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

Path Parameters

Example Request

Example Response

Error Responses

Path Parameters

Example Request

Example Response

Error Responses

Webhook events

Integration sequence

Notes

​Concepts

​How an application flows through TapTalent

​Privacy consent at application

​Get Application Details

​GET /job-candidates/:jobCandidateId/application

​Path Parameters

​Example Request

​Example Response

​Error Responses

​Get Consent Document

​GET /job-candidates/:jobCandidateId/application/consent-document

​Path Parameters

​Example Request

​Example Response

​Error Responses

​Webhook events

​Integration sequence

​Notes

Concepts

How an application flows through TapTalent

Privacy consent at application

Get Application Details

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

Path Parameters

Example Request

Example Response

Error Responses

Get Consent Document

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

Path Parameters

Example Request

Example Response

Error Responses

Webhook events

Integration sequence

Notes