Skip to main content
POST

Authorizations

​
Authorization
string
header
required

Company-scoped API key. Production keys are prefixed sk_live_, sandbox keys sk_test_, each followed by 22 base62 characters (pattern ^sk_(live|test)_[0-9A-Za-z]{22}$). Generate keys in the TapTalent dashboard under Account Settings → Developers → API Key Management; a key is shown once at generation and old keys are invalidated immediately on regeneration.

Body

application/json

Request body for creating a job. The three salary fields (salaryRangeFrom, salaryRangeTo, salaryCurrency) must be provided together or omitted together, with salaryRangeTo greater than salaryRangeFrom. potentialAmountCurrency is required whenever potentialAmount is provided.

​
title
string
required

The job title displayed to candidates and in job listings. Should be clear and descriptive; avoid non-standard abbreviations.

Required string length: 3 - 500
Example:

"Senior Software Engineer"

​
city
string
required

The city where the job is located (full city name, without state/province or country — use the state and country fields for those).

Maximum string length: 200
Example:

"San Francisco"

​
state
string
required

The state or province where the job is located (full name). For countries without states/provinces, you can use the country name or an empty string.

Maximum string length: 200
Example:

"California"

​
country
string
required

The country where the job is located (full country name).

Maximum string length: 200
Example:

"United States"

​
description
string

Detailed job description. If omitted, TapTalent auto-generates a description based on the other job fields.

Maximum string length: 10000
​
status
enum<string>
default:DRAFT

Whether the job is immediately visible to candidates (ACTIVE) or saved as a draft (DRAFT, the default). Only these two values are allowed at creation; INACTIVE and DELETED exist only for updates.

Available options:
DRAFT,
ACTIVE
​
workMode
enum<string>
default:ONSITE

Work arrangement for the position. Defaults to ONSITE.

Available options:
ONSITE,
REMOTE,
HYBRID
​
screeningQuestion
object[]

Pre-screening questions candidates must answer when applying. Maximum 15 questions; only text questions are supported. Defaults to an empty array.

Maximum array length: 15
​
teamId
string<uuid>

Associates the job with a specific team. Must be an existing team id in your TapTalent account.

Example:

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

​
contractType
enum<string>

Employment contract type.

Available options:
Permanent,
Freelance / Consultant,
Fixed term contract,
Internship,
Student
​
degreeLevel
enum<string>

Minimum education level required for the position.

Available options:
High School,
Bachelor's,
Master's,
M.B.A.,
Ph.D.,
Other
​
jobRole
enum<string>

Job role category, used for organization and candidate matching.

Available options:
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
​
salaryRangeFrom
integer

Minimum annual salary. Must be provided together with salaryRangeTo and salaryCurrency, and must be less than salaryRangeTo.

Required range: 0 <= x <= 9999999999
Example:

120000

​
salaryRangeTo
integer

Maximum annual salary. Must be provided together with salaryRangeFrom and salaryCurrency, and must be greater than salaryRangeFrom.

Required range: 0 <= x <= 9999999999
Example:

180000

​
salaryCurrency
enum<string>

Currency for the salary range. Must be provided together with salaryRangeFrom and salaryRangeTo.

Available options:
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

Potential revenue or value associated with filling this position (e.g. commission potential). If provided, potentialAmountCurrency is required.

Required range: x >= 0
Example:

50000

​
potentialAmountCurrency
string

Currency for the potential amount: a 3-character uppercase currency code. Required if potentialAmount is provided.

Required string length: 3
Pattern: ^[A-Z]{3}$
Example:

"USD"

​
potentialHiresCount
integer

Number of people you plan to hire for this position.

Required range: x >= 1
Example:

3

​
yearOfExperience
number

Minimum years of professional experience required. Use 0 for entry-level positions.

Required range: 0 <= x <= 50
Example:

5

​
applicationForm
object

Configures which fields are required, optional, or hidden in the candidate application form. If not provided, default values are set automatically by the system.

​
criterionDetails
object[]

Detailed job requirements and qualifications (maximum 7), used by TapTalent's AI to match and score candidates.

Maximum array length: 7

Response

The created job (bare job object, no envelope).

Full job object returned by the create and get endpoints (bare object, no envelope). Note that pipelineStage is null in the documented create/get responses (it is populated in the list and update responses) and createdAt does not appear in this shape.

​
id
integer
required

Unique identifier of the job.

​
title
string
required

Job title displayed to candidates.

​
city
string
required

Job location city.

​
state
string
required

Job location state/province.

​
country
string
required

Job location country.

​
pipelineId
integer
required

Identifier of the hiring pipeline attached to the job. The published documentation shows the placeholder string "pipelineId_1"; the API uses the integer pipeline id (as in the Pipelines API).

Example:

181

​
status
enum<string>
required

Job lifecycle status. The documented lifecycle path is DRAFT → ACTIVE → INACTIVE → DELETED. The only documented restriction is that once a job leaves DRAFT it can never return to DRAFT; other reverse transitions (e.g. reactivation) are not documented either way. When creating a job only DRAFT and ACTIVE are allowed (see JobStatusCreate).

Available options:
DRAFT,
ACTIVE,
INACTIVE,
DELETED
​
workMode
enum<string>
required

Work arrangement for the position. ONSITE (default at creation): work at a physical office location; REMOTE: work from anywhere; HYBRID: a combination of onsite and remote work.

Available options:
ONSITE,
REMOTE,
HYBRID
​
description
string

Detailed job description (auto-generated if not supplied at creation).

​
screeningQuestion
object[]

Pre-screening questions candidates must answer when applying.

​
skills
string[]

Undocumented; type observed from examples (always an empty array in documented responses).

​
applicationForm
object

Configuration of the candidate application form: which fields are required, optional, or hidden when a candidate applies to the job. All keys are optional — specify only the fields you want to configure. If the object is omitted at creation, the system sets default values automatically. When updating a job, the submitted object is MERGED with the job's existing applicationForm (new values override existing ones); it is not replaced wholesale.

​
clientId
integer

Undocumented; type observed from examples. The documentation shows the placeholder string "clientId_1"; modeled as the underlying integer client id.

Example:

301

​
companyId
integer

Undocumented; type observed from examples. The documentation shows the placeholder string "companyId_1"; modeled as the underlying integer company id.

Example:

12001

​
teamId
string<uuid> | null

Team the job is assigned to, or null if unassigned.

​
careerLevel
string | null

Undocumented; type observed from examples (always null in documented responses).

​
contractType
enum<string>

Employment contract type.

Available options:
Permanent,
Freelance / Consultant,
Fixed term contract,
Internship,
Student
​
degreeLevel
enum<string>

Minimum education level required for the position.

Available options:
High School,
Bachelor's,
Master's,
M.B.A.,
Ph.D.,
Other
​
jobRole
enum<string>

Job role category, used for job organization and candidate matching.

Available options:
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
​
salaryRangeFrom
integer

Minimum annual salary.

​
salaryRangeTo
integer

Maximum annual salary.

​
salaryCurrency
enum<string>

Currency code for the salary range.

Available options:
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
​
criterionDetails
object[]

Job requirements used for AI candidate matching.

​
publishType
string | null

Undocumented; type observed from examples (always null in documented responses).

​
companyClientId
integer | null

Undocumented; type observed from examples (always null in documented responses).

​
potentialAmount
number | null

Potential revenue or value associated with filling this position.

​
potentialAmountCurrency
string | null

Currency for the potential amount (3-character uppercase code).

​
potentialHiresCount
integer | null

Number of people planned to be hired for this position.

​
closingStatus
string | null

Undocumented; type observed from examples (always null in documented responses).

​
closingReason
string | null

Undocumented; type observed from examples (always null in documented responses).

​
referralTemplateId
integer | null

Undocumented; type observed from examples (always null in documented responses).

​
pipelineStage
object[] | null

Pipeline stages with per-stage candidate counts. null in the documented create/get responses; populated in the list and update responses.

​
jobType
string | null

Undocumented; type observed from examples (always null in documented responses).