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

# Add a job

> Create a new job posting in your Hirempire account

## Authentication

<ResponseField name="Authorization" type="string" required>
  Bearer authentication header of the form `Bearer <token>`, where `<token>` is your auth token.
</ResponseField>

## Request Body

<ParamField body="company_id" type="string" required>
  Unique identifier for the company
</ParamField>

<ParamField body="job_title" type="string" required>
  Title of the job position
</ParamField>

<ParamField body="department" type="string" required>
  Department where the job belongs. Allowed departments: `Accounting/Auditing` `Administrative` `Advertising` `Analyst` `Art/Creative` `Business Development` `Consulting` `Customer Service` `Design` `Distribution` `Education` `Engineering` `Finance` `Health Care Provider` `Human Resources` `Information Technology` `Legal` `Management` `Manufacturing` `Marketing` `Product Management` `Project Management` `Production` `Public Relations` `Purchasing` `Quality Assurance` `Research` `Sales` `Science` `Strategy/Planning` `Supply Chain` `Training` `Operations` `Other`
</ParamField>

<ParamField body="job_country" type="string" required>
  Country where the job is located
</ParamField>

<ParamField body="city" type="string">
  City where the job is located
</ParamField>

<ParamField body="salary" type="number" required>
  Salary information for the position
</ParamField>

<ParamField body="currency" type="string" required>
  Currency of the salary. Valid currency is in three-letter alphabetic codes. Examples: `USD` `EUR` `GBP`
</ParamField>

<ParamField body="salary_period" type="string" required>
  Period of the salary. Options: `Per hour` `Per day` `Per week` `Bi-weekly` `Per month` `Per year`
</ParamField>

<ParamField body="hide_salary" type="boolean">
  Hide salary in job application. Default is `false`
</ParamField>

<ParamField body="job_type" type="string" required>
  Employment type. Options: `Full-time` `Part-time` `Contract` `Freelance` `Internship` `Temporary` `Project-based`
</ParamField>

<ParamField body="workplace" type="string" required>
  Workplace type. Options: `On-site` `Remote` `Hybrid`
</ParamField>

<ParamField body="career_level" type="string" required>
  Career Level. Options: `Junior` `Mid-level` `Senior` `Team Leader` `Manager` `Director` `VP` `C-level`
</ParamField>

<ParamField body="job_description" type="string" required>
  Full description of the job requirements and responsibilities
</ParamField>

<ParamField body="job_sources" type="string[]" required>
  Array of job posting sources. Example: `LinkedIn` `Referral` or any source you would like to add.
</ParamField>

<ParamField body="industry" type="string">
  Industry classification (optional).
</ParamField>

<ParamField body="public_slug" type="string">
  URL slug for the public job board page. If omitted, auto-generated from the job title with a random 4-char suffix.
</ParamField>

<ParamField body="questions" type="object">
  Application form configuration (optional). Object shape:

  ```
  {
    "fields": {
      "show_cover_letter": boolean,
      "show_photo": boolean,
      "show_experience_years": boolean,
      "show_languages": boolean,
      "show_nationality": boolean,
      "show_location": boolean,
      "show_salary_expectation": boolean
    },
    "custom": [
      { "label": string, "type": string, "options": any, "required": boolean }
    ]
  }
  ```

  `custom[].type` must be one of: `text` `textarea` `number` `date` `url` `file` `single_select` `multi_select` `video` `audio`.
</ParamField>

<ParamField body="status" type="string">
  Job posting status. Accepted input values: `Pending` `Active` `Paused` `Hired` `Closed`. Values are normalized to lowercase before storage. `Pending` is mapped to `draft`. `Hired` is accepted as a **deprecated alias** for `Closed`. Default is `draft`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.hirempire.com/v1/add-job' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "company_id": "12345",
      "job_title": "Software Engineer",
      "department": "Engineering",
      "job_country": "USA",
      "city": "San Francisco",
      "salary": 100000,
      "currency": "USD",
      "salary_period": "Per year",
      "hide_salary": false,
      "job_type": "Full-time",
      "workplace": "Remote",
      "career_level": "Mid-level",
      "job_description": "Develop and maintain software applications, collaborate with cross-functional teams, and ensure high-quality code through testing and code reviews.",
      "job_sources": ["LinkedIn", "Facebook"],
      "status": "Active"
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.hirempire.com/v1/add-job', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      company_id: "12345",
      job_title: "Software Engineer",
      department: "Engineering",
      job_country: "USA",
      city: "San Francisco",
      salary: 100000,
      currency: "USD",
      salary_period: "Per year",
      hide_salary: false,
      job_type: "Full-time",
      workplace: "Remote",
      career_level: "Mid-level",
      job_description: "Develop and maintain software applications, collaborate with cross-functional teams, and ensure high-quality code through testing and code reviews.",
      job_sources: ["LinkedIn", "Facebook"],
      status: "Active"
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://api.hirempire.com/v1/add-job"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  }

  payload = {
      "company_id": "12345",
      "job_title": "Software Engineer",
      "department": "Engineering",
      "job_country": "USA",
      "city": "San Francisco",
      "salary": 100000,
      "currency": "USD",
      "salary_period": "Per year",
      "hide_salary": False,
      "job_type": "Full-time",
      "workplace": "Remote",
      "career_level": "Mid-level",
      "job_description": "Develop and maintain software applications, collaborate with cross-functional teams, and ensure high-quality code through testing and code reviews.",
      "job_sources": ["LinkedIn", "Facebook"],
      "status": "Active"
  }

  response = requests.post(url, headers=headers, data=json.dumps(payload))
  data = response.json()
  print(data)
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  $payload = json_encode([
      "company_id" => "12345",
      "job_title" => "Software Engineer",
      "department" => "Engineering",
      "job_country" => "USA",
      "city" => "San Francisco",
      "salary" => 100000,
      "currency" => "USD",
      "salary_period" => "Per year",
      "hide_salary" => false,
      "job_type" => "Full-time",
      "workplace" => "Remote",
      "career_level" => "Mid-level",
      "job_description" => "Develop and maintain software applications, collaborate with cross-functional teams, and ensure high-quality code through testing and code reviews.",
      "job_sources" => ["LinkedIn", "Facebook"],
      "status" => "Active"
  ]);

  curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.hirempire.com/v1/add-job',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => array(
      'Authorization: Bearer YOUR_TOKEN',
      'Content-Type: application/json'
    ),
  ));

  $response = curl_exec($curl);
  curl_close($curl);

  $data = json_decode($response, true);
  print_r($data);
  ?>
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'

  uri = URI('https://api.hirempire.com/v1/add-job')
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = 'Bearer YOUR_TOKEN'
  request['Content-Type'] = 'application/json'
  request.body = {
    company_id: "12345",
    job_title: "Software Engineer",
    department: "Engineering",
    job_country: "USA",
    city: "San Francisco",
    salary: 100000,
    currency: "USD",
    salary_period: "Per year",
    hide_salary: false,
    job_type: "Full-time",
    workplace: "Remote",
    career_level: "Mid-level",
    job_description: "Develop and maintain software applications, collaborate with cross-functional teams, and ensure high-quality code through testing and code reviews.",
    job_sources: ["LinkedIn", "Facebook"],
    status: "Active"
  }.to_json

  response = http.request(request)
  data = JSON.parse(response.body)
  puts data
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "io"
      "net/http"
  )

  func main() {
      payload := map[string]interface{}{
          "company_id": "12345",
          "job_title": "Software Engineer",
          "department": "Engineering",
          "job_country": "USA",
          "city": "San Francisco",
          "salary": 100000,
          "currency": "USD",
          "salary_period": "Per year",
          "hide_salary": false,
          "job_type": "Full-time",
          "workplace": "Remote",
          "career_level": "Mid-level",
          "job_description": "Develop and maintain software applications, collaborate with cross-functional teams, and ensure high-quality code through testing and code reviews.",
          "job_sources": []string{"LinkedIn", "Facebook"},
          "status": "Active",
      }
      
      jsonPayload, _ := json.Marshal(payload)
      
      client := &http.Client{}
      req, _ := http.NewRequest("POST", "https://api.hirempire.com/v1/add-job", bytes.NewBuffer(jsonPayload))
      req.Header.Add("Authorization", "Bearer YOUR_TOKEN")
      req.Header.Add("Content-Type", "application/json")
      
      resp, _ := client.Do(req)
      defer resp.Body.Close()
      
      body, _ := io.ReadAll(resp.Body)
      fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;

  public class HirempireAPI {
      public static void main(String[] args) throws Exception {
          String payload = """
          {
              "company_id": "12345",
              "job_title": "Software Engineer",
              "department": "Engineering",
              "job_country": "USA",
              "city": "San Francisco",
              "salary": 100000,
              "currency": "USD",
              "salary_period": "Per year",
              "hide_salary": false,
              "job_type": "Full-time",
              "workplace": "Remote",
              "career_level": "Mid-level",
              "job_description": "Develop and maintain software applications, collaborate with cross-functional teams, and ensure high-quality code through testing and code reviews.",
              "job_sources": ["LinkedIn", "Facebook"],
              "status": "Active"
          }
          """;
          
          HttpClient client = HttpClient.newHttpClient();
          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create("https://api.hirempire.com/v1/add-job"))
              .header("Authorization", "Bearer YOUR_TOKEN")
              .header("Content-Type", "application/json")
              .POST(HttpRequest.BodyPublishers.ofString(payload))
              .build();
              
          HttpResponse<String> response = client.send(request, 
              HttpResponse.BodyHandlers.ofString());
          System.out.println(response.body());
      }
  }
  ```

  ```csharp C# theme={null}
  using System;
  using System.Net.Http;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      private static readonly HttpClient client = new HttpClient();

      static async Task Main(string[] args)
      {
          client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_TOKEN");
          
          var payload = """
          {
              "company_id": "12345",
              "job_title": "Software Engineer",
              "department": "Engineering",
              "job_country": "USA",
              "city": "San Francisco",
              "salary": 100000,
              "currency": "USD",
              "salary_period": "Per year",
              "hide_salary": false,
              "job_type": "Full-time",
              "workplace": "Remote",
              "career_level": "Mid-level",
              "job_description": "Develop and maintain software applications, collaborate with cross-functional teams, and ensure high-quality code through testing and code reviews.",
              "job_sources": ["LinkedIn", "Facebook"],
              "status": "Active"
          }
          """;
          
          var content = new StringContent(payload, Encoding.UTF8, "application/json");
          HttpResponseMessage response = await client.PostAsync("https://api.hirempire.com/v1/add-job", content);
          string responseBody = await response.Content.ReadAsStringAsync();
          
          Console.WriteLine(responseBody);
      }
  }
  ```

  ```swift Swift theme={null}
  import Foundation

  let url = URL(string: "https://api.hirempire.com/v1/add-job")!
  var request = URLRequest(url: url)
  request.httpMethod = "POST"
  request.setValue("Bearer YOUR_TOKEN", forHTTPHeaderField: "Authorization")
  request.setValue("application/json", forHTTPHeaderField: "Content-Type")

  let payload: [String: Any] = [
      "company_id": "12345",
      "job_title": "Software Engineer",
      "department": "Engineering",
      "job_country": "USA",
      "city": "San Francisco",
      "salary": 100000,
      "currency": "USD",
      "salary_period": "Per year",
      "hide_salary": false,
      "job_type": "Full-time",
      "workplace": "Remote",
      "career_level": "Mid-level",
      "job_description": "Develop and maintain software applications, collaborate with cross-functional teams, and ensure high-quality code through testing and code reviews.",
      "job_sources": ["LinkedIn", "Facebook"],
      "status": "Active"
  ]

  request.httpBody = try? JSONSerialization.data(withJSONObject: payload)

  let task = URLSession.shared.dataTask(with: request) { data, response, error in
      if let data = data {
          let json = try? JSONSerialization.jsonObject(with: data)
          print(json ?? "No data")
      }
  }

  task.resume()
  ```

  ```kotlin Kotlin theme={null}
  import kotlinx.coroutines.*
  import java.net.http.HttpClient
  import java.net.http.HttpRequest
  import java.net.http.HttpResponse
  import java.net.URI

  fun main() = runBlocking {
      val payload = """
      {
          "company_id": "12345",
          "job_title": "Software Engineer",
          "department": "Engineering",
          "job_country": "USA",
          "city": "San Francisco",
          "salary": 100000,
          "currency": "USD",
          "salary_period": "Per year",
          "hide_salary": false,
          "job_type": "Full-time",
          "workplace": "Remote",
          "career_level": "Mid-level",
          "job_description": "Develop and maintain software applications, collaborate with cross-functional teams, and ensure high-quality code through testing and code reviews.",
          "job_sources": ["LinkedIn", "Facebook"],
          "status": "Active"
      }
      """.trimIndent()
      
      val client = HttpClient.newHttpClient()
      val request = HttpRequest.newBuilder()
          .uri(URI.create("https://api.hirempire.com/v1/add-job"))
          .header("Authorization", "Bearer YOUR_TOKEN")
          .header("Content-Type", "application/json")
          .POST(HttpRequest.BodyPublishers.ofString(payload))
          .build()
          
      val response = client.send(request, HttpResponse.BodyHandlers.ofString())
      println(response.body())
  }
  ```

  ```rust Rust theme={null}
  use reqwest::header::{HeaderMap, HeaderValue, AUTHORIZATION, CONTENT_TYPE};
  use serde_json::json;

  #[tokio::main]
  async fn main() -> Result<(), Box<dyn std::error::Error>> {
      let mut headers = HeaderMap::new();
      headers.insert(AUTHORIZATION, HeaderValue::from_str("Bearer YOUR_TOKEN")?);
      headers.insert(CONTENT_TYPE, HeaderValue::from_str("application/json")?);
      
      let payload = json!({
          "company_id": "12345",
          "job_title": "Software Engineer",
          "department": "Engineering",
          "job_country": "USA",
          "city": "San Francisco",
          "salary": 100000,
          "currency": "USD",
          "salary_period": "Per year",
          "hide_salary": false,
          "job_type": "Full-time",
          "workplace": "Remote",
          "career_level": "Mid-level",
          "job_description": "Develop and maintain software applications, collaborate with cross-functional teams, and ensure high-quality code through testing and code reviews.",
          "job_sources": ["LinkedIn", "Facebook"],
          "status": "Active"
      });
      
      let client = reqwest::Client::new();
      let response = client
          .post("https://api.hirempire.com/v1/add-job")
          .headers(headers)
          .json(&payload)
          .send()
          .await?;
          
      let body = response.text().await?;
      println!("{}", body);
      
      Ok(())
  }
  ```
</RequestExample>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the job was created successfully
</ResponseField>

<ResponseField name="job_id" type="string">
  Unique identifier for the newly created job
</ResponseField>

<ResponseField name="job_status" type="string">
  Current status of the job posting (lowercase). One of: `draft` `active` `paused` `closed`
</ResponseField>

<ResponseField name="total_applications" type="integer">
  Number of applications received for this job
</ResponseField>

<ResponseField name="applications" type="array">
  Array of application objects

  <Expandable title="Application Object Properties">
    <ResponseField name="id" type="string">
      Unique identifier for the application
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp when the application was created
    </ResponseField>

    <ResponseField name="source" type="string">
      Source platform where the application came from
    </ResponseField>

    <ResponseField name="application_url" type="string">
      URL to view the full application details
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "job_id": "f3a2c1d4-1111-4222-9333-444455556666",
    "job_status": "active",
    "total_applications": 0,
    "applications": []
  }
  ```
</ResponseExample>

## Error Responses

### Authorization Errors

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Missing 'Authorization' header."
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Authorization header must start with 'Bearer '."
}
```

### Request Format Errors

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Query parameters or URL params are not allowed."
}
```

### Missing Required Fields

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Missing required field: company_id"
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Missing required field: job_title"
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Missing required field: department"
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Missing required field: job_country"
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Missing required field: salary"
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Missing required field: currency"
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Missing required field: salary_period"
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Missing required field: job_type"
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Missing required field: workplace"
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Missing required field: career_level"
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Missing required field: job_description"
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Missing required field: job_sources"
}
```

### Field Validation Errors

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Field 'salary' must be a number."
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Invalid salary_period. Allowed values: Per hour, Per day, Per week, Bi-weekly, Per month, Per year"
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Invalid job_type. Allowed values: Full-time, Part-time, Contract, Freelance, Internship, Temporary, Project-based"
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Invalid workplace. Allowed values: On-site, Remote, Hybrid"
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Invalid career_level. Allowed values: Junior, Mid-level, Senior, Team Leader, Manager, Director, VP, C-level"
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Field 'job_sources' must be an array."
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Invalid job_source: [source_name]. Allowed: LinkedIn, Referral, Alien Talents, Facebook, WhatsApp, Pinterest, Reddit, Snapchat, TikTok, X, Instagram, Xing, WeChat, YouTube, Indeed, My Website, Other, Hirempire"
}
```

**400 - Bad Request**

```json theme={null}
{
    "success": false,
    "error": "Field 'status' must be a string if provided."
}
```

### Company Authorization Errors

**401 - Unauthorized**

```json theme={null}
{
    "success": false,
    "error": "Invalid company id"
}
```

**401 - Unauthorized**

```json theme={null}
{
    "success": false,
    "error": "Unauthorized. You don't have the permission post a job in this company."
}
```

### Limit Reached Error

**402 - Payment Required**

```json theme={null}
{
    "success": false,
    "error": "Active jobs limit reached. Upgrade to add more, or close one of your jobs."
}
```

### Token Validation Errors

**401 - Unauthorized**

```json theme={null}
{
    "success": false,
    "error": "Invalid token"
}
```

**401 - Unauthorized**

```json theme={null}
{
    "success": false,
    "error": "Token is expired"
}
```