Jobs - Taptalent Partner 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.

List Jobs

Retrieve a paginated list of all jobs in your company.

`GET /jobs`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

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/jobs?pageNumber=1&perPage=20" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json"

Example Response

{
  "jobs": [
    {
      "id": 12345,
      "title": "Senior Software Engineer",
      "description": "We are looking for an experienced software engineer...",
      "city": "San Francisco",
      "state": "California",
      "country": "United States",
      "pipelineId": "pipelineId_1",
      "status": "DRAFT",
      "workMode": "REMOTE",
      "pipelineStage": [
        {
          "name": "Applied",
          "type": "APPLIED",
          "totalCandidate": 5
        },
        {
          "name": "Interview",
          "type": "INTERVIEW",
          "totalCandidate": 2
        }
      ],
      "createdAt": 1234567890,
      "runningRevenue": 0,
      "rejectedCandidateCount": 1,
      "salaryRangeFrom": 120000,
      "salaryRangeTo": 180000,
      "salaryCurrency": "USD"
    }
  ],
  "totalJobs": 45
}

Response Fields

Field	Type	Description
`jobs`	array	Array of job objects
`totalJobs`	number	Total number of jobs in your company

Each job object includes all standard job fields plus:

pipelineStage: Array of pipeline stages with candidate counts
createdAt: Timestamp when job was created
runningRevenue: Total revenue from hired candidates
rejectedCandidateCount: Number of rejected candidates

Error Responses

Invalid perPage value:

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

Create Job

Create a new job posting.

`POST /jobs`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Request Body Parameters

Required Fields

`title` (string, required)

What it does: The job title that will be displayed to candidates and in job listings. Data format:

Must be between 3 and 500 characters
Should be clear and descriptive (e.g., “Senior Software Engineer”, “Marketing Manager”, “Sales Representative”)
Avoid abbreviations unless they’re industry-standard

Examples:

✅ Good: "Senior Full Stack Developer"
✅ Good: "Product Marketing Manager"
❌ Bad: "Dev" (too short)
❌ Bad: "SWE" (unclear abbreviation)

`city` (string, required)

What it does: The city where the job is located. Used for location-based job searches and candidate matching. Data format:

Maximum 200 characters
Use the full city name (e.g., “San Francisco”, “New York”, “London”)
Don’t include state/province or country here (use state and country fields)

Examples:

✅ Good: "San Francisco"
✅ Good: "New York"
❌ Bad: "San Francisco, CA" (state should be in state field)

`state` (string, required)

What it does: The state or province where the job is located. Data format:

Maximum 200 characters
Use full state/province name (e.g., “California”, “New York”, “Ontario”)
For countries without states/provinces, you can use the country name or leave as empty string (though country is still required)

Examples:

✅ Good: "California"
✅ Good: "New York"
✅ Good: "Ontario" (for Canada)

`country` (string, required)

What it does: The country where the job is located. Used for geographic filtering and compliance. Data format:

Maximum 200 characters
Use full country name (e.g., “United States”, “United Kingdom”, “Canada”)

Examples:

✅ Good: "United States"
✅ Good: "United Kingdom"
✅ Good: "Canada"

Optional Fields

`description` (string, optional)

What it does: The detailed job description that explains the role, responsibilities, company culture, and what you’re looking for. This is what candidates will read to understand the job. Data format:

Maximum 10,000 characters
Can include formatting, bullet points, and detailed information
If omitted, TapTalent will auto-generate a description based on other job fields

When to provide:

✅ Provide when you have a specific, well-written job description
✅ Use when you want to highlight company culture, benefits, or unique aspects
⚠️ Omit if you want TapTalent to generate a description automatically

Example:

"description": "We are looking for an experienced Senior Software Engineer to join our growing team. You will be responsible for designing and developing scalable web applications, collaborating with cross-functional teams, and mentoring junior developers. Our company values innovation, work-life balance, and continuous learning. We offer competitive salary, comprehensive health benefits, and flexible remote work options."

`status` (string, optional)

What it does: Controls whether the job is immediately visible to candidates or saved as a draft. Valid values (for creating jobs):

"DRAFT" (default): Job is saved but not visible to candidates. Use this when you’re still working on the job posting.
"ACTIVE": Job is live and visible to candidates. Use this when the job is ready to accept applications.

Note: When creating a job, only "DRAFT" and "ACTIVE" are allowed. Additional status values ("INACTIVE", "DELETED") are available when updating jobs. See Update Job for status transition rules. When to use:

Use "DRAFT" when creating jobs programmatically and want to review them before going live
Use "ACTIVE" when the job is ready to be published immediately

Example: "DRAFT"

`workMode` (string, optional)

What it does: Specifies the work arrangement for the position. This is important for candidates who have location preferences. Valid values:

"ONSITE" (default): Work must be done at a physical office location
"REMOTE": Work can be done entirely from home or any location
"HYBRID": Combination of onsite and remote work

When to use:

Use "ONSITE" for jobs that require physical presence (e.g., manufacturing, retail)
Use "REMOTE" for jobs that can be done from anywhere (e.g., software development, customer support)
Use "HYBRID" for jobs with flexible arrangements (e.g., 2-3 days in office, rest remote)

Example: "REMOTE"

`screeningQuestion` (array, optional)

What it does: Pre-screening questions that candidates must answer when applying. These help filter candidates early in the process. Data format:

Maximum 15 questions
Each question is an object with:
- type: Must be "text" (only text questions are supported)
- question: The question text (1-3000 characters)

When to use:

Use for essential qualifications that can be quickly verified (e.g., “Do you have 5+ years of experience with React?”)
Use for deal-breaker questions (e.g., “Are you authorized to work in the United States?”)
Keep questions short and specific

Example:

"screeningQuestion": [
  {
    "type": "text",
    "question": "How many years of experience do you have with Node.js?"
  },
  {
    "type": "text",
    "question": "Are you authorized to work in the United States?"
  }
]

`teamId` (string UUID, optional)

What it does: Associates the job with a specific team within your organization. Useful for multi-team companies. Data format:

Must be a valid UUID
Must be an existing team ID in your TapTalent account

When to use:

Use when your organization has multiple teams and you want to assign the job to a specific team
Leave empty if you don’t use teams or want to assign later

Example: "123e4567-e89b-12d3-a456-426614174000"

`contractType` (string, optional)

What it does: Specifies the employment contract type. Important for candidates to understand the nature of the position. Valid values:

"Permanent": Full-time permanent employment
"Freelance / Consultant": Contract-based, project-based work
"Fixed term contract": Temporary position with a defined end date
"Internship": Internship position
"Student": Student position or part-time student role

When to use:

Use "Permanent" for standard full-time positions
Use "Freelance / Consultant" for contract work
Use "Internship" or "Student" for entry-level learning positions

Example: "Permanent"

`degreeLevel` (string, optional)

What it does: The minimum education level required for the position. Used for candidate filtering and matching. Valid values:

"High School": High school diploma or equivalent
"Bachelor's": Bachelor’s degree required
"Master's": Master’s degree required
"M.B.A.": MBA degree required
"Ph.D.": Doctoral degree required
"Other": Other education requirements

When to use:

Specify when education is a hard requirement
Leave empty if education level is flexible or not important
Consider using criterionDetails for more nuanced education requirements

Example: "Bachelor's"

`jobRole` (string, optional)

What it does: Categorizes the job into a specific role category. Used for job organization and candidate matching. Valid 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 When to use:

Use to categorize jobs for better organization
Helps with candidate matching and job recommendations
Choose the category that best fits the role

Example: "Engineering"

`salaryRangeFrom` (number, conditional*)

What it does: The minimum salary for the position. Used to attract candidates and set expectations. Data format:

Integer between 0 and 9,999,999,999
Represents the minimum annual salary
Must be provided together with salaryRangeTo and salaryCurrency

When to use:

Provide when you want to display salary range to attract candidates
Use realistic market rates
Must be less than salaryRangeTo

Example: 120000 (for $120,000)

`salaryRangeTo` (number, conditional*)

What it does: The maximum salary for the position. Data format:

Integer between 0 and 9,999,999,999
Represents the maximum annual salary
Must be greater than salaryRangeFrom
Must be provided together with salaryRangeFrom and salaryCurrency

Example: 180000 (for $180,000)

`salaryCurrency` (string, conditional*)

What it does: The currency for the salary range. 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 Important: All three salary fields (salaryRangeFrom, salaryRangeTo, salaryCurrency) must be provided together or omitted together. Example: "USD"

`potentialAmount` (number, optional)

What it does: The potential revenue or value associated with filling this position. Used for business planning and reporting. Data format:

Number greater than or equal to 0
Represents the monetary value (e.g., revenue, commission potential)
If provided, potentialAmountCurrency is required

When to use:

Use for sales positions with commission potential
Use for roles that directly generate revenue
Leave empty for standard salaried positions

Example: 50000

`potentialAmountCurrency` (string, conditional**)

What it does: The currency for the potential amount. Data format:

3-character uppercase currency code (e.g., “USD”, “EUR”)
Required if potentialAmount is provided

Example: "USD"

`potentialHiresCount` (number, optional)

What it does: The number of people you plan to hire for this position. Used for planning and resource allocation. Data format:

Integer, minimum 1
Represents how many candidates you want to hire for this role

When to use:

Use when hiring multiple people for the same role
Leave as 1 for single positions

Example: 3 (hiring 3 people for this role)

`yearOfExperience` (number, optional)

What it does: The minimum years of professional experience required for the position. Data format:

Number between 0 and 50
Represents years of experience

When to use:

Use for experience requirements (e.g., “5 years of experience”)
Can be combined with criterionDetails for more specific experience requirements
Use 0 for entry-level positions

Example: 5 (5 years of experience required)

`applicationForm` (object, optional)

What it does: Configures which fields are required, optional, or hidden in the candidate application form. This controls what information candidates must provide when applying to the job. Data format:

Object with fields that can be set to "OPTIONAL", "MANDATORY", or "OFF"
See applicationForm Structure below for complete field list

When to use:

Use to customize the candidate application experience
Control which information is required vs optional
Hide fields that aren’t relevant to your hiring process

Example: See applicationForm Structure section below. Note: If not provided, default values will be set automatically by the system.

`criterionDetails` (array, optional)

What it does: Detailed job requirements and qualifications. This is used by TapTalent’s AI to match and score candidates. See the Job Criteria section below for comprehensive details. Data format:

Array of criterion objects (maximum 7)
Each criterion has:
- priority: "Must Have", "Nice to Have", or "Bonus" (default: "Nice to Have")
- criterion_text: Requirement description (1-3000 characters)

When to use:

✅ Always recommended for better candidate matching
✅ Essential for AI-powered candidate evaluation
✅ Helps filter and rank candidates automatically

Example: See Job Criteria section for detailed examples.

* Salary Fields Rule: All three salary fields (salaryRangeFrom, salaryRangeTo, salaryCurrency) must be provided together or omitted together. salaryRangeTo must be greater than salaryRangeFrom. ** Potential Amount Rule: potentialAmountCurrency is required if potentialAmount is provided.

applicationForm Structure

The applicationForm field allows you to configure the candidate application form by specifying which fields should be required, optional, or hidden.

Field Descriptions

Field	Valid Values	Description
`phone`	`OPTIONAL`, `MANDATORY`, `OFF`	Phone number field requirement
`currentJobTitle`	`OPTIONAL`, `MANDATORY`, `OFF`	Current job title field requirement
`resume`	`OPTIONAL`, `MANDATORY`, `OFF`	Resume/CV upload requirement
`otherFiles`	`OPTIONAL`, `MANDATORY`, `OFF`	Other documents upload requirement
`company`	`OPTIONAL`, `MANDATORY`, `OFF`	Current company field requirement
`isWillingToRelocate`	`MANDATORY`, `OFF`	Willingness to relocate question (no OPTIONAL)
`noticePeriod`	`OPTIONAL`, `MANDATORY`, `OFF`	Notice period field requirement
`expectedCTC`	`OPTIONAL`, `MANDATORY`, `OFF`	Expected compensation requirement
`currentCTC`	`OPTIONAL`, `MANDATORY`, `OFF`	Current compensation requirement
`currencyExpectedCTC`	string	Currency code for expected CTC (required if `expectedCTC` is not `OFF`)
`currencyCurrentCTC`	string	Currency code for current CTC (required if `currentCTC` is not `OFF`)
`expectedCTCPeriod`	`ANNUALLY`, `MONTHLY`	Period for expected CTC
`currentCTCPeriod`	`ANNUALLY`, `MONTHLY`	Period for current CTC
`gender`	`OPTIONAL`, `MANDATORY`, `OFF`	Gender field requirement
`dateOfBirth`	`OPTIONAL`, `MANDATORY`, `OFF`	Date of birth field requirement
`nationality`	`OPTIONAL`, `MANDATORY`, `OFF`	Nationality field requirement

Example: Complete applicationForm

{
  "applicationForm": {
    "phone": "MANDATORY",
    "currentJobTitle": "OPTIONAL",
    "resume": "MANDATORY",
    "otherFiles": "OFF",
    "company": "OPTIONAL",
    "isWillingToRelocate": "MANDATORY",
    "noticePeriod": "OPTIONAL",
    "expectedCTC": "MANDATORY",
    "currentCTC": "OPTIONAL",
    "currencyExpectedCTC": "USD",
    "currencyCurrentCTC": "USD",
    "expectedCTCPeriod": "ANNUALLY",
    "currentCTCPeriod": "MONTHLY",
    "gender": "OFF",
    "dateOfBirth": "OPTIONAL",
    "nationality": "MANDATORY"
  }
}

Example: Minimal applicationForm (Only Required Fields)

{
  "applicationForm": {
    "phone": "MANDATORY",
    "resume": "MANDATORY"
  }
}

Important Notes

All fields are optional in the applicationForm object - you can specify only the fields you want to configure
Currency fields: If expectedCTC or currentCTC is set to MANDATORY or OPTIONAL (not OFF), the corresponding currency field is required
Default values: If applicationForm is not provided, the system will set default values automatically
Partial updates: When updating a job, you can provide only the applicationForm fields you want to change - they will be merged with existing values

Job Criteria (criterionDetails)

The criterionDetails field is one of the most important fields for recruiters when creating a job posting. It defines the specific requirements, qualifications, and skills you’re looking for in candidates. These criteria are used by TapTalent’s AI to automatically evaluate and score candidates against your job requirements.

Why Job Criteria Matter

From a recruiter’s perspective, job criteria help you:

Define Clear Requirements: Specify exactly what skills, experience, and qualifications candidates need
Improve Candidate Matching: The AI uses these criteria to match candidates to your job and provide match scores
Save Time: Automatically filter and rank candidates based on how well they meet your requirements
Set Expectations: Clearly communicate what you’re looking for, helping candidates self-assess their fit

Understanding Priority Levels

Each criterion has a priority level that indicates how important it is:

Priority	Description	When to Use
Must Have	Essential requirements that candidates absolutely must meet	Use for non-negotiable skills, certifications, or qualifications. Candidates without these should typically be filtered out.
Nice to Have	Preferred qualifications that would make a candidate stronger	Use for skills or experience that would be beneficial but aren’t deal-breakers. This is the default priority.
Bonus	Additional skills that would be great but aren’t necessary	Use for extra qualifications that would make a candidate exceptional but aren’t required.

Best Practices for Writing Criteria

Be Specific: Instead of “Good communication skills”, write “Excellent written and verbal communication skills with experience presenting to stakeholders”
Focus on Measurable Skills: Include specific technologies, tools, or certifications (e.g., “5+ years of experience with React and TypeScript”)
Balance Your Criteria:
- Use 2-4 “Must Have” criteria for essential requirements
- Use 3-5 “Nice to Have” criteria for preferred qualifications
- Use 1-2 “Bonus” criteria for exceptional skills
Keep It Relevant: Only include criteria that directly relate to job performance
Think Like a Recruiter: Write criteria that help you quickly identify qualified candidates

CriterionDetails Structure

Each criterion in the array must have:

Field	Type	Required	Description
`priority`	string	No	Priority level. Valid values: `"Must Have"`, `"Nice to Have"`, `"Bonus"`. Default: `"Nice to Have"`
`criterion_text`	string	Yes	The requirement description (1-3000 characters). This is where you describe the skill, qualification, or requirement.

Example: Software Engineer Job

{
  "criterionDetails": [
    {
      "priority": "Must Have",
      "criterion_text": "5+ years of professional software development experience with JavaScript and Node.js"
    },
    {
      "priority": "Must Have",
      "criterion_text": "Strong experience with RESTful API design and development"
    },
    {
      "priority": "Nice to Have",
      "criterion_text": "Experience with cloud platforms (AWS, Azure, or GCP)"
    },
    {
      "priority": "Nice to Have",
      "criterion_text": "Familiarity with microservices architecture and containerization (Docker, Kubernetes)"
    },
    {
      "priority": "Nice to Have",
      "criterion_text": "Experience with database design and optimization (PostgreSQL, MongoDB)"
    },
    {
      "priority": "Bonus",
      "criterion_text": "Contributions to open-source projects or active GitHub profile"
    }
  ]
}

Example: Marketing Manager Job

{
  "criterionDetails": [
    {
      "priority": "Must Have",
      "criterion_text": "Bachelor's degree in Marketing, Business, or related field"
    },
    {
      "priority": "Must Have",
      "criterion_text": "5+ years of experience in digital marketing with proven track record of successful campaigns"
    },
    {
      "priority": "Must Have",
      "criterion_text": "Proficiency with marketing analytics tools (Google Analytics, HubSpot, or similar)"
    },
    {
      "priority": "Nice to Have",
      "criterion_text": "Experience with SEO/SEM and content marketing strategies"
    },
    {
      "priority": "Nice to Have",
      "criterion_text": "Certification in Google Ads, Facebook Blueprint, or similar platforms"
    },
    {
      "priority": "Bonus",
      "criterion_text": "Experience managing marketing budgets over $500K annually"
    }
  ]
}

How Criteria Affect Candidate Matching

When you upload resumes or add candidates to a job:

AI Evaluation: TapTalent’s AI analyzes each candidate’s resume against your criteria
Match Scoring: Candidates receive a profile match score based on how well they meet your criteria
Priority Weighting: “Must Have” criteria carry more weight in the scoring than “Nice to Have” or “Bonus” criteria
Detailed Breakdown: You’ll see which criteria each candidate meets and how well they match

Validation Rules

Maximum 7 criteria per job
Each criterion_text must be between 1 and 3000 characters
priority must be one of: "Must Have", "Nice to Have", or "Bonus"
If priority is omitted, it defaults to "Nice to Have"

Tips for Developers

When building job creation forms or integrations:

Make Priority Selection Easy: Provide clear UI options for priority selection with helpful descriptions
Character Limits: Show character count for criterion_text (max 3000)
Validation: Enforce the 7-criteria maximum and validate text length
Default Values: Pre-fill priority as "Nice to Have" for better UX
Help Text: Provide examples or tooltips explaining each priority level

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

Parameter Quick Reference

Parameter	Type	Required	Max Length/Value	Default	Purpose
`title`	string	✅ Yes	3-500 chars	-	Job title displayed to candidates
`city`	string	✅ Yes	200 chars	-	Job location city
`state`	string	✅ Yes	200 chars	-	Job location state/province
`country`	string	✅ Yes	200 chars	-	Job location country
`description`	string	No	10,000 chars	Auto-generated	Detailed job description
`status`	string	No	-	`"DRAFT"`	Job visibility (`DRAFT` or `ACTIVE`)
`workMode`	string	No	-	`"ONSITE"`	Work arrangement (`ONSITE`, `REMOTE`, `HYBRID`)
`screeningQuestion`	array	No	15 items max	`[]`	Pre-screening questions
`teamId`	UUID	No	-	-	Team assignment
`contractType`	string	No	-	-	Employment type
`degreeLevel`	string	No	-	-	Minimum education required
`jobRole`	string	No	-	-	Job category
`salaryRangeFrom`	number	Conditional*	0-9,999,999,999	-	Minimum salary
`salaryRangeTo`	number	Conditional*	0-9,999,999,999	-	Maximum salary
`salaryCurrency`	string	Conditional*	-	-	Salary currency code
`potentialAmount`	number	No	≥ 0	-	Revenue potential
`potentialAmountCurrency`	string	Conditional**	3 chars	-	Potential amount currency
`potentialHiresCount`	number	No	≥ 1	-	Number of hires needed
`yearOfExperience`	number	No	0-50	-	Years of experience required
`applicationForm`	object	No	-	Auto-set	Candidate form requirements
`criterionDetails`	array	No	7 items max	-	Job requirements/criteria

* All three salary fields must be provided together
** Required if potentialAmount is provided

Common Use Case Examples

Example 1: Remote Software Engineer Position

{
  "title": "Senior Full Stack Developer",
  "description": "Join our innovative team building next-generation web applications...",
  "city": "San Francisco",
  "state": "California",
  "country": "United States",
  "workMode": "REMOTE",
  "status": "ACTIVE",
  "contractType": "Permanent",
  "degreeLevel": "Bachelor's",
  "jobRole": "Engineering",
  "salaryRangeFrom": 130000,
  "salaryRangeTo": 180000,
  "salaryCurrency": "USD",
  "yearOfExperience": 5,
  "criterionDetails": [
    {
      "priority": "Must Have",
      "criterion_text": "5+ years of experience with React, Node.js, and TypeScript"
    },
    {
      "priority": "Must Have",
      "criterion_text": "Strong experience with RESTful APIs and microservices"
    },
    {
      "priority": "Nice to Have",
      "criterion_text": "Experience with AWS or cloud platforms"
    }
  ],
  "screeningQuestion": [
    {
      "type": "text",
      "question": "Are you authorized to work in the United States?"
    }
  ]
}

Example 2: Onsite Sales Position with Commission

{
  "title": "Sales Representative",
  "description": "We're looking for a motivated sales professional...",
  "city": "New York",
  "state": "New York",
  "country": "United States",
  "workMode": "ONSITE",
  "status": "DRAFT",
  "contractType": "Permanent",
  "jobRole": "Sales",
  "salaryRangeFrom": 50000,
  "salaryRangeTo": 70000,
  "salaryCurrency": "USD",
  "potentialAmount": 100000,
  "potentialAmountCurrency": "USD",
  "potentialHiresCount": 2,
  "yearOfExperience": 2,
  "criterionDetails": [
    {
      "priority": "Must Have",
      "criterion_text": "2+ years of B2B sales experience"
    },
    {
      "priority": "Nice to Have",
      "criterion_text": "Experience with CRM software (Salesforce, HubSpot)"
    }
  ]
}

Example 3: Entry-Level Internship

{
  "title": "Software Engineering Intern",
  "city": "Seattle",
  "state": "Washington",
  "country": "United States",
  "workMode": "HYBRID",
  "status": "ACTIVE",
  "contractType": "Internship",
  "degreeLevel": "Bachelor's",
  "jobRole": "Engineering",
  "yearOfExperience": 0,
  "criterionDetails": [
    {
      "priority": "Must Have",
      "criterion_text": "Currently pursuing a Bachelor's degree in Computer Science or related field"
    },
    {
      "priority": "Nice to Have",
      "criterion_text": "Basic knowledge of programming languages (Python, JavaScript, or Java)"
    }
  ]
}

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?"
      }
    ],
    "criterionDetails": [
      {
        "priority": "Must Have",
        "criterion_text": "5+ years of professional software development experience with JavaScript and Node.js"
      },
      {
        "priority": "Must Have",
        "criterion_text": "Strong experience with RESTful API design and development"
      },
      {
        "priority": "Nice to Have",
        "criterion_text": "Experience with cloud platforms (AWS, Azure, or GCP)"
      },
      {
        "priority": "Nice to Have",
        "criterion_text": "Familiarity with microservices architecture and containerization"
      }
    ]
  }'

Example Response

{
  "id": 12345,
  "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": "pipelineId_1",
  "status": "DRAFT",
  "workMode": "REMOTE",
  "screeningQuestion": [
    {
      "type": "text",
      "question": "What is your experience with Node.js?"
    }
  ],
  "skills": [],
  "applicationForm": {
    "phone": "OPTIONAL",
    "currentJobTitle": "OPTIONAL",
    "resume": "MANDATORY",
    "otherFiles": "OFF",
    "company": "OFF",
    "isWillingToRelocate": "MANDATORY",
    "noticePeriod": "OPTIONAL",
    "expectedCTC": "OFF",
    "currentCTC": "OFF",
    "gender": "OFF",
    "dateOfBirth": "OFF",
    "nationality": "OFF"
  },
      "clientId": "clientId_1",
      "companyId": "companyId_1",
  "teamId": null,
  "careerLevel": null,
  "contractType": "Permanent",
  "degreeLevel": "Bachelor's",
  "jobRole": "Engineering",
  "salaryRangeFrom": 120000,
  "salaryRangeTo": 180000,
  "salaryCurrency": "USD",
  "criterionDetails": [
    {
      "priority": "Must Have",
      "criterion_text": "5+ years of professional software development experience with JavaScript and Node.js"
    },
    {
      "priority": "Must Have",
      "criterion_text": "Strong experience with RESTful API design and development"
    },
    {
      "priority": "Nice to Have",
      "criterion_text": "Experience with cloud platforms (AWS, Azure, or GCP)"
    }
  ],
  "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 15 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 /jobs/:jobId`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Path Parameters

Parameter	Type	Description
`jobId`	integer	The unique identifier of the job

Example Request

curl -X GET "https://partner-api.taptalent.io/v1/partner/jobs/12345" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json"

Example Response

{
  "id": 12345,
  "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": "pipelineId_1",
  "status": "DRAFT",
  "workMode": "REMOTE",
  "screeningQuestion": [
    {
      "type": "text",
      "question": "What is your experience with Node.js?"
    }
  ],
  "skills": [],
  "applicationForm": {
    "phone": "OPTIONAL",
    "currentJobTitle": "OPTIONAL",
    "resume": "MANDATORY",
    "otherFiles": "OFF",
    "company": "OFF",
    "isWillingToRelocate": "MANDATORY",
    "noticePeriod": "OPTIONAL",
    "expectedCTC": "OFF",
    "currentCTC": "OFF",
    "gender": "OFF",
    "dateOfBirth": "OFF",
    "nationality": "OFF"
  },
      "clientId": "clientId_1",
      "companyId": "companyId_1",
  "teamId": null,
  "careerLevel": null,
  "contractType": "Permanent",
  "degreeLevel": "Bachelor's",
  "jobRole": "Engineering",
  "salaryRangeFrom": 120000,
  "salaryRangeTo": 180000,
  "salaryCurrency": "USD",
  "criterionDetails": [
    {
      "priority": "Must Have",
      "criterion_text": "5+ years of professional software development experience with JavaScript and Node.js"
    },
    {
      "priority": "Must Have",
      "criterion_text": "Strong experience with RESTful API design and development"
    },
    {
      "priority": "Nice to Have",
      "criterion_text": "Experience with cloud platforms (AWS, Azure, or GCP)"
    }
  ],
  "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."
}

Update Job

Update an existing job posting. You can update any field(s) - all fields are optional for partial updates.

`PUT /jobs/:jobId`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Path Parameters

Parameter	Type	Description
`jobId`	integer	The unique identifier of the job to update

Request Body

All fields are optional - you can update just the fields you want to change. Fields not included in the request will remain unchanged.

Updateable Fields

All fields from the Create Job endpoint can be updated, with the following differences:

All fields are optional (no required fields for updates)
Status values: Can be "DRAFT", "ACTIVE", "INACTIVE", or "DELETED" (more options than create)
Null values: Some fields can be set to null to clear them (e.g., teamId, contractType, degreeLevel, jobRole, potentialAmount, potentialAmountCurrency, potentialHiresCount, yearOfExperience, description, screeningQuestion, applicationForm, criterionDetails). Fields like city, state, and country cannot be set to null - omit them if you don’t want to change them.
Partial updates: Only include fields you want to change

Status Transition Rules

Important: Once a job status moves from "DRAFT", it cannot be changed back to "DRAFT". Valid status transitions:

✅ DRAFT → ACTIVE → INACTIVE → DELETED
❌ ACTIVE → DRAFT (not allowed)

applicationForm Updates

The applicationForm field allows you to configure which fields are required, optional, or hidden in the candidate application form. Structure:

{
  "applicationForm": {
    "phone": "OPTIONAL" | "MANDATORY" | "OFF",
    "currentJobTitle": "OPTIONAL" | "MANDATORY" | "OFF",
    "resume": "OPTIONAL" | "MANDATORY" | "OFF",
    "otherFiles": "OPTIONAL" | "MANDATORY" | "OFF",
    "company": "OPTIONAL" | "MANDATORY" | "OFF",
    "isWillingToRelocate": "MANDATORY" | "OFF",
    "noticePeriod": "OPTIONAL" | "MANDATORY" | "OFF",
    "expectedCTC": "OPTIONAL" | "MANDATORY" | "OFF",
    "currentCTC": "OPTIONAL" | "MANDATORY" | "OFF",
    "currencyExpectedCTC": "string (currency code)",
    "currencyCurrentCTC": "string (currency code)",
    "expectedCTCPeriod": "ANNUALLY" | "MONTHLY",
    "currentCTCPeriod": "ANNUALLY" | "MONTHLY",
    "gender": "OPTIONAL" | "MANDATORY" | "OFF",
    "dateOfBirth": "OPTIONAL" | "MANDATORY" | "OFF",
    "nationality": "OPTIONAL" | "MANDATORY" | "OFF"
  }
}

Field Descriptions:

Field	Values	Description
`phone`	`OPTIONAL`, `MANDATORY`, `OFF`	Phone number field requirement
`currentJobTitle`	`OPTIONAL`, `MANDATORY`, `OFF`	Current job title field requirement
`resume`	`OPTIONAL`, `MANDATORY`, `OFF`	Resume/CV upload requirement
`otherFiles`	`OPTIONAL`, `MANDATORY`, `OFF`	Other documents upload requirement
`company`	`OPTIONAL`, `MANDATORY`, `OFF`	Current company field requirement
`isWillingToRelocate`	`MANDATORY`, `OFF`	Willingness to relocate question (no OPTIONAL)
`noticePeriod`	`OPTIONAL`, `MANDATORY`, `OFF`	Notice period field requirement
`expectedCTC`	`OPTIONAL`, `MANDATORY`, `OFF`	Expected compensation requirement
`currentCTC`	`OPTIONAL`, `MANDATORY`, `OFF`	Current compensation requirement
`currencyExpectedCTC`	string	Currency code for expected CTC (required if `expectedCTC` is not `OFF`)
`currencyCurrentCTC`	string	Currency code for current CTC (required if `currentCTC` is not `OFF`)
`expectedCTCPeriod`	`ANNUALLY`, `MONTHLY`	Period for expected CTC
`currentCTCPeriod`	`ANNUALLY`, `MONTHLY`	Period for current CTC
`gender`	`OPTIONAL`, `MANDATORY`, `OFF`	Gender field requirement
`dateOfBirth`	`OPTIONAL`, `MANDATORY`, `OFF`	Date of birth field requirement
`nationality`	`OPTIONAL`, `MANDATORY`, `OFF`	Nationality field requirement

Important Notes:

When updating applicationForm, it will be merged with the existing applicationForm (new values override existing)
If expectedCTC or currentCTC is set to MANDATORY or OPTIONAL (not OFF), the corresponding currency field (currencyExpectedCTC or currencyCurrentCTC) is required
If currency is not provided and the job doesn’t have an existing currency value, the update will fail

Example Requests

Basic Update (Single Field)

curl -X PUT "https://partner-api.taptalent.io/v1/partner/jobs/12345" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Senior Software Engineer Position"
  }'

Multiple Fields Update

curl -X PUT "https://partner-api.taptalent.io/v1/partner/jobs/12345" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Full Stack Developer",
    "description": "We are looking for an experienced full stack developer...",
    "city": "San Francisco",
    "state": "California",
    "country": "United States",
    "workMode": "REMOTE",
    "status": "ACTIVE",
    "contractType": "Permanent",
    "degreeLevel": "Bachelor'\''s",
    "jobRole": "Engineering"
  }'

Update applicationForm

curl -X PUT "https://partner-api.taptalent.io/v1/partner/jobs/12345" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationForm": {
      "phone": "MANDATORY",
      "resume": "MANDATORY",
      "currentJobTitle": "OPTIONAL",
      "company": "OFF",
      "isWillingToRelocate": "MANDATORY",
      "noticePeriod": "OPTIONAL",
      "expectedCTC": "MANDATORY",
      "currencyExpectedCTC": "USD",
      "expectedCTCPeriod": "ANNUALLY",
      "currentCTC": "OPTIONAL",
      "currencyCurrentCTC": "USD",
      "currentCTCPeriod": "MONTHLY",
      "gender": "OFF",
      "dateOfBirth": "OPTIONAL",
      "nationality": "MANDATORY"
    }
  }'

Update Status

curl -X PUT "https://partner-api.taptalent.io/v1/partner/jobs/12345" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "INACTIVE"
  }'

Update Salary Range

curl -X PUT "https://partner-api.taptalent.io/v1/partner/jobs/12345" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "salaryRangeFrom": 120000,
    "salaryRangeTo": 180000,
    "salaryCurrency": "USD"
  }'

Update Screening Questions

curl -X PUT "https://partner-api.taptalent.io/v1/partner/jobs/12345" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "screeningQuestion": [
      {
        "type": "text",
        "question": "Why are you interested in this position?"
      },
      {
        "type": "text",
        "question": "What is your experience with React?"
      }
    ]
  }'

Update Criterion Details

curl -X PUT "https://partner-api.taptalent.io/v1/partner/jobs/12345" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "criterionDetails": [
      {
        "priority": "Must Have",
        "criterion_text": "5+ years of experience in JavaScript"
      },
      {
        "priority": "Nice to Have",
        "criterion_text": "Experience with TypeScript"
      }
    ]
  }'

Example Response

{
  "id": 12345,
  "title": "Updated Senior Software Engineer Position",
  "description": "We are looking for an experienced software engineer...",
  "city": "San Francisco",
  "state": "California",
  "country": "United States",
  "pipelineId": "pipelineId_1",
  "status": "ACTIVE",
  "workMode": "REMOTE",
  "screeningQuestion": [
    {
      "type": "text",
      "question": "Why are you interested in this position?"
    }
  ],
  "applicationForm": {
    "phone": "MANDATORY",
    "resume": "MANDATORY",
    "currentJobTitle": "OPTIONAL",
    "company": "OFF",
    "isWillingToRelocate": "MANDATORY",
    "noticePeriod": "OPTIONAL",
    "expectedCTC": "MANDATORY",
    "currencyExpectedCTC": "USD",
    "expectedCTCPeriod": "ANNUALLY",
    "currentCTC": "OPTIONAL",
    "currencyCurrentCTC": "USD",
    "currentCTCPeriod": "MONTHLY",
    "gender": "OFF",
    "dateOfBirth": "OPTIONAL",
    "nationality": "MANDATORY"
  },
      "clientId": "clientId_1",
      "companyId": "companyId_1",
  "teamId": null,
  "contractType": "Permanent",
  "degreeLevel": "Bachelor's",
  "jobRole": "Engineering",
  "salaryRangeFrom": 120000,
  "salaryRangeTo": 180000,
  "salaryCurrency": "USD",
  "criterionDetails": [
    {
      "priority": "Must Have",
      "criterion_text": "5+ years of experience in JavaScript"
    }
  ],
  "pipelineStage": [
    {
      "name": "Applied",
      "type": "APPLIED",
      "totalCandidate": 5
    }
  ]
}

Error Responses

Empty Request Body:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Request body cannot be empty. At least one field must be provided for update."
  }
}

Invalid Status Transition (trying to revert to DRAFT):

{
  "error": {
    "code": "INVALID_STATUS_TRANSITION",
    "type": "validation_error",
    "message": "Cannot change job status back to DRAFT. Current status is ACTIVE. Once a job moves from DRAFT, it cannot be reverted."
  }
}

Job Not Found:

{
  "error": {
    "code": "NOT_FOUND",
    "type": "not_found",
    "message": "Job not found"
  }
}

Permission Denied (job doesn’t belong to your company):

{
  "error": {
    "code": "PERMISSION_DENIED",
    "type": "authorization_error",
    "message": "You are not authorized to update this job. The job does not belong to your company."
  }
}

Missing Currency for CTC:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "currencyExpectedCTC is required when expectedCTC is not OFF"
  }
}

Invalid Salary Range:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "One or more fields are invalid.",
    "details": {
      "salaryRangeTo": "salaryRangeTo must be greater than salaryRangeFrom"
    }
  }
}

Partial Salary Fields (missing one):

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "One or more fields are invalid.",
    "details": {
      "salaryCurrency": "salaryRangeFrom, salaryRangeTo, and salaryCurrency must be provided together"
    }
  }
}

Validation Rules

Request body: Cannot be empty - at least one field must be provided
Status: Cannot revert to DRAFT once moved past it
Salary fields: All three (salaryRangeFrom, salaryRangeTo, salaryCurrency) must be provided together if any is provided
CTC fields: currencyExpectedCTC required if expectedCTC is not OFF (and job doesn’t have existing currency)
CTC fields: currencyCurrentCTC required if currentCTC is not OFF (and job doesn’t have existing currency)
applicationForm: Merged with existing applicationForm if present
All field validations: Same as Create Job endpoint (type, length, format validations)

Best Practices

Partial Updates: Only include fields you want to change - other fields remain unchanged
Status Management: Use status transitions carefully - remember you can’t revert to DRAFT
applicationForm: When updating applicationForm, you can provide just the fields you want to change - they’ll be merged with existing values
Currency Fields: Always provide currency when setting CTC fields to MANDATORY or OPTIONAL
Error Handling: Check error codes to understand validation failures

Use Cases

Syncing Open Roles

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

Listing All Jobs

Retrieve a paginated list of all jobs in your company to:

Display jobs in your dashboard
Sync job data with external systems
Monitor job status and candidate counts
Track revenue and hiring metrics

Updating Hiring Requirements

Update job details programmatically to:

Modify job descriptions and requirements
Change candidate form requirements (applicationForm)
Update screening questions and criteria
Adjust salary ranges and job details
Manage job status lifecycle

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

Get Started

Authentication

API Reference

Webhooks

Integration Notes

​List Jobs

​GET /jobs

​Authentication

​Query Parameters

​Example Request

​Example Response

​Response Fields

​Error Responses

​Create Job

​POST /jobs

​Authentication

​Request Body Parameters

​Required Fields

title (string, required)

city (string, required)

state (string, required)

country (string, required)

​Optional Fields

description (string, optional)

status (string, optional)

workMode (string, optional)

screeningQuestion (array, optional)

teamId (string UUID, optional)

contractType (string, optional)

degreeLevel (string, optional)

jobRole (string, optional)

salaryRangeFrom (number, conditional*)

salaryRangeTo (number, conditional*)

salaryCurrency (string, conditional*)

potentialAmount (number, optional)

potentialAmountCurrency (string, conditional**)

potentialHiresCount (number, optional)

yearOfExperience (number, optional)

applicationForm (object, optional)

criterionDetails (array, optional)

​applicationForm Structure

​Field Descriptions

​Example: Complete applicationForm

​Example: Minimal applicationForm (Only Required Fields)

​Important Notes

​Job Criteria (criterionDetails)

​Why Job Criteria Matter

​Understanding Priority Levels

​Best Practices for Writing Criteria

​CriterionDetails Structure

​Example: Software Engineer Job

​Example: Marketing Manager Job

​How Criteria Affect Candidate Matching

​Validation Rules

​Tips for Developers

​Valid Job Role Values

​Parameter Quick Reference

​Common Use Case Examples

​Example 1: Remote Software Engineer Position

​Example 2: Onsite Sales Position with Commission

​Example 3: Entry-Level Internship

​Example Request

​Example Response

​Validation Rules

​Common Errors

​Get Job

​GET /jobs/:jobId

​Authentication

​Path Parameters

​Example Request

​Example Response

​Error Responses

​Update Job

​PUT /jobs/:jobId

​Authentication

​Path Parameters

​Request Body

​Updateable Fields

​Status Transition Rules

​applicationForm Updates

List Jobs

`GET /jobs`

Authentication

Query Parameters

Example Request

Example Response

Response Fields

Error Responses

Create Job

`POST /jobs`

Authentication

Request Body Parameters

Required Fields

`title` (string, required)

`city` (string, required)

`state` (string, required)

`country` (string, required)

Optional Fields

`description` (string, optional)

`status` (string, optional)

`workMode` (string, optional)

`screeningQuestion` (array, optional)

`teamId` (string UUID, optional)

`contractType` (string, optional)

`degreeLevel` (string, optional)

`jobRole` (string, optional)

`salaryRangeFrom` (number, conditional*)

`salaryRangeTo` (number, conditional*)

`salaryCurrency` (string, conditional*)

`potentialAmount` (number, optional)

`potentialAmountCurrency` (string, conditional**)

`potentialHiresCount` (number, optional)

`yearOfExperience` (number, optional)

`applicationForm` (object, optional)

`criterionDetails` (array, optional)

applicationForm Structure

Field Descriptions

Example: Complete applicationForm

Example: Minimal applicationForm (Only Required Fields)

Important Notes

Job Criteria (criterionDetails)

Why Job Criteria Matter

Understanding Priority Levels

Best Practices for Writing Criteria

CriterionDetails Structure

Example: Software Engineer Job

Example: Marketing Manager Job

How Criteria Affect Candidate Matching

Validation Rules

Tips for Developers

Valid Job Role Values

Parameter Quick Reference

Common Use Case Examples

Example 1: Remote Software Engineer Position

Example 2: Onsite Sales Position with Commission

Example 3: Entry-Level Internship

Example Request

Example Response

Validation Rules

Common Errors

Get Job

`GET /jobs/:jobId`

Authentication

Path Parameters

Example Request

Example Response

Error Responses

Update Job

`PUT /jobs/:jobId`

Authentication

Path Parameters

Request Body

Updateable Fields

Status Transition Rules

applicationForm Updates

Example Requests

Basic Update (Single Field)

Multiple Fields Update

Update applicationForm

Update Status