Teamtailor Job Board API

https://partner.teamtailor.com/job_boards
Admin
The Teamtailor Job Board API enables integration of external job boards with Teamtailor, allowing...
Tokens:19,160
Snippets:73
Trust Score:10
Update:10 months ago
Show doc for...
Tokens:
Raw
### Paginated Config Response Example

Source: https://partner.teamtailor.com/job_boards/index

Example JSON response for a paginated config request to the GET /config endpoint. This demonstrates how multiple pages of form configuration are structured, including 'page' and 'hasNextPage' attributes.

```JSON
{
  "config": {
    "1": [],
    "2": [],
    "3": [],
    "page": 1,
    "hasNextPage": true
  }
}

```

--------------------------------

### GET Config Endpoint Example

Source: https://partner.teamtailor.com/job_boards/index

Example of an HTTP GET request to the /config endpoint, used to retrieve configuration options for a job ad form. This endpoint supports pagination and job-specific configurations.

```HTTP
GET ${BASE_URL}/config?page=1&job_id=23&user_id=789 HTTP/1.1

```

--------------------------------

### Example Config Response

Source: https://partner.teamtailor.com/job_boards/index

Example JSON response for the GET /config endpoint, illustrating the structure of configuration options for a job ad form. It includes field definitions, pagination details, and supported field types.

```JSON
{
  "config": {
    "1": [
      {
        "id": "experience-level",
        "label": "Experience level",
        "placeholder": "Experience level",
        "type": "select",
        "options": [
          { "id": 1, "label": "Junior" },
          { "id": 2, "label": "Senior" },
        ]
      }
    ],
    "2": [
      {
        "id": "degree-level",
        "label": "Required degree level",
        "placeholder": "Choose degree level",
        "type": "select",
        "options": [
          { "id": 1, "label": "Bachelor's Degree" },
          { "id": 2, "label": "Master's Degree" },
        ]
      },
    ],
    "page": 1,
    "hasNextPage": true
  }
}

```

--------------------------------

### API Versioning Example

Source: https://partner.teamtailor.com/job_boards/index

This example demonstrates how to specify the API version for a request. It uses the `X-Api-Version` header to ensure compatibility when making API calls. The current version is '20180828'.

```http
PUT https://api.teamtailor.com/channel/v1/promotions/1 HTTP/1.1
X-Api-Version : 20180828
```

--------------------------------

### Email Integration Job Data Example

Source: https://partner.teamtailor.com/job_boards/index

This example demonstrates the structure of an email notification containing job ad data, including details about the job, locations, recruiter, department, company, and promotion. It shows various fields that can be included in these email alerts.

```text
Channel: Channel name
Reference number: teamtailor-23
Duration: 30
Publish date: 2021-03-24T00:00:00+01:00
End date: 2021-03-31T00:00:00+02:00
Remote status: none
Employment type: none
Employment level: none
Job offer url: https://career.teamtailor.localhost/jobs/407c2b91-f06e-475f-9e51-72a62091abce
Job apply url: https://career.teamtailor.localhost/jobs/407c2b91-f06e-475f-9e51-72a62091abce/applications/new?promotion=abc
Cover image url: https://teamtailor-production.s3.eu-west-1.amazonaws.com/image_uploads/cd24c21b-db10-4cf2-aabd-4a6f4ef1cf06/original.png
Price: 400 EUR

Locations:
    - country: Sweden
    - city: Stockholm
    - postalcode: 118 46
    - address: Sankt Paulsgatan 7B
    - region: Västra Götaland County


Recruiter data
--------------
- name: Hammes Grud
- email: email1@example.com
- phone: 123456

Department data:
--------------
- name: Marketing
- role name: Growth Marketing Manager

Company data
------------

Company name: Test company
Company description: Cupio barba articulus.</p><p>Spes deleniti cubicularis.
Company logotype: https://teamtailor-production.s3.eu-west-1.amazonaws.com/image_uploads/cd24c21b-db10-4cf2-aabd-4a6f4ef1cf06/original.png
Company headquarters:
    - country: Sweden
    - city: Stockholm
    - postalcode: 118 46
    - address: Sankt Paulsgatan 7B
    - countrycode: SE
    - region: Västra Götaland County


Promotion data
--------------

Title: Marketing Coordinator
Description: <p>Depereo decumbo defungo. Ubi stipes vel. Cupio barba articulus.</p><p>Spes deleniti cubicularis. Admitto aut contra. Aspernatur sperno cuppedia.</p><p>Vado concedo ager. 
      Usitas coaegresco autem. Suscipio thorax aurum.</p><p>Vero et veniam. Alioqui cometes apto. Truculenter tollo quos.</p><p>Decimus sunt sollers. Cotidie celo voluntarius. 
      Centum triduana deleo.</p><p>Denego quod dedico. Conservo bos illo. Molestiae valetudo avaritia.</p><h2>Recusandae placeat voluptates modi.</h2><p>Verto et absum. Culpa corroboro atrocitas.
      Clam apud voluptatibus.</p><p>Verbum verto sit. Coadunatio centum animi. Succedo adversus inventore.</p><p>Rem est uberrime. Voluptatem theologus inflammatio. Crastinus tergum civitas.</p><p>Deputo summopere eveniet. 
      Vulgus timidus nisi. Defaeco verto natus.</p><p>Quas colligo cresco. Praesentium colo chirographum. Torqueo celebrer concedo.</p><p>Compono statua vaco. Volo adsum veritatis. Aufero bene sursum.</p><p>Viriliter ratione venia. 
      Uter sit quia. Accommodo varietas socius.</p>
```

--------------------------------

### Example Teamtailor XML Job Feed

Source: https://partner.teamtailor.com/job_boards/index

This is an example of the XML feed provided by Teamtailor for job postings. It includes details about the publisher, company, job description, location, and custom fields. Note that the salary field is optional in this feed.

```xml
<source>
  <publisher>Teamtailor</publisher>
  <publisherurl>https://www.teamtailor.com</publisherurl>
  <lastupdatedat>
    <![CDATA[ 2021-03-23T10:50:08+01:00 ]]> 
  </lastupdatedat>
  <job>
    <company>
      <![CDATA[ Test company ]]> 
    </company>
    <companydescription>
      <![CDATA[ Cupio barba articulus.</p><p>Spes deleniti cubicularis. ]]> 
    </companydescription>
    <companyuuid>
      <![CDATA[ ZPXFT2VMtr8 ]]> 
    </companyuuid>
    <logotype>
      <![CDATA[ https://teamtailor-production.s3.eu-west-1.amazonaws.com/image_uploads/cd24c21b-db10-4cf2-aabd-4a6f4ef1cf06/original.png ]]> 
    </logotype>
    <headquarters>
      <country>
        <![CDATA[ Sweden ]]> 
      </country>
      <city>
        <![CDATA[ Stockholm ]]> 
      </city>
       <zip>
        <![CDATA[ 118 46 ]]> 
      </zip>
      <address>
        <![CDATA[ Sankt Paulsgatan 7B ]]> 
      </address>
      <countrycode>
        <![CDATA[ SE ]]> 
      </countrycode>
      <region>
        <![CDATA[ Västra Götaland County ]]> 
      </region>
    </headquarters>
    <referencenumber>
      <![CDATA[ teamtailor-23 ]]> 
    </referencenumber>
    <title>
      <![CDATA[ Marketing Coordinator ]]> 
    </title>
    <description>
      <![CDATA[ Depereo decumbo defungo. Ubi stipes vel. Cupio barba articulus. ]]> 
    </description>
    <startdate>
      <![CDATA[ 2021-03-24T00:00:00+01:00 ]]> 
    </startdate>
    <enddate>
      <![CDATA[ 2021-03-31T00:00:00+02:00 ]]> 
    </enddate>
    <createddate>
      <![CDATA[ 2021-03-02T19:18:22+01:00 ]]> 
    </createddate>
    <remotestatus>
      <![CDATA[ none ]]> 
    </remotestatus>
    <employmenttype>
      <![CDATA[ none ]]> 
    </employmenttype>
    <employmentlevel>
      <![CDATA[ none ]]> 
    </employmentlevel>
    <url>
      <![CDATA[ https://career.teamtailor.localhost/jobs/23-marketing-coordinator ]]> 
    </url>
    <applyurl>
      <![CDATA[ https://career.teamtailor.localhost/jobs/23-marketing-coordinator/applications/new ]]> 
    </applyurl>
    <coverimageurl>
      <![CDATA[ https://teamtailor-production.s3.eu-west-1.amazonaws.com/image_uploads/cd24c21b-db10-4cf2-aabd-4a6f4ef1cf06/original.png ]]> 
    </coverimageurl>
    <pitch>
      <![CDATA[ Coadunatio centum animi. Succedo adversus inventore. Rem est uberrime. ]]> 
    </pitch>
    <applybuttontext>
      <![CDATA[ Become a developer ]]> 
    </applybuttontext>
    <locations>
      <location>
        <country>
          <![CDATA[ Finland ]]> 
        </country>
        <city>
          <![CDATA[ Helsinki ]]> 
        </city>
        <zip>
          <![CDATA[ 00100 ]]> 
        </zip>
        <address>
          <![CDATA[ ]]> 
        </address>
        <countrycode>
          <![CDATA[ FI ]]> 
        </countrycode>
        <region>
          <![CDATA[ Västra Götaland County ]]> 
        </region>
      </location>
      <location>
        <country>
          <![CDATA[ Sweden ]]> 
        </country>
        <city>
          <![CDATA[ Stockholm ]]> 
        </city>
        <postalcode>
          <![CDATA[ 118 46 ]]> 
        </postalcode>
        <address>
          <![CDATA[ Sankt Paulsgatan 7B ]]> 
        </address>
        <countrycode>
          <![CDATA[ SE ]]> 
        </countrycode>
        <region>
          <![CDATA[ Västra Götaland County ]]> 
        </region>
      </location>
    </locations>
    <customfields>
      <customfield>
        <id>
          <![CDATA[ 3 ]]> 
        </id>
        <type>
          <![CDATA[ date ]]> 
        </type>
        <name>
          <![CDATA[ Customdate ]]> 
        </name>
        <value>
          <![CDATA[ 2023-06-14 ]]> 
        </value>
      </customfield>
      <customfield>
        <id>
          <![CDATA[ 4 ]]> 
        </id>
        <type>
          <![CDATA[ boolean ]]> 
        </type>
        <name>
          <![CDATA[ Custombool ]]> 
        </name>
        <value>
          <![CDATA[ true ]]> 
        </value>
      </customfield>
      <customfield>
        <id>
          <![CDATA[ 5 ]]> 
        </id>
        <type>
          <![CDATA[ multiselect ]]> 
        </type>
        <name>
          <![CDATA[ Custommultiselect ]]> 
        </name>
        <value>
          <![CDATA[ Multiselectoption1 ]]> 
        </value>
        <value>
          <![CDATA[ Multiselectoption2 ]]> 
        </value>
        <value>
          <![CDATA[ Multiselectoption3 ]]> 
        </value>
      </customfield>
    </customfields>
    <department>
      <name>
        <![CDATA[ Product Development ]]> 
      </name>
    </department>
    <role>
      <name>
        <![CDATA[ Developer ]]> 
      </name>
    </role>
    <recruiter>
      <name>
        <![CDATA[ Hammes Grud ]]> 
      </name>
      <email>
        <![CDATA[ email1@example.com ]]> 
      </email>
      <phone>
        <![CDATA[ 123456 ]]> 
      </phone>
    </recruiter>
  </job>
</source>
```

--------------------------------

### Update Promotion Request (HTTP)

Source: https://partner.teamtailor.com/job_boards/index

This example demonstrates how to update an existing promotion using an HTTP PUT request. It requires authentication via an Authorization token and specifies the API version. The request body contains the promotion data to be updated, including its ID and attributes.

```http
PUT https://api.teamtailor.localhost/channel/v1/promotions/1 HTTP/1.1
Authorization: Token abc123abc123
X-Api-Version: 20180828
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1",
    "type": "promotions",
    "attributes": {
      "external-url": "http://www.example.com"
    }
  }
}
```

--------------------------------

### API Authentication Example

Source: https://partner.teamtailor.com/job_boards/index

This snippet shows how to authenticate API requests to the Teamtailor API. It involves sending your secret API key in the Authorization header. Replace 'abc123abc123' with your actual API key obtained from the Integrations hub.

```http
PUT https://api.teamtailor.com/channel/v1/promotions/1 HTTP/1.1
Authorization: Token abc123abc123
```

--------------------------------

### GET /config

Source: https://partner.teamtailor.com/job_boards/index

Retrieves configuration options for a form used when publishing a job ad. This endpoint is used to populate the choices displayed to the user.

```APIDOC
## GET ${BASE_URL}/config

### Description
Retrieves configuration options for a form used when publishing a job ad. This endpoint is used to populate the choices displayed to the user.

### Method
GET

### Endpoint
${BASE_URL}/config

### Parameters
#### Query Parameters
- **page** (number) - Optional - The page number for which to retrieve configuration.
- **job_id** (number) - Optional - The ID of the job for which to retrieve configuration.

### Request Example
```
GET ${BASE_URL}/config?page=1&job_id=23&user_id=789 HTTP/1.1
```

### Response
#### Success Response (200)
- **config** (object) - Top-level object containing configuration fields for each page.
- **page** (number) - The current page number of the configuration.
- **hasNextPage** (boolean) - Indicates if there is another page of configuration available.

#### Response Example
```json
{
  "config": {
    "1": [
      {
        "id": "experience-level",
        "label": "Experience level",
        "placeholder": "Experience level",
        "type": "select",
        "options": [
          { "id": 1, "label": "Junior" },
          { "id": 2, "label": "Senior" }
        ]
      }
    ],
    "2": [
      {
        "id": "degree-level",
        "label": "Required degree level",
        "placeholder": "Choose degree level",
        "type": "select",
        "options": [
          { "id": 1, "label": "Bachelor's Degree" },
          { "id": 2, "label": "Master's Degree" }
        ]
      }
    ],
    "page": 1,
    "hasNextPage": true
  }
}
```

### Field Objects
- **id** (string) - Identifier for this field, will be sent in webhook.
- **label** (string) - Human-readable label for the field.
- **placeholder** (string) - Placeholder text for the input field.
- **type** (string) - Type of form element (e.g., 'select', 'text', 'number').
- **options** (array) - An array of available options for select-type fields.

### Supported Field Types
- checkbox
- color
- date
- datetime
- datetime-local
- email
- infobox
- hidden
- month
- number
- password
- radio
- range
- reset
- search
- select
- multiselect
- tel
- text
- url
- week

### Pagination
The API supports paginated configuration. Responses may include multiple `config` page objects, along with `page` and `hasNextPage` attributes. Query string parameters with selected option IDs and values will be included to make the form dependent on previous selections.
```

--------------------------------

### Enable Dynamic Activation Config

Source: https://partner.teamtailor.com/job_boards/index

This endpoint enables dynamic activation configuration. When enabled, Teamtailor will call your specified endpoint (`GET ${BASE_URL}/activation`) each time a user accesses your integration in the settings page to fetch configuration fields dynamically.

```APIDOC
## PUT /channel/v1/channels/{INTEGRATION_ID}

### Description
Enables dynamic activation configuration for a job board. When active, Teamtailor will call a specified endpoint to dynamically retrieve configuration fields.

### Method
PUT

### Endpoint
`https://api.teamtailor.com/channel/v1/channels/{INTEGRATION_ID}`

### Parameters
#### Path Parameters
- **INTEGRATION_ID** (integer) - Required - The ID of the integration to update.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **X-Api-Version** (string) - Required - API version, e.g., `20180828`.
- **Content-Type** (string) - Required - `application/vnd.api+json`

#### Request Body
- **data** (object) - Required - The payload for the channel update.
  - **id** (integer) - Required - The ID of the channel.
  - **type** (string) - Required - Must be `channels`.
  - **attributes** (object) - Required - Contains the attributes to update.
    - **dynamic-activation-config** (boolean) - Required - Set to `true` to enable dynamic activation.

### Request Example
```json
{
  "data": {
    "id": 99,
    "type":"channels",
    "attributes":{
      "dynamic-activation-config": true
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Details of the updated channel.

#### Response Example
(Response structure would typically mirror the request with updated status or confirmation)
```

--------------------------------

### Set Dynamic Activation Config on Teamtailor Job Board (API)

Source: https://partner.teamtailor.com/job_boards/index

This API call shows how to configure a Teamtailor channel for dynamic activation configuration. By setting the 'webhook-activation-config' attribute to an empty object, the system will call a specified endpoint (GET ${BASE_URL}/activation?company_id=xyz) each time a user accesses the integration settings page to fetch and render the configuration fields.

```http
PUT https://api.teamtailor.com/channel/v1/channels/{INTEGRATION_ID} HTTP/1.1
Authorization: Token abc123abc123
X-Api-Version: 20180828
Content-Type: application/vnd.api+json

{
  "data": {
    "id": 99,
    "type":"channels",
    "attributes":{
      "webhook-activation-config": {}
    }
  }
}


```

--------------------------------

### HTTP Webhooks - GET Config

Source: https://partner.teamtailor.com/job_boards/index

Retrieves the configuration for HTTP webhooks. This endpoint allows you to fetch the current settings related to webhook integrations.

```APIDOC
## GET /config/webhooks

### Description
Retrieves the configuration for HTTP webhooks. This endpoint allows you to fetch the current settings related to webhook integrations.

### Method
GET

### Endpoint
/config/webhooks

### Parameters

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **config** (object) - The webhook configuration details.

#### Response Example
```json
{
  "config": {
    "url": "https://example.com/webhook",
    "events": [
      "job.created",
      "job.updated"
    ]
  }
}
```
```

--------------------------------

### Validate Teamtailor Webhook Signature (Node.js)

Source: https://partner.teamtailor.com/job_boards/index

This Node.js example demonstrates how to validate the authenticity of incoming webhooks from Teamtailor. It uses the `crypto` module to compare the received signature with a locally computed HMAC. Ensure the `WEBHOOK_SECRET` environment variable is set with your job board API key. The implementation checks the timestamp and the HMAC signature to prevent replay attacks and ensure the webhook originates from Teamtailor.

```javascript
// Bundled with Node
const crypto = require('crypto');

// External dependencies
const express = require('express');
const bodyParser = require('body-parser');

// Webhook secret as environment variable
const SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhook', bodyParser.raw({type: 'application/json'}), (req, res) => {
  const signaturePattern = /^t=(\d+),v\d=(\w+),.+$/;
  const signature = req.headers['teamtailor-signature'];
  const [_, timestamp, cHmac] = signaturePattern.exec(signature);
  const payload = `${timestamp}.${payload}`;
  const hmac = crypto.createHmac('sha256', SECRET)
    .update(payload, 'utf-8')
    .digest('hex');
  if (cHmac === hmac) {
    // Signature check passed.
    // If you want to prevent replay attacks, check timestamp as well.
    return res.status(200).send();
  }
  return res.status(401).send();
})
```

--------------------------------

### Webhook Activation Configuration

Source: https://partner.teamtailor.com/job_boards/index

Provides the JSON structure for configuring webhook activation, including fields for client ID, client secret, and language selection.

```APIDOC
## Webhook Activation Configuration

### Description
This is the configuration object for webhook activation.

### Configuration JSON
```json
{
   "config":{
      "fields":[
         {
            "id":"clientId",
            "type":"text",
            "label":"Client ID",
            "required":true,
            "description":"Please insert the Client ID"
         },
         {
            "id":"clientSecret",
            "type":"password",
            "label":"Client SECRET",
            "required":true,
            "description":"Please insert the Client secret"
         },
         {
            "id":"language",
            "type":"select",
            "label":"Test Default language",
            "description":"Select the default test language",
            "options":[
               {
                  "id":"1",
                  "label":"English"
               },
               {
                  "id":"2",
                  "label":"French"
               }
            ]
         }
      ]
   }
}
```
```

--------------------------------

### Configure Dynamic Activation

Source: https://partner.teamtailor.com/job_boards/index

This endpoint configures the webhook for dynamic activation. By setting an empty object for `webhook-activation-config`, you signal that your endpoint should be called to render dynamic fields when the user visits the integration settings.

```APIDOC
## PUT /channel/v1/channels/{INTEGRATION_ID}

### Description
Configures the webhook for dynamic activation. An empty object for `webhook-activation-config` indicates that an external endpoint should be called to dynamically render configuration fields.

### Method
PUT

### Endpoint
`https://api.teamtailor.com/channel/v1/channels/{INTEGRATION_ID}`

### Parameters
#### Path Parameters
- **INTEGRATION_ID** (integer) - Required - The ID of the integration to update.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **X-Api-Version** (string) - Required - API version, e.g., `20180828`.
- **Content-Type** (string) - Required - `application/vnd.api+json`

#### Request Body
- **data** (object) - Required - The payload for the channel update.
  - **id** (integer) - Required - The ID of the channel.
  - **type** (string) - Required - Must be `channels`.
  - **attributes** (object) - Required - Contains the attributes to update.
    - **webhook-activation-config** (object) - Required - An empty object to enable dynamic configuration fetching from your endpoint.

### Request Example
```json
{
  "data": {
    "id": 99,
    "type":"channels",
    "attributes":{
      "webhook-activation-config": {}
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Details of the updated channel.

#### Response Example
(Response structure would typically mirror the request with updated status or confirmation)
```

--------------------------------

### Set Static Activation Config

Source: https://partner.teamtailor.com/job_boards/index

This endpoint allows you to set a static activation configuration for a job board. You can define fields that the user needs to fill in, marking them as required if necessary. The collected data will be used to generate a JSON web token.

```APIDOC
## PUT /channel/v1/channels/{INTEGRATION_ID}

### Description
Sets a static activation configuration on a job board. The user-provided field values are transformed into a JSON Web Token. Fields can be marked as required.

### Method
PUT

### Endpoint
`https://api.teamtailor.com/channel/v1/channels/{INTEGRATION_ID}`

### Parameters
#### Path Parameters
- **INTEGRATION_ID** (integer) - Required - The ID of the integration to update.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **X-Api-Version** (string) - Required - API version, e.g., `20180828`.
- **Content-Type** (string) - Required - `application/vnd.api+json`

#### Request Body
- **data** (object) - Required - The payload for the channel update.
  - **id** (integer) - Required - The ID of the channel.
  - **type** (string) - Required - Must be `channels`.
  - **attributes** (object) - Required - Contains the attributes to update.
    - **activation-config** (object) - Required - Configuration for static activation.
      - **config** (object) - Required - The actual configuration fields.
        - **fields** (array) - Required - An array of field objects.
          - **id** (string) - Required - Unique identifier for the field.
          - **type** (string) - Required - Type of the input field (e.g., `text`).
          - **label** (string) - Required - User-facing label for the field.
          - **required** (boolean) - Optional - Whether the field is mandatory.

### Request Example
```json
{
  "data": {
    "id": 99,
    "type":"channels",
    "attributes":{
      "activation-config": {
        "config": {
          "fields": [
            {
              "id":"token",
              "type":"text",
              "label":"Example Token",
              "required":true
            }
          ]
        }
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Details of the updated channel.

#### Response Example
(Response structure would typically mirror the request with updated status or confirmation)
```

--------------------------------

### Enable Dynamic Activation Config on Teamtailor Job Board (API)

Source: https://partner.teamtailor.com/job_boards/index

This API call enables the dynamic activation configuration for a Teamtailor channel. By setting the 'dynamic-activation-config' property to 'true' using a PUT request to the channel endpoint, the integration will utilize the dynamic configuration method previously set up.

```http
PUT https://api.teamtailor.com/channel/v1/channels/{INTEGRATION_ID} HTTP/1.1
Authorization: Token abc123abc123
X-Api-Version: 20180828
Content-Type: application/vnd.api+json

{
  "data": {
    "id": 99,
    "type":"channels",
    "attributes":{
      "dynamic-activation-config": true
    }
  }
}


```

--------------------------------

### Versioning

Source: https://partner.teamtailor.com/job_boards/index

Control API versioning by sending the X-Api-Version header with your requests.

```APIDOC
## Versioning

### Description
When backwards-incompatible changes are made to the API, new, dated versions are released. This allows you to specify which API version your request should use.

### Method
Any applicable HTTP method (e.g., GET, POST, PUT, DELETE)

### Endpoint
`https://api.teamtailor.com/channel/v1/*`

### Headers
- **X-Api-Version**: `20180828` (Replace with the desired API version. The current version is `20180828`)

### Request Example
```
PUT https://api.teamtailor.com/channel/v1/promotions/1 HTTP/1.1
X-Api-Version : 20180828
```

### Response
Successful API requests will include the `X-Api-Version` header in the response, indicating the API version used for that request.
```

--------------------------------

### Set Static Activation Config on Teamtailor Job Board (API)

Source: https://partner.teamtailor.com/job_boards/index

This API call demonstrates how to set a static activation configuration for a Teamtailor channel (job board). It uses a PUT request to update the channel with an activation-config containing a fields array. Each field can have properties like id, type, label, and a required flag. The values entered by the user for these fields will be converted into a JSON Web Token.

```http
PUT https://api.teamtailor.com/channel/v1/channels/{INTEGRATION_ID} HTTP/1.1
Authorization: Token abc123abc123
X-Api-Version: 20180828
Content-Type: application/vnd.api+json

{
  "data": {
    "id": 99,
    "type":"channels",
    "attributes":{
      "activation-config": {
        "config": {
          "fields": [
            {
              "id":"token",
              "type":"text",
              "label":"Example Token",
              "required":true
            },
          ]
        }
      }
    }
  }
}


```

--------------------------------

### Webhook Signatures - Checking Signatures

Source: https://partner.teamtailor.com/job_boards/index

Details on how to verify the authenticity of incoming webhooks using signature headers.

```APIDOC
## Webhook Signature Verification

### Description
To validate the authenticity of webhooks sent by Teamtailor, a `Teamtailor-Signature` header is included in each request. This header contains a timestamp and a signature (HMAC) that allows you to verify the request's origin using your job board API key as the secret token.

### Signature Structure
The `Teamtailor-Signature` header has the format: `t=<timestamp>,v<version>=<signature>,...`. The timestamp prevents replay attacks, and `v1` is the current valid signature scheme.

```
# Example signature
Teamtailor-Signature: t=1539756759, v1=2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae
```

### Checking Signatures
1. **Timestamp Validation**: Check that the timestamp is within a valid range (e.g., within the last five minutes). This range is determined by your implementation.
2. **Hash Verification**: Compute the hash using the formula `sha256(timestamp + "." + payload, secret_key)` and compare it with the signature provided in the `v1` or latest scheme in the `Teamtailor-Signature` header. If they match, the webhook is confirmed to be from Teamtailor.

### Example implementation (Node.js)
```javascript
// Bundled with Node
const crypto = require('crypto');

// External dependencies
const express = require('express');
const bodyParser = require('body-parser');

// Webhook secret as environment variable
const SECRET = process.env.WEBHOOK_SECRET;

const app = express();

app.post('/webhook', bodyParser.raw({type: 'application/json'}), (req, res) => {
  const signatureHeader = req.headers['teamtailor-signature'];
  if (!signatureHeader) {
    return res.status(400).send('Signature header missing');
  }

  const signatureParts = signatureHeader.split(',');
  let timestamp = null;
  let receivedHmac = null;

  for (const part of signatureParts) {
    if (part.startsWith('t=')) {
      timestamp = part.substring(2);
    } else if (part.startsWith('v1=')) {
      receivedHmac = part.substring(3);
    }
  }

  if (!timestamp || !receivedHmac) {
    return res.status(400).send('Invalid signature format');
  }

  // Optional: Timestamp validation (e.g., within 5 minutes)
  const currentTime = Math.floor(Date.now() / 1000);
  const fiveMinutesAgo = currentTime - 300;
  if (parseInt(timestamp, 10) < fiveMinutesAgo) {
    console.warn('Webhook timestamp is too old');
    // Depending on security policy, you might return 401 here or just log a warning
  }

  const payload = `${timestamp}.${req.body}`;
  const calculatedHmac = crypto.createHmac('sha256', SECRET)
    .update(payload, 'utf-8')
    .digest('hex');

  if (receivedHmac === calculatedHmac) {
    console.log('Webhook signature verified successfully.');
    // Process the webhook data
    return res.status(200).send('Webhook received');
  } else {
    console.error('Webhook signature verification failed.');
    return res.status(401).send('Invalid signature');
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Webhook server listening on port ${PORT}`);
});
```
```

--------------------------------

### HTTP Webhooks - POST Webhook

Source: https://partner.teamtailor.com/job_boards/index

Creates a new HTTP webhook subscription. This endpoint allows you to register a new URL to receive webhook events.

```APIDOC
## POST /webhooks

### Description
Creates a new HTTP webhook subscription. This endpoint allows you to register a new URL to receive webhook events.

### Method
POST

### Endpoint
/webhooks

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **url** (string) - Required - The URL to send webhook events to.
- **events** (array of strings) - Required - A list of events to subscribe to (e.g., `job.created`, `job.updated`).

### Request Example
```json
{
  "url": "https://your-job-board.com/api/webhooks",
  "events": [
    "job.created",
    "job.updated",
    "job.deleted"
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created webhook.
- **url** (string) - The registered webhook URL.
- **events** (array of strings) - The list of subscribed events.

#### Response Example
```json
{
  "id": "wh_abc123xyz",
  "url": "https://your-job-board.com/api/webhooks",
  "events": [
    "job.created",
    "job.updated",
    "job.deleted"
  ]
}
```
```

--------------------------------

### Authentication

Source: https://partner.teamtailor.com/job_boards/index

Authenticate API requests by including your secret API key in the Authorization header.

```APIDOC
## Authentication

### Description
Authenticate your account by including your secret API key in the request. You can find your API key in the Integrations hub inside the Teamtailor App.

### Method
Any applicable HTTP method (e.g., GET, POST, PUT, DELETE)

### Endpoint
`https://api.teamtailor.com/channel/v1/*`

### Headers
- **Authorization**: `Token abc123abc123` (Replace `abc123abc123` with your actual API key)

### Request Example
```
PUT https://api.teamtailor.com/channel/v1/promotions/1 HTTP/1.1
Authorization: Token abc123abc123
```

### Response
Successful requests will return the requested data. Failed requests due to authentication issues will typically return a 401 Unauthorized status code.
```

--------------------------------

### POST Webhook Request Structure

Source: https://partner.teamtailor.com/job_boards/index

This snippet shows the structure of the HTTP POST request sent to the webhook endpoint. It includes the endpoint URL and a sample JSON payload detailing the job, company, and location information.

```http
POST ${BASE_URL}/webhook HTTP/1.1

{
  "id": "04798257-51ff-42e4-aa56-61e75632f23b",
  "reference-id": "1",
  "created-at": "2021-03-24T00:00:00+01:00",
  "duration": 30,
  "job-board-id": "job_board",
  "webhook-data": {
    "experience-level": "Junior",
    "degree-level": "Master's Degree"
  },
  "location": {
    "address": "Sankt Paulsgatan 7B",
    "city": "Stockholm",
    "country": "Sweden",
    "country-code": "SE",
    "zip": "118 46"
  },
  "company": {
    "name": "Teamtailor",
    "company-info-about": "Cupio barba articulus.</p><p>Spes deleniti cubicularis.",
    "url": "https://career.teamtailor.localhost",
    "uuid": "ZPXFT2VMtr8",
    "subdomain": "career",
    "logotype": "https://example.com/original.jpg",
    "headquarters": {
      "address": "Sankt Paulsgatan 7B",
      "city": "Stockholm",
      "country": "Sweden",
      "country-code": "SE",
      "zip": "118 46"
    }
  },
  "job": {
    "title": "Marketing Coordinator",
    "body": "Depereo decumbo defungo. Ubi stipes vel. Cupio barba articulus.",
    "remote-status": "none",
    "employment-type": "none",
    "employment-level": "none",
    "url": "https://career.teamtailor.localhost/jobs/23-marketing-coordinator",
    "apply-url": "https://career.teamtailor.localhost/jobs/23-marketing-coordinator/applications/new?promotion=2-monster-finland",
    "cover-image-url": "https://example.com/original.jpg",
    "pitch": "Coadunatio centum animi. Succedo adversus inventore. Rem est uberrime.",
    "start-date": "2021-03-24T00:00:00+01:00",
    "end-date": "2021-03-31T00:00:00+02:00",
    "created-date": "2021-03-02T19:18:22+01:00",
    "apply-button-text": "Apply now",
    "department": {
      "name": "Business Marketing"
    },
    "role": {
      "name": "Marketer"
    },
    "recruiter": {
      "name": "Hammes Grud",
      "email": "email1@example.com",
      "phone": "123456"
    },
    "locations": [
      {
        "address": "Sankt Paulsgatan 7B",
        "city": "Stockholm",
        "country": "Sweden",
        "country-code": "SE",
        "zip": "118 46"
      },
      {
        "address": "Sankt Paulsgatan 7B",
        "city": "Stockholm",
        "country": "Sweden",
        "country-code": "SE",
        "zip": "118 46"
      }
    ],
    "salary": {
      "min-salary": "500.0",
      "max-salary": "800.0",
      "salary-currency": "EUR",
      "salary-time-unit": "monthly"
    },
    "custom-fields": [
      { "id": 3, "name": 'Custom date', "value": '2023-06-14' },
      { "id": 9, "name": 'Custom bool', "value": true },
      {
        "id": 8,
        "name": 'Custom multiselect',
        "value": [ 'Multiselect option 3', 'Multiselect option 1' ]
      },
      { "id": 7, "name": 'Custom select', "value": [ 'Option 2' ] },
      { "id": 6, "name": 'Custom number', "value": 44 },
      { "id": 5, "name": 'Custom string', "value": 'String' }
    ]
  }
}
```

--------------------------------

### POST /webhook

Source: https://partner.teamtailor.com/job_boards/index

Handles the creation of a new job ad in Teamtailor by receiving webhook notifications.

```APIDOC
## POST ${BASE_URL}/webhook

### Description
Handles the creation of a new job ad in Teamtailor by receiving webhook notifications containing the job ad data.

### Method
POST

### Endpoint
${BASE_URL}/webhook

### Parameters
#### Request Body
- **job_ad_data** (object) - Required - JSON object containing the details of the newly created job ad.

### Request Example
```json
{
  "event": "job.created",
  "data": {
    "id": "job123",
    "title": "Software Engineer",
    "description": "Develop amazing software."
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating successful processing of the webhook.

#### Response Example
```json
{
  "message": "Job ad created successfully"
}
```
```

--------------------------------

### Salary Object Attributes

Source: https://partner.teamtailor.com/job_boards/index

Details of the attributes available within a salary object.

```APIDOC
## Salary Object

### Description
Details the attributes of a salary associated with a job.

### Attributes
- **min-salary** (number) - Minimum salary for the job if range otherwise offered salary amount
- **max-salary** (number) - Maximum salary for the job
- **salary-currency** (string) - Salary currency
- **salary-time-unit** (string) - Salary time unit. One of: `monthly`, `hourly`, `yearly`, `daily`
```

--------------------------------

### Promotion Object Structure (JSON)

Source: https://partner.teamtailor.com/job_boards/index

This JSON object represents a promotion within the Teamtailor system. It includes an ID, type, links, and attributes such as the external URL for the job ad. This structure is fundamental for understanding promotion data.

```json
{
  "data": {
    "id": "1",
    "type": "promotions",
    "links": {
      "self": "https://api.teamtailor.localhost/channel/v1/promotions/1"
    },
    "attributes": {
      "external-url": "http://www.example.com"
    }
  }
}
```

--------------------------------

### Recruiter Object Attributes

Source: https://partner.teamtailor.com/job_boards/index

Details of the attributes available within a recruiter object.

```APIDOC
## Recruiter Object

### Description
Details the attributes of a recruiter associated with a job.

### Attributes
- **name** (string) - Recruiter name
- **email** (string) - Recruiter email
- **phone** (string) - Recruiter phone
```

--------------------------------

### Node.js Middleware for JWT Authentication

Source: https://partner.teamtailor.com/job_boards/index

This Node.js middleware authenticates incoming requests using a JWT token extracted from the Authorization header. It verifies the token against a predefined API key and attaches the decoded payload to the request object. If authentication fails, it handles configuration-related errors by returning a specific JSON response, otherwise, it passes the error to the next middleware.

```javascript
module.exports = async (req, res, next) => {
  const [JWTtoken] = req.headers.authorization.split('Bearer ');

  try {
    const decoded = JWT.verify(JWTtoken, TT_JOB_BOARD_API_KEY);
    req.auth = decoded;
    return next();
  } catch (error) {
    if (req.path.includes('config')) {
      return res.json({
        config: {
          fields: [
            {
              type: 'error',
              message: 'Wrong authorization token',
            },
          ],
        },
      });
    }
    return next(error);
  }
};

```

--------------------------------

### Promotions - Update Promotion

Source: https://partner.teamtailor.com/job_boards/index

Updates an existing promotion associated with a job ad. This allows for modification of promotion details.

```APIDOC
## PUT /promotions/{promotion_id}

### Description
Updates an existing promotion associated with a job ad. This allows for modification of promotion details.

### Method
PUT

### Endpoint
/promotions/{promotion_id}

### Parameters

#### Path Parameters
- **promotion_id** (string) - Required - The unique identifier of the promotion to update.

#### Query Parameters
None

#### Request Body
- **details** (object) - Optional - The updated promotion details.
  - **status** (string) - Optional - The new status of the promotion (e.g., 'active', 'inactive').

### Request Example
```json
{
  "details": {
    "status": "inactive"
  }
}
```

### Response
#### Success Response (200)
- **promotion** (object) - The updated promotion object.
  - **id** (string) - The promotion ID.
  - **job_id** (string) - The associated job ID.
  - **status** (string) - The current status of the promotion.

#### Response Example
```json
{
  "promotion": {
    "id": "promo_xyz789",
    "job_id": "job_abc123",
    "status": "inactive"
  }
}
```
```
Tokens:
Raw