> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taptalent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Jobs

> API endpoints for managing job postings

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) |
| `jobTitle`     | string  | No       | Filter jobs by title (default: `""`)                              |
| `teamId`       | string  | No       | Filter by team ID                                                 |
| `city`         | string  | No       | Filter jobs by city                                               |
| `state`        | string  | No       | Filter jobs by state                                              |
| `country`      | string  | No       | Filter jobs by country (default: `""`)                            |
| `careerLevel`  | string  | No       | Filter by career level                                            |
| `contractType` | string  | No       | Filter by contract type                                           |
| `degreeLevel`  | string  | No       | Filter by degree level                                            |
| `jobRole`      | string  | No       | Filter by job role                                                |
| `status`       | string  | No       | Filter by status. Allowed values: `DRAFT`, `ACTIVE`, `INACTIVE`   |
| `publishType`  | string  | No       | Filter by publish type. Allowed values: `EXTERNAL`, `INTERNAL`    |
| `workMode`     | string  | No       | Filter by work mode. Allowed values: `REMOTE`, `ONSITE`, `HYBRID` |

### Example Request

```bash theme={null}
curl -X GET "https://partner-api.taptalent.io/v1/partner/jobs?pageNumber=1&perPage=20&jobTitle=Engineer&country=United%20States" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json"
```

### Example Request (Extended Filters)

```bash theme={null}
curl -X GET "https://partner-api.taptalent.io/v1/partner/jobs?pageNumber=1&perPage=20&jobTitle=Engineer&country=United%20States&status=ACTIVE&publishType=EXTERNAL&workMode=REMOTE" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json"
```

### Example Response

```json theme={null}
{
  "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",
      "customFields": {
        "cf_001": {
          "label": "Department",
          "value": "Engineering",
          "parentSection": "Job Details"
        },
        "cf_002": {
          "label": "Cost Center",
          "value": "",
          "parentSection": null
        }
      }
    }
  ],
  "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
* `customFields`: Object keyed by custom field ID, each containing `label`, `value`, and `parentSection`. All company-level job custom fields are always present — fields with no value set will have `value: ""`

### Error Responses

**Invalid perPage value**:

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

**Invalid status value**:

```json theme={null}
{
  "error": {
    "code": "INVALID_STATUS",
    "type": "validation_error",
    "message": "status must be one of: DRAFT, ACTIVE, INACTIVE"
  }
}
```

**Invalid publishType value**:

```json theme={null}
{
  "error": {
    "code": "INVALID_PUBLISH_TYPE",
    "type": "validation_error",
    "message": "publishType must be one of: EXTERNAL, INTERNAL"
  }
}
```

**Invalid workMode value**:

```json theme={null}
{
  "error": {
    "code": "INVALID_WORK_MODE",
    "type": "validation_error",
    "message": "workMode must be one of: REMOTE, ONSITE, HYBRID"
  }
}
```

## 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 120 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**:

```json theme={null}
"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](#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**:

```json theme={null}
"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`,\
`NZD`, `SAR`, `QAR`, `KWD`, `BHD`, `OMR`, `PKR`, `BDT`, `LKR`, `NPR`, `EGP`, `NGN`, `KES`, `TWD`, `ILS`, `ARS`, `CLP`, `COP`, `CZK`, `HUF`, `RON`, `UAH`

**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](#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](#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](#job-criteria-criteriondetails) 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](#job-criteria-criteriondetails) 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

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

1. **Be Specific**: Instead of "Good communication skills", write "Excellent written and verbal communication skills with experience presenting to stakeholders"

2. **Focus on Measurable Skills**: Include specific technologies, tools, or certifications (e.g., "5+ years of experience with React and TypeScript")

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

4. **Keep It Relevant**: Only include criteria that directly relate to job performance

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

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

1. **AI Evaluation**: TapTalent's AI analyzes each candidate's resume against your criteria
2. **Match Scoring**: Candidates receive a profile match score based on how well they meet your criteria
3. **Priority Weighting**: "Must Have" criteria carry more weight in the scoring than "Nice to Have" or "Bonus" criteria
4. **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:

1. **Make Priority Selection Easy**: Provide clear UI options for priority selection with helpful descriptions
2. **Character Limits**: Show character count for `criterion_text` (max 3000)
3. **Validation**: Enforce the 7-criteria maximum and validate text length
4. **Default Values**: Pre-fill `priority` as `"Nice to Have"` for better UX
5. **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-120 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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-120 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**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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**:

```json theme={null}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "type": "internal_error",
    "message": "Something went wrong."
  }
}
```

**Invalid API Key**:

```json theme={null}
{
  "message": "Invalid API key"
}
```

**Inactive Subscription**:

```json theme={null}
{
  "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](#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**:

```json theme={null}
{
  "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)

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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):

```json theme={null}
{
  "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**:

```json theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "type": "not_found",
    "message": "Job not found"
  }
}
```

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

```json theme={null}
{
  "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**:

```json theme={null}
{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "currencyExpectedCTC is required when expectedCTC is not OFF"
  }
}
```

**Invalid Salary Range**:

```json theme={null}
{
  "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):

```json theme={null}
{
  "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

1. **Partial Updates**: Only include fields you want to change - other fields remain unchanged
2. **Status Management**: Use status transitions carefully - remember you can't revert to DRAFT
3. **applicationForm**: When updating `applicationForm`, you can provide just the fields you want to change - they'll be merged with existing values
4. **Currency Fields**: Always provide currency when setting CTC fields to MANDATORY or OPTIONAL
5. **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](/webhooks/overview) to receive notifications when jobs are updated
* Review [Integration Notes](/integration-notes/overview) for best practices
* Explore other [API endpoints](/api-reference/overview)