Teamtailor API

https://docs.teamtailor.com/
Admin
The Teamtailor API allows developers to interact with the Teamtailor platform, enabling tasks like...
Tokens:3,492
Snippets:39
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### GET https://api.teamtailor.com/v1/jobs

Source: https://docs.teamtailor.com/

Example of an authenticated request to retrieve jobs.

```APIDOC
## GET https://api.teamtailor.com/v1/jobs

### Description
Retrieves a list of jobs. Authentication is performed by passing the API key in the Authorization header.

### Method
GET

### Endpoint
https://api.teamtailor.com/v1/jobs

### Parameters
#### Query Parameters
- **filter[department]** (string) - Optional - Filter jobs by department ID.
```

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

### Pagination Response Structure

Source: https://docs.teamtailor.com/

Example of the meta and links objects returned in a paginated list response.

```json
{
  "meta": {
    "record-count": 2,
    "page-count": 1
  },
  "links": {
    "prev": "https://api.teamtailor.com/v1/jobs?filter[department]=337&page[before]=NQ&page[size]=10&sort=id",
    "next": "https://api.teamtailor.com/v1/jobs?filter[department]=337&page[after]=Ng&page[size]=10&sort=id",
  }
}
```

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

### GET /v1/jobs

Source: https://docs.teamtailor.com/

Retrieves a paginated list of jobs from the Teamtailor API.

```APIDOC
## GET /v1/jobs

### Description
Retrieves a list of jobs with pagination support.

### Method
GET

### Endpoint
https://api.teamtailor.com/v1/jobs

### Parameters
#### Query Parameters
- **page[size]** (integer) - Optional - The number of jobs to return per page.
```

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

### GET https://api.teamtailor.com/v1/job-applications

Source: https://docs.teamtailor.com/

Retrieve a list of the most recent hired candidates by filtering job applications.

```APIDOC
## GET https://api.teamtailor.com/v1/job-applications

### Description
Get a list of the most recent hired candidates.

### Method
GET

### Endpoint
https://api.teamtailor.com/v1/job-applications?include=candidate&filter[stage-type]=hired&sort=-changed_stage_at

### Parameters
#### Query Parameters
- **include** (string) - Optional - Include candidate data for each hire.
- **filter[stage-type]** (string) - Optional - Filter job applications marked as hired.
- **sort** (string) - Optional - Sort applications by most recent added to current stage.
```

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

### GET https://api.teamtailor.com/v1/jobs

Source: https://docs.teamtailor.com/

Retrieve a list of published jobs, optionally including department and location details.

```APIDOC
## GET https://api.teamtailor.com/v1/jobs

### Description
Get a list of published jobs and include their departments and locations in one request.

### Method
GET

### Endpoint
https://api.teamtailor.com/v1/jobs?include=department,locations

### Parameters
#### Query Parameters
- **include** (string) - Optional - Comma separated list of relations to include in the response.
```

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

### Pagination

Source: https://docs.teamtailor.com/

Top-level API resources support bulk fetches with pagination. Use the 'links' and 'meta' keys in the response to navigate datasets.

```APIDOC
### Pagination Parameters

- **page[size]** (integer) - Optional - The number of resources per page. Default: 10, Max: 30.

### Response Structure

- **meta.record-count** (integer) - Total number of items in the collection.
- **meta.page-count** (integer) - Total number of pages.
- **links** (object) - Contains navigation links: first, last, prev, next.
```

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

### POST https://api.teamtailor.com/v1/candidates

Source: https://docs.teamtailor.com/

Create a new candidate resource with a To-Many relationship to existing locations.

```APIDOC
## POST https://api.teamtailor.com/v1/candidates

### Description
Create a `candidates` resource with a `To-Many` relationship to a `locations` resource set. The `location` resource must exist before this request.

### Method
POST

### Endpoint
https://api.teamtailor.com/v1/candidates

### Request Body
- **data** (object) - Required - The candidate resource data including attributes and relationships.
```

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

### Create candidate with To-Many location relationship

Source: https://docs.teamtailor.com/

Creates a new candidate resource with an established relationship to existing location resources. The location must exist prior to this request.

```http
POST https://api.teamtailor.com/v1/candidates HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20240404
{"data":{"type":"candidates","attributes":{"email":"jonas@example.com","pitch":"Lorem ipsum dolor sit amet, consectetur adipiscing elit.","last-name":"Jonas","first-name":"Brusman","merge":true},"relationships":{"locations":{"data":[{"id":"1","type":"locations"}]}}}}
```

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

### Create Job from Template

Source: https://docs.teamtailor.com/

Send a POST request to the jobs endpoint with a template-id to clone an existing job configuration. Payload values will override the template defaults.

```http
POST https://api.teamtailor.com/v1/jobs HTTP/1.1
Authorization: Token token=abc123abc123
Content-Type: application/json
{
    "data":
    {
        "type": "jobs",
        "attributes":
        {
            "title": "Account Manager",
            "pitch": "Become part of something great!",
            "body": "<p class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27; class=&#x27;preserveHtml&#x27;>hello</p>",
            "template-id": 3026014
        },
        "relationships":
        {
            "user":
            {
                "data":
                {
                    "id": 1479857,
                    "type": "users"
                }
            }
        }
    }
}
```

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

### Paginate a list of jobs via HTTP

Source: https://docs.teamtailor.com/

Retrieves the first page of jobs with a specified page size. Requires an API token for authorization and the X-Api-Version header.

```http
GET https://api.teamtailor.com/v1/jobs?page[size]=20 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20240404
```

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

### POST /v1/jobs

Source: https://docs.teamtailor.com/

Creates a new job from a template by providing the template ID and job attributes.

```APIDOC
## POST /v1/jobs

### Description
Creates a new job from a template. This copies all settings from the template, including triggers and application forms, while allowing overrides via the request payload.

### Method
POST

### Endpoint
https://api.teamtailor.com/v1/jobs

### Request Body
- **data** (object) - Required - The job data object
- **data.type** (string) - Required - Must be "jobs"
- **data.attributes** (object) - Required - Job attributes including title, pitch, body, and template-id
- **data.relationships** (object) - Required - User relationship data
```

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

### Set API Version

Source: https://docs.teamtailor.com/

Specify the API version using the X-Api-Version header. Use the current date to ensure access to the latest API features.

```http
GET https://api.teamtailor.com/v1/jobs?filter[department]=337 HTTP/1.1
X-Api-Version : 20240404
```

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

### List latest hired candidates

Source: https://docs.teamtailor.com/

Fetches recent job applications filtered by the 'hired' stage and sorted by the stage change timestamp.

```http
GET https://api.teamtailor.com/v1/job-applications?include=candidate&filter[stage-type]=hired&sort=-changed_stage_at HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20240404
```

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

### List published jobs with department and locations

Source: https://docs.teamtailor.com/

Retrieves a list of published jobs including their associated departments and locations using the include parameter.

```http
GET https://api.teamtailor.com/v1/jobs?include=department,locations HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20240404
```

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

### Embed Application Form via Iframe

Source: https://docs.teamtailor.com/

Use an iframe to display the application form on your website. Set the src attribute to the job's application URL and configure dimensions as needed.

```html
<iframe src="https://career.teamtailor.com/jobs/7199-new-title/applications/new?iframe=true" style="width: 100%; height: 800px" frameborder="0"></iframe>
```

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

### API Rate Limit Headers

Source: https://docs.teamtailor.com/

Headers returned by the API to indicate current usage and remaining capacity within the rate limit window.

```text
X-Rate-Limit-Limit
# The number of allowed requests in the current period
X-Rate-Limit-Remaining
# The number of remaining requests in the current period
X-Rate-Limit-Reset
# The number of seconds left in the current period
```

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

### Include Iframe Helper Script

Source: https://docs.teamtailor.com/

Add this script to the head section of your page to enable features like automatic iframe resizing.

```html
<script src="https://scripts.teamtailor-cdn.com/widgets/production/apply.js"></script>
```

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

### Authenticate API Requests

Source: https://docs.teamtailor.com/

Include the secret API key in the Authorization header to authenticate requests. Replace the placeholder token with your actual API key.

```http
GET https://api.teamtailor.com/v1/jobs HTTP/1.1
Authorization: Token token=abc123abc123
```

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

### Rate Limiting

Source: https://docs.teamtailor.com/

The API enforces a rate limit of 50 requests per 10 seconds. Exceeding this limit results in an HTTP 429 status code.

```APIDOC
### Rate Limit Headers

- **X-Rate-Limit-Limit**: The number of allowed requests in the current period.
- **X-Rate-Limit-Remaining**: The number of remaining requests in the current period.
- **X-Rate-Limit-Reset**: The number of seconds left in the current period.
```
Tokens:
Raw