Candidates - Documentation

Candidates API

The Candidates API allows you to bulk upload resumes and retrieve parsed candidate information. Resumes are processed asynchronously, and you can retrieve the parsed candidates using batch operations.

Bulk Upload Resumes

Upload multiple resumes for parsing and candidate creation.

`POST /v1/partner/candidates/bulk/resume`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Request Body

Field	Type	Required	Description
`resumeURLs`	array of strings	Yes	Array of publicly accessible URLs pointing to resume files (PDF, DOC, DOCX). Maximum 200 resumes per batch.

Request Body Example

{
  "resumeURLs": [
    "https://example.com/resumes/john-doe.pdf",
    "https://example.com/resumes/jane-smith.docx",
    "https://example.com/resumes/bob-johnson.pdf"
  ]
}

Example Request

curl -X POST "https://partner-api.taptalent.io/v1/partner/candidates/bulk/resume" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "resumeURLs": [
      "https://example.com/resumes/john-doe.pdf",
      "https://example.com/resumes/jane-smith.docx"
    ]
  }'

Example Response

{
  "success": true,
  "data": {
    "batchId": "batch-uuid-here",
    "fileCount": 2
  }
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`data.batchId`	string (UUID)	Unique identifier for this batch. Use this to retrieve candidates later.
`data.fileCount`	number	Number of resumes in the batch

Validation Rules

resumeURLs must be provided and cannot be empty
resumeURLs must be an array
Each URL must be a non-empty string
URLs must be publicly accessible
Maximum 200 resumes per batch

Webhook Events

When you upload resumes, webhook events are triggered:

resume.bulk_upload_parse.started: Sent when batch processing starts

{
  "event": "resume.bulk_upload_parse.started",
  "timestamp": "2024-01-20T14:45:00Z",
  "companyId": "company-uuid",
  "data": {
    "batchId": "batch-uuid",
    "fileCount": 2
  }
}

resume.bulk_upload_parse.failed: Sent if batch processing fails

{
  "event": "resume.bulk_upload_parse.failed",
  "timestamp": "2024-01-20T14:45:00Z",
  "companyId": "company-uuid",
  "data": {
    "error": "Error message"
  }
}

Error Responses

Missing resumeURLs:

{
  "error": {
    "code": "MISSING_RESUME_URLS",
    "type": "validation_error",
    "message": "resumeURLs is required in the request body"
  }
}

Invalid resumeURLs format:

{
  "error": {
    "code": "INVALID_RESUME_URLS",
    "type": "validation_error",
    "message": "resumeURLs must be an array of URLs",
    "details": {
      "invalidCount": 1
    }
  }
}

Empty resumeURLs array:

{
  "error": {
    "code": "MISSING_RESUME_URLS",
    "type": "validation_error",
    "message": "resumeURLs array cannot be empty"
  }
}

Company not found:

{
  "error": {
    "code": "COMPANY_NOT_FOUND",
    "type": "resource_error",
    "message": "Company not found for this API key"
  }
}

Subscription not active:

{
  "error": {
    "code": "SUBSCRIPTION_NOT_ACTIVE",
    "type": "subscription_error",
    "message": "Your subscription is not active. Please renew to continue."
  }
}

Get Batch Candidates

Retrieve parsed candidates from a batch with pagination.

`GET /v1/partner/candidates/batch/:batchId`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Path Parameters

Parameter	Type	Description
`batchId`	string (UUID)	The batch ID returned from the bulk upload endpoint

Query Parameters

Parameter	Type	Required	Description
`pageNumber`	integer	No	Page number (default: 1)
`perPage`	integer	No	Items per page. Must be one of: 10, 20, 40, 80, 100 (default: 10)

Example Request

curl -X GET "https://partner-api.taptalent.io/v1/partner/candidates/batch/batch-uuid-here?pageNumber=1&perPage=20" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json"

Example Response

{
  "success": true,
  "data": {
    "batchId": "batch-uuid-here",
    "batchStatus": "COMPLETED",
    "total": 45,
    "pageNumber": 1,
    "perPage": 20,
    "hasNextPage": true,
    "candidates": [
      {
        "id": "candidate-uuid-1",
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "+1234567890",
        "resumeUrl": "https://s3.amazonaws.com/...",
        "parsedData": {
          "skills": ["JavaScript", "React", "Node.js"],
          "experience": "5 years",
          "education": "Bachelor's in Computer Science"
        },
        "createdAt": "2024-01-20T14:45:00Z"
      },
      {
        "id": "candidate-uuid-2",
        "name": "Jane Smith",
        "email": "[email protected]",
        "phone": "+0987654321",
        "resumeUrl": "https://s3.amazonaws.com/...",
        "parsedData": {
          "skills": ["Python", "Django", "PostgreSQL"],
          "experience": "3 years",
          "education": "Master's in Software Engineering"
        },
        "createdAt": "2024-01-20T14:46:00Z"
      }
    ]
  }
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`data.batchId`	string (UUID)	The batch ID
`data.batchStatus`	string	Batch processing status (e.g., “PROCESSING”, “COMPLETED”, “FAILED”)
`data.total`	number	Total number of candidates in the batch
`data.pageNumber`	number	Current page number
`data.perPage`	number	Number of items per page
`data.hasNextPage`	boolean	Indicates if there are more pages
`data.candidates`	array	Array of candidate objects

Candidate Object Fields

Field	Type	Description
`id`	string (UUID)	Unique candidate identifier
`name`	string	Candidate’s full name
`email`	string	Candidate’s email address
`phone`	string	Candidate’s phone number
`resumeUrl`	string	URL to the stored resume file
`parsedData`	object	Parsed resume data (skills, experience, education, etc.)
`createdAt`	string (ISO 8601)	Timestamp when candidate was created

Error Responses

Invalid batchId:

{
  "error": {
    "code": "INVALID_BATCH_ID",
    "type": "validation_error",
    "message": "batchId is required"
  }
}

Batch not found:

{
  "error": {
    "code": "BATCH_NOT_FOUND",
    "type": "resource_error",
    "message": "Batch not found"
  }
}

Unauthorized access:

{
  "error": {
    "code": "UNAUTHORIZED_ACCESS",
    "type": "authorization_error",
    "message": "You do not have access to this batch"
  }
}

Invalid perPage value:

{
  "error": {
    "code": "INVALID_PER_PAGE",
    "type": "validation_error",
    "message": "perPage must be one of: 10, 20, 40, 80, 100"
  }
}

Use Cases

Bulk Candidate Ingestion

Upload multiple resumes at once to quickly build your candidate database:

Collect resume URLs from your ATS or other sources
Upload them in batches (up to 200 per batch)
Receive webhook notifications when processing starts/completes
Retrieve parsed candidates using the batch ID

Resume Parsing Pipeline

Integrate TapTalent’s resume parsing into your workflow:

Upload resumes as they come in
Receive real-time webhook notifications
Retrieve parsed candidate data programmatically
Sync with your internal systems

Best Practices

Batch Size

Use batches of 50-100 resumes for optimal processing time
Maximum 200 resumes per batch
Split larger sets into multiple batches

Error Handling

Handle webhook events for batch status updates
Implement retry logic for failed uploads
Monitor batch status and handle failures gracefully

Pagination

Use appropriate perPage values (10, 20, 40, 80, or 100)
Check hasNextPage to determine if more data is available
Implement pagination loops to retrieve all candidates

Webhook Integration

Set up webhook URL to receive batch status updates
Handle both success and failure webhook events
Use webhooks to trigger downstream processing

Next Steps

Set up Webhooks to receive batch status updates
Review Integration Notes for best practices
Explore other API endpoints

Getting Started

​Candidates API

​Bulk Upload Resumes

​POST /v1/partner/candidates/bulk/resume

​Authentication

​Request Body

​Request Body Example

​Example Request

​Example Response

​Response Fields

​Validation Rules

​Webhook Events

​Error Responses

​Get Batch Candidates

​GET /v1/partner/candidates/batch/:batchId

​Authentication

​Path Parameters

​Query Parameters

​Example Request

​Example Response

​Response Fields

​Candidate Object Fields

​Error Responses

​Use Cases

​Bulk Candidate Ingestion

​Resume Parsing Pipeline

​Best Practices

​Batch Size

​Error Handling

​Pagination

​Webhook Integration

​Next Steps

Candidates API

Bulk Upload Resumes

`POST /v1/partner/candidates/bulk/resume`

Authentication

Request Body

Request Body Example

Example Request

Example Response

Response Fields

Validation Rules

Webhook Events

Error Responses

Get Batch Candidates

`GET /v1/partner/candidates/batch/:batchId`

Authentication

Path Parameters

Query Parameters

Example Request

Example Response

Response Fields

Candidate Object Fields

Error Responses

Use Cases

Bulk Candidate Ingestion

Resume Parsing Pipeline

Best Practices

Batch Size

Error Handling

Pagination

Webhook Integration

Next Steps