Jobs - Documentation

Jobs API

The Jobs API allows you to create and retrieve job postings programmatically. Jobs represent open positions in your organization that can be managed through the TapTalent platform.

Create Job

Create a new job posting.

`POST /v1/partner/jobs`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Request Body

Field	Type	Required	Description
`title`	string	Yes	Job title (3-500 characters)
`description`	string	No	Job description (max 10,000 characters). If omitted, description will be auto-generated.
`city`	string	Yes	City name (max 200 characters)
`state`	string	Yes	State/Province name (max 200 characters)
`country`	string	Yes	Country name (max 200 characters)
`status`	string	No	Job status. Valid values: `DRAFT`, `ACTIVE`. Default: `DRAFT`
`workMode`	string	No	Work mode. Valid values: `ONSITE`, `REMOTE`, `HYBRID`. Default: `ONSITE`
`screeningQuestion`	array	No	Array of screening questions (max 5). Each question must have `type: "text"` and `question` (1-3000 characters)
`teamId`	string (UUID)	No	Team ID associated with the job
`contractType`	string	No	Contract type. Valid values: `Permanent`, `Freelance / Consultant`, `Fixed term contract`, `Internship`, `Student`
`degreeLevel`	string	No	Required degree level. Valid values: `Bachelor's`, `High School`, `M.B.A.`, `Master's`, `Other`, `Ph.D.`
`jobRole`	string	No	Job role category. See valid values below
`salaryRangeFrom`	number	Conditional*	Minimum salary (0-9999999999)
`salaryRangeTo`	number	Conditional*	Maximum salary (0-9999999999)
`salaryCurrency`	string	Conditional*	Salary currency code. Valid values: `USD`, `PHP`, `SGD`, `IDR`, `EUR`, `INR`, `GBP`, `AED`, `MYR`, `AUD`, `CAD`, `JPY`, `CNY`, `CHF`, `ZAR`, `KRW`, `THB`, `VND`, `BRL`, `MXN`, `RUB`, `TRY`, `SEK`, `NOK`, `DKK`, `PLN`, `HKD`, `MAD`
`potentialAmount`	number	No	Potential amount (min 0)
`potentialAmountCurrency`	string	Conditional**	Required if `potentialAmount` is provided. 3-character uppercase currency code
`potentialHiresCount`	number	No	Number of potential hires (min 1)
`yearOfExperience`	number	No	Years of experience required (0-50)

* All three salary fields (salaryRangeFrom, salaryRangeTo, salaryCurrency) must be provided together or omitted together. salaryRangeTo must be greater than salaryRangeFrom. ** Required if potentialAmount is provided.

Valid Job Role Values

Accounting, Administrative, Customer Service, Design, Education, Engineering, Finance, Healthcare, Hospitality & Tourism, Human Resources (HR), Information Technology (IT), Legal, Marketing, Media & Public Relations (PR), Pharmaceuticals, Production, Property Management, Public Service & Security, Real Estate, Retail, Sales, Supply Chain & Logistics

Example Request

curl -X POST "https://partner-api.taptalent.io/v1/partner/jobs" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Software Engineer",
    "description": "We are looking for an experienced software engineer to join our team...",
    "city": "San Francisco",
    "state": "California",
    "country": "United States",
    "workMode": "REMOTE",
    "status": "DRAFT",
    "contractType": "Permanent",
    "degreeLevel": "Bachelor's",
    "jobRole": "Engineering",
    "salaryRangeFrom": 120000,
    "salaryRangeTo": 180000,
    "salaryCurrency": "USD",
    "yearOfExperience": 5,
    "screeningQuestion": [
      {
        "type": "text",
        "question": "What is your experience with Node.js?"
      }
    ]
  }'

Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Senior Software Engineer",
  "description": "We are looking for an experienced software engineer to join our team...",
  "city": "San Francisco",
  "state": "California",
  "country": "United States",
  "pipelineId": "pipeline-uuid",
  "status": "DRAFT",
  "workMode": "REMOTE",
  "screeningQuestion": [
    {
      "type": "text",
      "question": "What is your experience with Node.js?"
    }
  ],
  "skills": [],
  "applicationForm": {},
  "clientId": "client-uuid",
  "companyId": "company-uuid",
  "teamId": null,
  "careerLevel": null,
  "contractType": "Permanent",
  "degreeLevel": "Bachelor's",
  "jobRole": "Engineering",
  "salaryRangeFrom": 120000,
  "salaryRangeTo": 180000,
  "salaryCurrency": "USD",
  "criterionDetails": {},
  "publishType": null,
  "companyClientId": null,
  "potentialAmount": null,
  "potentialAmountCurrency": null,
  "potentialHiresCount": null,
  "closingStatus": null,
  "closingReason": null,
  "referralTemplateId": null,
  "pipelineStage": null,
  "jobType": null
}

Validation Rules

title: Required, 3-500 characters
description: Optional, max 10,000 characters
city, state, country: Required, max 200 characters each
screeningQuestion: Max 5 questions, each question 1-3000 characters
salaryRangeFrom, salaryRangeTo, salaryCurrency: Must all be provided together or all omitted. salaryRangeTo must be greater than salaryRangeFrom
potentialAmount and potentialAmountCurrency: If potentialAmount is provided, potentialAmountCurrency is required

Common Errors

Validation Error:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "One or more fields are invalid.",
    "details": {
      "title": "\"title\" length must be at least 3 characters long",
      "salaryRangeTo": "rangeTo must be greater than rangeFrom"
    }
  }
}

Missing Company:

{
  "error": {
    "code": "INTERNAL_ERROR",
    "type": "internal_error",
    "message": "Please create a company!"
  }
}

Get Job

Retrieve detailed information about a specific job.

`GET /v1/partner/jobs/:jobId`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Path Parameters

Parameter	Type	Description
`jobId`	string (UUID)	The unique identifier of the job

Example Request

curl -X GET "https://partner-api.taptalent.io/v1/partner/jobs/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json"

Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Senior Software Engineer",
  "description": "We are looking for an experienced software engineer...",
  "city": "San Francisco",
  "state": "California",
  "country": "United States",
  "pipelineId": "pipeline-uuid",
  "status": "DRAFT",
  "workMode": "REMOTE",
  "screeningQuestion": [
    {
      "type": "text",
      "question": "What is your experience with Node.js?"
    }
  ],
  "skills": [],
  "applicationForm": {},
  "clientId": "client-uuid",
  "companyId": "company-uuid",
  "teamId": null,
  "careerLevel": null,
  "contractType": "Permanent",
  "degreeLevel": "Bachelor's",
  "jobRole": "Engineering",
  "salaryRangeFrom": 120000,
  "salaryRangeTo": 180000,
  "salaryCurrency": "USD",
  "criterionDetails": {},
  "publishType": null,
  "companyClientId": null,
  "potentialAmount": null,
  "potentialAmountCurrency": null,
  "potentialHiresCount": null,
  "closingStatus": null,
  "closingReason": null,
  "referralTemplateId": null,
  "pipelineStage": null,
  "jobType": null
}

Error Responses

Job Not Found:

{
  "error": {
    "code": "INTERNAL_ERROR",
    "type": "internal_error",
    "message": "Something went wrong."
  }
}

Invalid API Key:

{
  "message": "Invalid API key"
}

Inactive Subscription:

{
  "code": "ACCOUNT_INACTIVE",
  "message": "Your subscription is inactive. Please renew your plan to continue using this feature."
}

Use Cases

Syncing Open Roles

Create jobs programmatically from your internal systems to keep TapTalent in sync with your ATS or HRIS.

Updating Hiring Requirements

Retrieve job details to check current requirements and update them as needed through your integration.

Job Status Management

Create jobs in DRAFT status and activate them when ready, or manage job lifecycle programmatically.

Next Steps

Set up Webhooks to receive notifications when jobs are updated
Review Integration Notes for best practices
Explore other API endpoints

Getting Started

​Jobs API

​Create Job

​POST /v1/partner/jobs

​Authentication

​Request Body

​Valid Job Role Values

​Example Request

​Example Response

​Validation Rules

​Common Errors

​Get Job

​GET /v1/partner/jobs/:jobId

​Authentication

​Path Parameters

​Example Request

​Example Response

​Error Responses

​Use Cases

​Syncing Open Roles

​Updating Hiring Requirements

​Job Status Management

​Next Steps

Jobs API

Create Job

`POST /v1/partner/jobs`

Authentication

Request Body

Valid Job Role Values

Example Request

Example Response

Validation Rules

Common Errors

Get Job

`GET /v1/partner/jobs/:jobId`

Authentication

Path Parameters

Example Request

Example Response

Error Responses

Use Cases

Syncing Open Roles

Updating Hiring Requirements

Job Status Management

Next Steps