NAV
HTTP cURL

Topics

Teamtailor API

The Teamtailor API is following the JSON API Specification.

If you have any question or feedback please contact us at support@teamtailor.com

Example use cases:

Authentication

GET https://api.teamtailor.com/v1/jobs HTTP/1.1
Authorization: Token token=abc123abc123
curl -X "GET" "https://api.teamtailor.com/v1/jobs" \
     -H "Authorization: Token token=abc123abc123"

Authenticate your account when using the API by including your secret API key in the request. Manage your API keys.

Autentication is performed by passing the api key in the Authorization header.

Permissions

Your api keys might have different scope and permissions.

Public

Has access to public data, basically all data that is publicly visible on your career site.

read

Can read all public data, for example jobs, departments, locations.

write

Can create new jobs.

read/write

Can do all above and update existing jobs.

Internal

Same as Public, but can also access internal, unlisted & archived jobs.

read

Can read all public & internal data, for example jobs, departments, locations.

write

Can create new jobs.

read/write

Can do all above and update existing jobs.

Admin

Has access to all resources.

read

Can read all data, for example candidates, jobs, users.

write

Can create new jobs, candidates and job applications.

read/write

Can do all above and update jobs, candidates and job applications.

Versioning

GET https://api.teamtailor.com/v1/jobs?filter%5Bdepartment%5D=337 HTTP/1.1
X-Api-Version : 20161108
curl -X "GET" "https://api.teamtailor.com/v1/jobs?filter%5Bdepartment%5D=337" \
     -H "X-Api-Version: 20161108"

When we make backwards-incompatible changes to the API, we release new, dated versions.

To set the API version on a specific request, send a X-Api-Version header. See the API changelog to see current and old versions.

Successful API requests will have the used API version in the response header X-Api-Version

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

The headers are already present in every response but contains static values. Please use common sense when making requests to the API until it returns real rate limit values.

Pagination

Example response

{
  "meta": {
    "record-count": 2,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/jobs?filter%5Bdepartment%5D=337&page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/jobs?filter%5Bdepartment%5D=337&page%5Bnumber%5D=1&page%5Bsize%5D=10"
  }
}

All top-level API resources have support for bulk fetches via “list” API methods.

The links key in the response contains the following links:

The meta key contains:

To paginate a list, use these parameters:

Examples

Here are some real world usage examples of the Teamtailor API.

Paginate a list

Get the second page of jobs, with 20 jobs per page.

GET https://api.teamtailor.com/v1/jobs?page%5Bsize%5D=20&page%5Bnumber%5D=2 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/jobs?page%5Bsize%5D=20&page%5Bnumber%5D=2" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Parameters used in this example

Parameter Value Description
page[size] 20 Get 20 jobs in the list.
page[number] 2 Get the second page of jobs.

List published jobs with their department and locations

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

GET https://api.teamtailor.com/v1/jobs?include=department,locations HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/jobs?include=department,locations" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Parameters used in this example

Parameter Value Description
include department,locations Comma separated list of relations to include in the response.

List latest hired candidates

Get a list of the most recent hired candidates

GET https://api.teamtailor.com/v1/job-applications?include=candidate&filter%5Bstage-type%5D=hired&sort=-changed_stage_at HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl "https://api.teamtailor.com/v1/job-applications?include=candidate&filter%5Bstage-type%5D=hired&sort=-changed_stage_at" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Parameters used in this example

Parameter Value Description
include candidate Since we’re fetching latest job applications, we must include the candidate if we wan’t more data about each hire.
filter[stage-type] hired Just list job applications marked as hired
sort -changed_stage_at Sort applications by most recent added to current (hired) stage

Create candidate with a To-Many location relationship

Create a candidates resource with a To-Many relationship to a locations resource set.

POST https://api.teamtailor.com/v1/candidates HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{"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"}]}}}}
     curl -X "POST" "https://api.teamtailor.com/v1/candidates" \
          -H "Content-Type: application/vnd.api+json" \
          -H "X-Api-Version: 20161108" \
          -H "Authorization: Token token=abc123abc123" \
          -d $'{
       "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"
                }
              ]
            }
        }
      }
     }'

Embed application form

Example iframe

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

Iframe helper script

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

To embed an application form on your website, create an <iframe> and set the src attribute to the job’s careersite-job-apply-iframe-url attribute.

Remember to set frameborder="0" and style="width: 100%; height: 800px".

To enable features such as auto-resize of the iframe, insert the helper script to the right in the <head> section of your page.

Changelog

Example request

GET https://api.teamtailor.com/v1/jobs HTTP/1.1
X-Api-Version : 20161108
curl -X "GET" "https://api.teamtailor.com/v1/jobs" \
     -H "X-Api-Version: 20161108"

2020-07-20 Non breaking update

2020-05-14 Non breaking update

2020-05-13 Non breaking update

2020-05-12 Non breaking update

2020-04-23 Non breaking update

2020-02-26 Non breaking update

2019-11-14 Non breaking update

2019-11-14 Non breaking update

2019-09-10 Non breaking update

2019-08-09 Non breaking update

2019-08-08 Non breaking update

2019-08-07 Non breaking update

2019-07-31 Non breaking update

2019-07-15 Non breaking update

2019-07-11 Non breaking update

2019-07-03 Non breaking update

2019-06-18 Non breaking update

2019-05-17 Non breaking update

2019-05-06 Non breaking update

2019-04-23 Non breaking update

2019-04-23 Non breaking update

2019-04-15 Non breaking update

2019-03-07 Non breaking update

2019-03-07 Non breaking update

2019-01-09 Non breaking update

2018-11-05 Non breaking update

2018-09-17 Non breaking update

2018-07-17 Non breaking update

2018-05-31 Non breaking update

2018-05-11 Non breaking update

2018-05-22 Non breaking update

2018-04-26 Non breaking update

2018-04-19 Non breaking update

2018-04-05 Non breaking update

2018-04-04 Non breaking update

2018-03-02 Non breaking update

2018-02-13 Non breaking update

2018-01-25 Non breaking update

2018-01-16 Non breaking update

2017-10-31 Non breaking update

2017-09-06 Non breaking update

2017-03-15 Non breaking update

2017-03-10 Non breaking update

2017-02-23 Non breaking update

2016-11-08 New version

Resources

Activities

Activity Object

{
  "id": "1",
  "type": "activities",
  "links": {
    "self": "https://api.teamtailor.com/v1/activities/1"
  },
  "attributes": {
    "code": "created",
    "created-at": "2019-07-25T16:14:04.289+02:00",
    "data": "{}"
  },
  "relationships": {
    "candidate": {
      "links": {
        "self": "https://api.teamtailor.com/v1/activities/1/relationships/candidate",
        "related": "https://api.teamtailor.com/v1/activities/1/candidate"
      }
    },
    "job": {
      "links": {
        "self": "https://api.teamtailor.com/v1/activities/1/relationships/job",
        "related": "https://api.teamtailor.com/v1/activities/1/job"
      }
    },
    "user": {
      "links": {
        "self": "https://api.teamtailor.com/v1/activities/1/relationships/user",
        "related": "https://api.teamtailor.com/v1/activities/1/user"
      }
    }
  }
}

Attributes

Attribute Type Description
code string Activity type
created-at date
data string Json string with activity data, like note text, todo value etc.

Relations

Relation Description
candidate Candidate which the activity concerns
job Job which the activity concerns
user User who creates the activity

List Activities

GET https://api.teamtailor.com/v1/activities HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/activities" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "1",
      "type": "activities",
      "links": {
        "self": "https://api.teamtailor.com/v1/activities/1"
      },
      "attributes": {
        "code": "created",
        "created-at": "2019-07-25T16:14:04.289+02:00",
        "data": "{}"
      },
      "relationships": {
        "candidate": {
          "links": {
            "self": "https://api.teamtailor.com/v1/activities/1/relationships/candidate",
            "related": "https://api.teamtailor.com/v1/activities/1/candidate"
          }
        },
        "job": {
          "links": {
            "self": "https://api.teamtailor.com/v1/activities/1/relationships/job",
            "related": "https://api.teamtailor.com/v1/activities/1/job"
          }
        },
        "user": {
          "links": {
            "self": "https://api.teamtailor.com/v1/activities/1/relationships/user",
            "related": "https://api.teamtailor.com/v1/activities/1/user"
          }
        }
      }
    },
    
  ],
  "meta": {
    "record-count": 20,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/activities?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "next": "https://api.teamtailor.com/v1/activities?page%5Bnumber%5D=2&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/activities?page%5Bnumber%5D=3&page%5Bsize%5D=10"
  }
}

Example parameters

Parameter Default Description
include null Comma separated list of relations to include in the response. For example candidate,job,user.
filter[candidate] null Filter by candidate.
filter[code] null Filter by code.
filter[job] null Filter by job.
filter[user] null Filter by user.
sort id Sort list by any of the activity attributes.

Show an Activity

GET https://api.teamtailor.com/v1/activities/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/activities/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "id": "1",
  "type": "activities",
  "links": {
    "self": "https://api.teamtailor.com/v1/activities/1"
  },
  "attributes": {
    "code": "created",
    "created-at": "2019-07-25T16:14:04.289+02:00",
    "data": "{}"
  },
  "relationships": {
    "candidate": {
      "links": {
        "self": "https://api.teamtailor.com/v1/activities/1/relationships/candidate",
        "related": "https://api.teamtailor.com/v1/activities/1/candidate"
      }
    },
    "job": {
      "links": {
        "self": "https://api.teamtailor.com/v1/activities/1/relationships/job",
        "related": "https://api.teamtailor.com/v1/activities/1/job"
      }
    },
    "user": {
      "links": {
        "self": "https://api.teamtailor.com/v1/activities/1/relationships/user",
        "related": "https://api.teamtailor.com/v1/activities/1/user"
      }
    }
  }
}

Answers

Answer Object

{
  "data": {
    "id": "1337",
    "type": "answers",
    "links": {
      "self": "https://api.teamtailor.com/v1/answers/1337"
    },
    "attributes": {
      "boolean": null,
      "choices": [
        3,
        4
      ],
      "updated-at": "2017-02-16T14:06:36.926+01:00",
      "range": null,
      "text": null,
      "video-token": null
    },
    "relationships": {
      "question": {
        "links": {
          "self": "https://api.teamtailor.com/v1/answers/1337/relationships/question",
          "related": "https://api.teamtailor.com/v1/answers/1337/question"
        }
      },
      "candidate": {
        "links": {
          "self": "https://api.teamtailor.com/v1/answers/1337/relationships/candidate",
          "related": "https://api.teamtailor.com/v1/answers/1337/candidate"
        }
      }
    }
  }
}

Attributes

Attribute Type Description
boolean boolean
choices array
updated-at date
range integer
text string
video-token string

Relations

The answer object always has a relation to a question and a candidate

Relation Description
question
candidate

List Answers

GET https://api.teamtailor.com/v1/answers HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/answers" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "1337",
      "type": "answers",
      "links": {
        "self": "https://api.teamtailor.com/v1/answers/1337"
      },
      "attributes": {
        "boolean": null,
        "choices": [],
        "updated-at": "2015-06-21T16:38:51.958+02:00",
        "range": null,
        "text": "Dear Sir/Madam…",
        "video-token": null
      },
      "relationships": {
        "question": {
          "links": {
            "self": "https://api.teamtailor.com/v1/answers/1337/relationships/question",
            "related": "https://api.teamtailor.com/v1/answers/1337/question"
          }
        },
        "candidate": {
          "links": {
            "self": "https://api.teamtailor.com/v1/answers/1337/relationships/candidate",
            "related": "https://api.teamtailor.com/v1/answers/1337/candidate"
          }
        }
      }
    },
    {
      "id": "1338",
      "type": "answers",
      "links": {
        "self": "https://api.teamtailor.com/v1/answers/1338"
      },
      "attributes": {
        "boolean": null,
        "choices": [],
        "updated-at": "2015-06-21T16:39:52.181+02:00",
        "range": null,
        "text": "To Whom It May Concern…",
        "video-token": null
      },
      "relationships": {
        "question": {
          "links": {
            "self": "https://api.teamtailor.com/v1/answers/1338/relationships/question",
            "related": "https://api.teamtailor.com/v1/answers/1338/question"
          }
        },
        "candidate": {
          "links": {
            "self": "https://api.teamtailor.com/v1/answers/1338/relationships/candidate",
            "related": "https://api.teamtailor.com/v1/answers/1338/candidate"
          }
        }
      }
    }
  ],
  "meta": {
    "record-count": 100,
    "page-count": 10
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/answers?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "next": "https://api.teamtailor.com/v1/answers?page%5Bnumber%5D=2&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/answers?page%5Bnumber%5D=10&page%5Bsize%5D=10"
  }
}

Use this endpoint to retrieve lists of answers.

Example parameters

Parameter Default Description
include null Comma separated list of relations to include in the response. For example candidate,question.

Show an Answer

GET https://api.teamtailor.com/v1/answers/1337 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/answers/1337" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "1337",
    "type": "answers",
    "links": {
      "self": "https://api.teamtailor.com/v1/answers/1337"
    },
    "attributes": {
      "boolean": null,
      "choices": [
        3,
        4
      ],
      "updated-at": "2017-02-16T14:06:36.926+01:00",
      "range": null,
      "text": null,
      "video-token": null
    },
    "relationships": {
      "question": {
        "links": {
          "self": "https://api.teamtailor.com/v1/answers/1337/relationships/question",
          "related": "https://api.teamtailor.com/v1/answers/1337/question"
        }
      },
      "candidate": {
        "links": {
          "self": "https://api.teamtailor.com/v1/answers/1337/relationships/candidate",
          "related": "https://api.teamtailor.com/v1/answers/1337/candidate"
        }
      }
    }
  }
}

Retreive a specific answer.

Parameter Description
id The answers id.

Create Answer

POST https://api.teamtailor.com/v1/answers HTTP/1.1
X-Api-Version: 20161108
Authorization: Token token=abc123abc123

{
  "data": {
    "type": "answers",
    "attributes": {
      "choices": [
        3,
        4
      ]
    },
    "relationships": {
      "candidate": {
        "data": {
          "id": "376226",
          "type": "candidates"
        }
      },
      "question": {
        "data": {
          "id": "6039",
          "type": "questions"
        }
      }
    }
  }
}
curl -X "POST" "https://api.teamtailor.com/v1/answers" \
     -H "Content-Type: application/vnd.api+json" \
     -H "X-Api-Version: 20161108" \
     -H "Authorization: Token token=abc123abc123" \
     -d $'{
  "data": {
    "type": "answers",
    "attributes": {
      "choices": [
        3,
        4
      ]
    },
    "relationships": {
      "candidate": {
        "data": {
          "id": "376226",
          "type": "candidates"
        }
      },
      "question": {
        "data": {
          "id": "6039",
          "type": "questions"
        }
      }
    }
  }
}'

Example response

{
  "data": {
    "id": "1337",
    "type": "answers",
    "links": {
      "self": "https://api.teamtailor.com/v1/answers/1337"
    },
    "attributes": {
      "boolean": null,
      "choices": [
        3,
        4
      ],
      "updated-at": "2017-02-16T14:06:36.926+01:00",
      "range": null,
      "text": null,
      "video-token": null
    },
    "relationships": {
      "question": {
        "links": {
          "self": "https://api.teamtailor.com/v1/answers/1337/relationships/question",
          "related": "https://api.teamtailor.com/v1/answers/1337/question"
        }
      },
      "candidate": {
        "links": {
          "self": "https://api.teamtailor.com/v1/answers/1337/relationships/candidate",
          "related": "https://api.teamtailor.com/v1/answers/1337/candidate"
        }
      }
    }
  }
}

Create a new Answer.

Audit Events

An Audit Event represents a record (one action) in the Audit Log

Audit Event Object

{
  "id": "1",
  "type": "audit-events",
  "links": {
    "self": "https://api.teamtailor.com/v1/audit-events/1"
  },
  "attributes": {
    "action": "bulk-delete",
    "actor-id": 4,
    "actor-label": "Kulas",
    "actor-type": "user",
    "description": "Deleting 1 candidates",
    "ip-address": "127.0.0.1",
    "source-id": 4,
    "source-label": "kulas@teamtailor.com",
    "source-type": "user",
    "timestamp": "2020-01-27T11:07:52.737+01:00"
  }
}

Attributes

Attribute Type Description
action string Action performed
actor-id integer Actor id
actor-label string Actor name
actor-type string Actor type
description string Description of the action
ip-address string IP where the event was triggered from
source-id integer Source id
source-label string Depends on source-type.
- candidate: name or email
- job: job title
- nurture-campaign: name
- user: email
- audit-log: null
source-type string audit-log / candidate / job / nurture-campaign / user
timestamp string Action datetime

List Audit Events

GET https://api.teamtailor.com/v1/audit-events HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/audit-events" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "1",
      "type": "audit-events",
      "links": {
        "self": "https://api.teamtailor.com/v1/audit-events/1"
      },
      "attributes": {
        "action": "bulk-delete",
        "actor-id": 4,
        "actor-label": "Kulas",
        "actor-type": "user",
        "description": "Deleting 1 candidates",
        "ip-address": "127.0.0.1",
        "source-id": "4",
        "source-label": "kulas@teamtailor.com",
        "source-type": "user",
        "timestamp": "2020-01-27T11:07:52.737+01:00"
      }
    }
  ],
  "meta": {
    "record-count": 10,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/audit-events?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/audit-events?page%5Bnumber%5D=1&page%5Bsize%5D=10"
  }
}

Use this endpoint to retrieve lists of audit events.

Show an Audit Event

GET https://api.teamtailor.com/v1/audit-event/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/audit-event/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "1",
    "type": "audit-events",
    "links": {
      "self": "https://api.teamtailor.com/v1/audit-events/1"
    },
    "attributes": {
      "action": "bulk-delete",
      "actor-id": 4,
      "actor-label": "Kulas",
      "actor-type": "user",
      "description": "Deleting 1 candidates",
      "ip-address": "127.0.0.1",
      "source-id": "4",
      "source-label": "kulas@teamtailor.com",
      "source-type": "user",
      "timestamp": "2020-01-27T11:07:52.737+01:00"
    }
  }
}

Use this endpoint to retrieve a specific audit event.

Candidates

A candidate is defined by a unqiue email adress. If a candidate don’t have any job-applications it can be either sourced or connected.

Candidate Object

{
  "data": {
    "id": "1337",
    "type": "candidates",
    "links": {
      "self": "https://api.teamtailor.com/v1/candidates/1337"
    },
    "attributes": {
      "connected": true,
      "created-at": "2017-01-18T21:04:56.178+01:00",
      "email": "john.doe@example.com",
      "facebook-id": null,
      "first-name": "John",
      "last-name": "Doe",
      "linkedin-uid": null,
      "linkedin-url": null,
      "phone": "0700000000",
      "picture": "https://image.jpg",
      "pitch": "I like turtles",
      "referring-site": "Facebook",
      "referring-url": "http://facebook.com/page",
      "referred": false,
      "resume": "https://s3.amazonaws.com/resume.pdf",
      "set-consent-expiration": true,
      "sourced": false,
      "unsubscribed": false,
      "updated-at": "2017-01-18T21:20:16.646+01:00",
      "facebook-profile": null,
      "linkedin-profile": null,
      "tags": []
    },
    "relationships": {
      "department": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/department",
          "related": "https://api.teamtailor.com/v1/candidates/1337/department"
        }
      },
      "role": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/role",
          "related": "https://api.teamtailor.com/v1/candidates/1337/role"
        }
      },
      "job-applications": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/job-applications",
          "related": "https://api.teamtailor.com/v1/candidates/1337/job-applications"
        }
      },
      "questions": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/questions",
          "related": "https://api.teamtailor.com/v1/candidates/1337/questions"
        }
      },
      "answers": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/answers",
          "related": "https://api.teamtailor.com/v1/candidates/1337/answers"
        }
      },
      "locations": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/locations",
          "related": "https://api.teamtailor.com/v1/candidates/1337/locations"
        }
      },
      "custom-field-values": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/custom-field-values",
          "related": "https://api.teamtailor.com/v1/candidates/1337/custom-field-values"
        }
      },
      "partner-results": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/partner-results",
          "related": "https://api.teamtailor.com/v1/candidates/1337/partner-results"
        }
      },
      "regions": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/regions",
          "related": "https://api.teamtailor.com/v1/candidates/1337/regions"
        }
      }
    }
  }
}

Attributes

Attribute Type Description
connected boolean
created-at date
email string Email to candidate. Always unique.
facebook-id string User id if connected with Facebook
facebook-profile string Read only, html version of Facebook profile
first-name string
last-name string
linkedin-profile string Read only, html version of LinkedIn profile
linkedin-uid string User id if connected with LinkedIn
linkedin-url string URL to LinkedIn profile
merge boolean Write only True if the attributes should be merged with an existing candidate, matched by email address.
phone string
picture string Url to candidate picture
pitch string 140 character pitch
referring-site string Read only, friendly name parsed from referring-url (i.e. Facebook, Indeed etc)
referring-url string
referred boolean Read only True if added by an employee.
resume string Signed URL to pdf-version of resume, valid for 30 seconds.
sourced boolean Read only True if added by a recruiter without applying
set-consent-expiration boolean Write only True if candidate have given their consent for you to store their personal details. Will set an expiration period according to your data retention settings.
tags array
unsubscribed boolean If true no new job notifications are sent
updated-at date
send-welcome-message boolean Create only, set to true if you want to send the “Welcome to connect” email to the candidate. Default: false

Relations

Relation Description
department
role
job-applications
questions
answers
locations
regions
uploads
custom-field-values
partner-results

List Candidates

GET https://api.teamtailor.com/v1/candidates HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/candidates" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "576",
      "type": "candidates",
      "links": {
        "self": "https://api.teamtailor.com/v1/candidates/576"
      },
      "attributes": {
        "connected": false,
        "created-at": "2015-04-22T19:39:32.902+02:00",
        "email": "candidate@example.com",
        "facebook-id": null,
        "first-name": "John",
        "last-name": "Doe",
        "linkedin-uid": null,
        "linkedin-url": null,
        "phone": "07000000000",
        "picture": null,
        "pitch": null,
        "referring-site": "Teamtailor",
        "referring-url": "http://www.teamtailor.com/sv",
        "referred": false,
        "resume": "https://www.s3.amazonaws.com/resumes/cv.pdf",
        "sourced": false,
        "unsubscribed": false,
        "updated-at": "2015-04-25T21:50:02.378+02:00",
        "facebook-profile": null,
        "linkedin-profile": null,
        "tags": []
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/candidates/576/relationships/department",
            "related": "https://api.teamtailor.com/v1/candidates/576/department"
          }
        },
        "role": {
          "links": {
            "self": "https://api.teamtailor.com/v1/candidates/576/relationships/role",
            "related": "https://api.teamtailor.com/v1/candidates/576/role"
          }
        },
        "job-applications": {
          "links": {
            "self": "https://api.teamtailor.com/v1/candidates/576/relationships/job-applications",
            "related": "https://api.teamtailor.com/v1/candidates/576/job-applications"
          }
        },
        "questions": {
          "links": {
            "self": "https://api.teamtailor.com/v1/candidates/576/relationships/questions",
            "related": "https://api.teamtailor.com/v1/candidates/576/questions"
          }
        },
        "answers": {
          "links": {
            "self": "https://api.teamtailor.com/v1/candidates/576/relationships/answers",
            "related": "https://api.teamtailor.com/v1/candidates/576/answers"
          },
          "data": []
        },
        "custom-field-values": {
          "links": {
            "self": "https://api.teamtailor.com/v1/candidates/576/relationships/custom-field-values",
            "related": "https://api.teamtailor.com/v1/candidates/576/custom-field-values"
          }
        },
        "partner-results": {
          "links": {
            "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/partner-results",
            "related": "https://api.teamtailor.com/v1/candidates/1337/partner-results"
          }
        },
        "regions": {
          "links": {
            "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/regions",
            "related": "https://api.teamtailor.com/v1/candidates/1337/regions"
          }
        }
      }
    },
    {
      "id": "1106",
      "type": "candidates",
      "links": {
        "self": "https://api.teamtailor.com/v1/candidates/1106"
      },
      "attributes": {
        "connected": false,
        "created-at": "2015-04-21T10:34:35.109+02:00",
        "email": "candidate@example.com",
        "facebook-id": null,
        "first-name": "John",
        "last-name": "Doe",
        "linkedin-uid": null,
        "linkedin-url": "https://www.linkedin.com/pub/johndoe",
        "phone": "",
        "picture": null,
        "pitch": null,
        "referring-site": "Indeed Sweden",
        "referring-url": "http://se.indeed.com/visajobb",
        "referred": false,
        "resume": null,
        "sourced": false,
        "unsubscribed": false,
        "updated-at": "2016-06-27T12:37:34.422+02:00",
        "facebook-profile": null,
        "linkedin-profile": "<h5 id=\"freelance-financial-journalist--editor-and-project-manager\">Developer</h5>\n\n<p>Sweden • Coding</p>\n\n",
        "tags": []
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/candidates/1106/relationships/department",
            "related": "https://api.teamtailor.com/v1/candidates/1106/department"
          }
        },
        "role": {
          "links": {
            "self": "https://api.teamtailor.com/v1/candidates/1106/relationships/role",
            "related": "https://api.teamtailor.com/v1/candidates/1106/role"
          }
        },
        "job-applications": {
          "links": {
            "self": "https://api.teamtailor.com/v1/candidates/1106/relationships/job-applications",
            "related": "https://api.teamtailor.com/v1/candidates/1106/job-applications"
          }
        },
        "questions": {
          "links": {
            "self": "https://api.teamtailor.com/v1/candidates/1106/relationships/questions",
            "related": "https://api.teamtailor.com/v1/candidates/1106/questions"
          }
        },
        "answers": {
          "links": {
            "self": "https://api.teamtailor.com/v1/candidates/1106/relationships/answers",
            "related": "https://api.teamtailor.com/v1/candidates/1106/answers"
          },
          "data": []
        },
        "custom-field-values": {
          "links": {
            "self": "https://api.teamtailor.com/v1/candidates/1106/relationships/custom-field-values",
            "related": "https://api.teamtailor.com/v1/candidates/1106/custom-field-values"
          }
        },
        "partner-results": {
          "links": {
            "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/partner-results",
            "related": "https://api.teamtailor.com/v1/candidates/1337/partner-results"
          }
        },
        "regions": {
          "links": {
            "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/regions",
            "related": "https://api.teamtailor.com/v1/candidates/1337/regions"
          }
        }
      }
    },
  ],
  "meta": {
    "record-count": 20,
    "page-count": 2
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/candidates",
    "next": "https://api.teamtailor.com/v1/candidates",
    "last": "https://api.teamtailor.com/v1/candidates"
  }
}

Use this endpoint to retrieve lists of candidates.

Example parameters

Parameter Default Description
include null Comma separated list of relations to include in the response. For example job-applications,department.
filter[email] null Filter by email address.
filter[department] null Filter by department.
filter[role] null Filter by role.
filter[locations] null Filter by locations.
filter[regions] null Filter by regions.
filter[email] null Filter by email address.
filter[connected] null true or false Filter candidates who has connected.
sort id Sort list by any of the candidate attributes. Use -id to sort by id descending.

Show a Candidate

GET https://api.teamtailor.com/v1/candidates/{id} HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/candidates/{id}" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "1337",
    "type": "candidates",
    "links": {
      "self": "https://api.teamtailor.com/v1/candidates/1337"
    },
    "attributes": {
      "connected": true,
      "created-at": "2017-01-18T21:04:56.178+01:00",
      "email": "john.doe@example.com",
      "facebook-id": null,
      "first-name": "John",
      "last-name": "Doe",
      "linkedin-uid": null,
      "linkedin-url": null,
      "phone": "0700000000",
      "picture": "https://image.jpg",
      "pitch": "I like turtles",
      "referring-site": "Facebook",
      "referring-url": "http://facebook.com/page",
      "referred": false,
      "resume": "https://s3.amazonaws.com/resume.pdf",
      "sourced": false,
      "unsubscribed": false,
      "updated-at": "2017-01-18T21:20:16.646+01:00",
      "facebook-profile": null,
      "linkedin-profile": null,
      "tags": []
    },
    "relationships": {
      "department": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/department",
          "related": "https://api.teamtailor.com/v1/candidates/1337/department"
        }
      },
      "role": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/role",
          "related": "https://api.teamtailor.com/v1/candidates/1337/role"
        }
      },
      "job-applications": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/job-applications",
          "related": "https://api.teamtailor.com/v1/candidates/1337/job-applications"
        }
      },
      "questions": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/questions",
          "related": "https://api.teamtailor.com/v1/candidates/1337/questions"
        }
      },
      "answers": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/answers",
          "related": "https://api.teamtailor.com/v1/candidates/1337/answers"
        }
      },
      "custom-field-values": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/custom-field-values",
          "related": "https://api.teamtailor.com/v1/candidates/1337/custom-field-values"
        }
      },
      "partner-results": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/partner-results",
          "related": "https://api.teamtailor.com/v1/candidates/1337/partner-results"
        }
      },
      "regions": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/regions",
          "related": "https://api.teamtailor.com/v1/candidates/1337/regions"
        }
      }
    }
  }
}

Retreive a specific candidate.

Parameter Description
id The candidate’s id.

Create candidate

POST https://api.teamtailor.com/v1/candidates HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{"data":{"type":"candidates","attributes":{"first-name":"Jonas","last-name":"Brusman","pitch":"Lorem ipsum dolor sit amet, consectetur adipiscing elit.","email":"jonas@example.com"}}}
     curl -X "POST" "https://api.teamtailor.com/v1/candidates" \
          -H "Content-Type: application/vnd.api+json" \
          -H "X-Api-Version: 20161108"
          -H "Authorization: Token token=abc123abc123" \
          -d $'{
       "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
         }
       }
     }'

Example response

{
  "data": {
    "id": "1337",
    "type": "candidates",
    "links": {
      "self": "https://api.teamtailor.com/v1/candidates/1337"
    },
    "attributes": {
      "connected": false,
      "created-at": "2017-02-16T15:44:07.150+01:00",
      "email": "jonas@example.com",
      "facebook-id": null,
      "first-name": "Jonas",
      "last-name": "Brusman",
      "linkedin-uid": null,
      "linkedin-url": null,
      "phone": null,
      "picture": null,
      "pitch": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "referring-site": null,
      "referring-url": null,
      "referred": false,
      "resume": null,
      "sourced": false,
      "set-consent-expiration": true,
      "unsubscribed": false,
      "updated-at": "2017-02-16T15:44:07.150+01:00",
      "facebook-profile": null,
      "linkedin-profile": null,
      "tags": []
    },
    "relationships": {
      "department": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/department",
          "related": "https://api.teamtailor.com/v1/candidates/1337/department"
        }
      },
      "role": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/role",
          "related": "https://api.teamtailor.com/v1/candidates/1337/role"
        }
      },
      "job-applications": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/job-applications",
          "related": "https://api.teamtailor.com/v1/candidates/1337/job-applications"
        }
      },
      "questions": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/questions",
          "related": "https://api.teamtailor.com/v1/candidates/1337/questions"
        }
      },
      "answers": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/answers",
          "related": "https://api.teamtailor.com/v1/candidates/1337/answers"
        }
      },
      "custom-field-values": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/custom-field-values",
          "related": "https://api.teamtailor.com/v1/candidates/1337/custom-field-values"
        }
      },
      "partner-results": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/partner-results",
          "related": "https://api.teamtailor.com/v1/candidates/1337/partner-results"
        }
      }
    }
  }
}

Use the merge attribute to merge the candidate attributes in case a candidate with a matching email address already exists.

Update Candidate

PATCH https://api.teamtailor.com/v1/candidates/1337 HTTP/1.1
X-Api-Version: 20161108
Authorization: Token token=abc123abc123

{
  "data": {
    "id": "1337",
    "attributes": {
      "first-name": "Update"
    },
    "type": "candidates"
  }
}
curl -X "PATCH" "https://api.teamtailor.com/v1/candidates/1337" \
    -H "Content-Type: application/vnd.api+json" \
    -H "X-Api-Version: 20161108"
    -H "Authorization: Token token=abc123abc123" \
    -d $'{ "data": { "id": "1337", "attributes": { "first-name": "David" }, "type": "candidates" } }'

Example response

{
  "data": {
    "id": "1337",
    "type": "candidates",
    "links": {
      "self": "https://api.teamtailor.com/v1/candidates/1337"
    },
    "attributes": {
      "connected": true,
      "created-at": "2017-01-18T21:04:56.178+01:00",
      "email": "john.doe@example.com",
      "facebook-id": null,
      "first-name": "David",
      "last-name": "Doe",
      "linkedin-uid": null,
      "linkedin-url": null,
      "phone": "0700000000",
      "picture": "https://image.jpg",
      "pitch": "I like turtles",
      "referring-site": "Facebook",
      "referring-url": "http://facebook.com/page",
      "referred": false,
      "resume": "https://s3.amazonaws.com/resume.pdf",
      "sourced": false,
      "unsubscribed": false,
      "updated-at": "2017-01-18T21:20:16.646+01:00",
      "facebook-profile": null,
      "linkedin-profile": null,
      "tags": []
    },
    "relationships": {
      "department": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/department",
          "related": "https://api.teamtailor.com/v1/candidates/1337/department"
        }
      },
      "role": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/role",
          "related": "https://api.teamtailor.com/v1/candidates/1337/role"
        }
      },
      "job-applications": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/job-applications",
          "related": "https://api.teamtailor.com/v1/candidates/1337/job-applications"
        }
      },
      "questions": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/questions",
          "related": "https://api.teamtailor.com/v1/candidates/1337/questions"
        }
      },
      "answers": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/answers",
          "related": "https://api.teamtailor.com/v1/candidates/1337/answers"
        }
      },
      "custom-field-values": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/custom-field-values",
          "related": "https://api.teamtailor.com/v1/candidates/1337/custom-field-values"
        }
      },
      "partner-results": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/partner-results",
          "related": "https://api.teamtailor.com/v1/candidates/1337/partner-results"
        }
      },
      "regions": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/regions",
          "related": "https://api.teamtailor.com/v1/candidates/1337/regions"
        }
      }
    }
  }
}

Change a candidates attributes/relationships.

Companies

This resource represents your account in Teamtailor. Each API key belongs to only one Company. Use the show endpoint to get the Company belonging to your API key.

Company Object

{
  "data": {
    "id": "FkZE7LWdUXo",
    "type": "companies",
    "links": {
      "self": "https://api.teamtailor.com/v1/companies/FkZE7LWdUXo"
    },
    "attributes": {
      "name": "Acme Corp",
      "locale": "en",
      "website": "https://www.acmecorp.com"
    },
    "relationships": {
      "manager": {
        "links": {
          "self": "https://api.teamtailor.com/v1/companies/FkZE7LWdUXo/relationships/manager",
          "related": "https://api.teamtailor.com/v1/companies/FkZE7LWdUXo/manager"
        }
      }
    }
  }
}

Attributes

Attribute Type Description
name string Company name
locale string Career site language. Possible values: ar, cs, da, de, en, es, et, fi, fil, fr, hu, it, ja, ko, lv, ms, nl, no, pl, pt, ro, ru, sv, th, tr, zh-CN
website string Company website URL

Relations

Relation Description
manager The Admin user who is assigned manager for this company. Used as default sender of some emails, and as fallback where a user is always needed.

Show your Company

GET https://api.teamtailor.com/v1/company HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/company" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "FkZE7LWdUXo",
    "type": "companies",
    "links": {
      "self": "https://api.teamtailor.com/v1/companies/FkZE7LWdUXo"
    },
    "attributes": {
      "name": "Acme Corp",
      "locale": "en",
      "website": "https://www.acmecorp.com"
    },
    "relationships": {
      "manager": {
        "links": {
          "self": "https://api.teamtailor.com/v1/companies/FkZE7LWdUXo/relationships/manager",
          "related": "https://api.teamtailor.com/v1/companies/FkZE7LWdUXo/manager"
        }
      }
    }
  }
}

Update Company

PATCH https://api.teamtailor.com/v1/company HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{
  "data": {
    "type": "companies",
    "id": "ZPXFT2VMtr8",
    "attributes": {
      "name": "Acme Corp"
    },
    "relationships": {
      "manager": {
      "data": {
        "type": "users",
        "id": 1801
      }
    }
  }
}
curl -X "PATCH" "https://api.teamtailor.com/v1/company" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
     -H "Content-Type: application/vnd.api+json" \
     -d "{\"data\":{\"id\":\"FkZE7LWdUXo\",\"attributes\":{\"name\":\"Acme Corp\"},\"type\":\"companies\",\"relationships\":{\"manager\":{\"data\":{\"type\":\"users\",\"id\":1801}}}}}"

Example response

{
  "data": {
    "id": "FkZE7LWdUXo",
    "type": "companies",
    "links": {
      "self": "https://api.teamtailor.com/v1/companies/FkZE7LWdUXo"
    },
    "attributes": {
      "name": "Acme Corp",
      "locale": "en",
      "website": "https://www.acmecorp.com"
    },
    "relationships": {
      "manager": {
        "links": {
          "self": "https://api.teamtailor.com/v1/companies/FkZE7LWdUXo/relationships/manager",
          "related": "https://api.teamtailor.com/v1/companies/FkZE7LWdUXo/manager"
        }
      }
    }
  }
}

Change a company’s attributes/relationships.

Custom field value

A custom field value represents the relationship between custom field and an owner (which - for now - is only a candidate). There are 5 types of custom field as specified by the field-type attribute.

Custom field value object

  {
    "data": {
      "id": "1",
      "type": "custom-field-values",
      "links": {
        "self": "https://api.teamtailor.com/v1/custom-field-values/1"
      },
      "attributes": {
        "field-type": "CustomField::Date",
        "value": "2019-08-28"
      },
      "relationships": {
        "custom-field": {
          "links": {
            "self": "https://api.teamtailor.com/v1/custom-field-values/1/relationships/custom-field",
            "related": "https://api.teamtailor.com/v1/custom-field-values/1/custom-field"
          }
        },
        "owner": {
          "links": {
            "self": "https://api.teamtailor.com/v1/custom-field-values/1/relationships/owner",
            "related": "https://api.teamtailor.com/v1/custom-field-values/1/owner"
          }
        }
      }
    }
  }

Attributes

Attribute Type Description
value string Mandatory. Depending on the type, format may change. Check the available types above
field-type string Read only. Tells of which type the custom-field-value is.

Relations

Relation Description
custom_field Mandatory. The custom field related to this resource.
owner Mandatory. Owner of the polymorphic relation. For now, the only acceptable owner is “candidate”

List Custom Field Value

GET https://api.teamtailor.com/v1/custom-field-values HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/custom-field-values" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "1",
      "type": "custom-field-values",
      "links": {
        "self": "https://api.teamtailor.com/v1/custom-field-values/1"
      },
      "attributes": {
        "field-type": "CustomField::Date",
        "value": "2019-08-28"
      },
      "relationships": {
        "custom-field": {
          "links": {
            "self": "https://api.teamtailor.com/v1/custom-field-values/1/relationships/custom-field",
            "related": "https://api.teamtailor.com/v1/custom-field-values/1/custom-field"
          }
        },
        "owner": {
          "links": {
            "self": "https://api.teamtailor.com/v1/custom-field-values/1/relationships/owner",
            "related": "https://api.teamtailor.com/v1/custom-field-values/1/owner"
          }
        }
      }
    },
    {
      "id": "2",
      "type": "custom-field-values",
      "links": {
        "self": "https://api.teamtailor.com/v1/custom-field-values/2"
      },
      "attributes": {
        "field-type": "CustomField::Date",
        "value": "2019-08-28"
      },
      "relationships": {
        "custom-field": {
          "links": {
            "self": "https://api.teamtailor.com/v1/custom-field-values/2/relationships/custom-field",
            "related": "https://api.teamtailor.com/v1/custom-field-values/1/custom-field"
          }
        },
        "owner": {
          "links": {
            "self": "https://api.teamtailor.com/v1/custom-field-values/2/relationships/owner",
            "related": "https://api.teamtailor.com/v1/custom-field-values/1/owner"
          }
        }
      }
    }
  ],
  "meta": {
    "record-count": 2,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/custom-field-values?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/custom-field-values?page%5Bnumber%5D=1&page%5Bsize%5D=10"
  }
}

Use this endpoint to retrieve lists of custom fields.

Example parameters

Parameter Description
filter[field-type] Available values: CustomField::Text, CustomField::Email , CustomField::Url , CustomField::Phone, CustomField::Date, CustomField::Checkbox

Show a Custom Field Value

GET https://api.teamtailor.com/v1/custom-field-values/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/custom-field-values/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "1",
    "type": "custom-field-values",
    "links": {
      "self": "https://api.teamtailor.com/v1/custom-field-values/1"
    },
    "attributes": {
      "field-type": "CustomField::Date",
      "value": "2019-08-28"
    },
    "relationships": {
      "custom-field": {
        "links": {
          "self": "https://api.teamtailor.com/v1/custom-field-values/1/relationships/custom-field",
          "related": "https://api.teamtailor.com/v1/custom-field-values/1/custom-field"
        }
      },
      "owner": {
        "links": {
          "self": "https://api.teamtailor.com/v1/custom-field-values/1/relationships/owner",
          "related": "https://api.teamtailor.com/v1/custom-field-values/1/owner"
        }
      }
    }
  }
}

Create Custom Field Value

POST https://api.teamtailor.com/v1/custom-field-values HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{
  "data": {
    "type": "custom-field-values",
    "attributes": {
      "value": "2019-08-28T18:56:53+02:00",
    },
    "relationships": {
      "custom-field": {
        "data": {
          "id": 4,
          "type": "custom-fields",
        },
      },
      "owner": {
        "data": {
          "id": 3,
          "type": "candidates",
        },
      },
    },
  },
}
curl -X "POST" "https://api.teamtailor.com/v1/custom-field-values" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
     -H "Content-Type: application/vnd.api+json" \
     -d '{
   "data": {
     "type": "custom-field-values",
     "attributes": {
       "value": "2019-08-28T18:56:53+02:00",
     },
     "relationships": {
       "custom-field": {
         "data": {
           "id": 4,
           "type": "custom-fields",
         },
       },
       "owner": {
         "data": {
           "id": 1,
           "type": "candidates",
         },
       },
     },
   },
}'

Example response

{
  "data": {
    "id": "1",
    "type": "custom-field-values",
    "links": {
      "self": "https://api.teamtailor.com/v1/custom-field-values/1"
    },
    "attributes": {
      "field-type": "CustomField::Date",
      "value": "2019-08-28T14:11:34+02:00"
    },
    "relationships": {
      "custom-field": {
        "links": {
          "self": "https://api.teamtailor.com/v1/custom-field-values/1/relationships/custom-field",
          "related": "https://api.teamtailor.com/v1/custom-field-values/1/custom-field"
        }
      },
      "owner": {
        "links": {
          "self": "https://api.teamtailor.com/v1/custom-field-values/1/relationships/owner",
          "related": "https://api.teamtailor.com/v1/custom-field-values/1/owner"
        }
      }
    }
  }
}

Create a new custom field value.

Update Custom Field Value

PATCH https://api.teamtailor.com/v1/custom-field-values/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

"data": {
  "id": 1,
  "type": "custom-field-values",
  "attributes": {
    "value": "2019-08-28",
  },
  "relationships": {
    "custom-field": {
      "data": {
        "id": 1,
        "type": "custom-fields",
      },
    },
    "owner": {
      "data": {
        "id": 1,
        "type": "candidates",
      },
    },
  },
},
curl -X "PATCH" "https://api.teamtailor.com/v1/custom-field-values/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
     -H "Content-Type: application/vnd.api+json" \
     -d '{
   "data": {
     "id": 1,
     "type": "custom-field-values",
     "attributes": {
       "value": "2019-08-28T",
     },
     "relationships": {
       "custom-field": {
         "data": {
           "id": 4,
           "type": "custom-fields",
         },
       },
       "owner": {
         "data": {
           "id": 1,
           "type": "candidates",
         },
       },
     },
   },
}'

Example response

{
  "data": {
    "id": "1",
    "type": "custom-field-values",
    "links": {
      "self": "https://api.teamtailor.com/v1/custom-field-values/1"
    },
    "attributes": {
      "field-type": "CustomField::Date",
      "value": "2019-08-28"
    },
    "relationships": {
      "custom-field": {
        "links": {
          "self": "https://api.teamtailor.com/v1/custom-field-values/1/relationships/custom-field",
          "related": "https://api.teamtailor.com/v1/custom-field-values/1/custom-field"
        }
      },
      "owner": {
        "links": {
          "self": "https://api.teamtailor.com/v1/custom-field-values/1/relationships/owner",
          "related": "https://api.teamtailor.com/v1/custom-field-values/1/owner"
        }
      }
    }
  }
}

Custom fields

There are 5 types of custom field as specified by the field-type attribute.

Custom field object

  {
    "data": {
      "id": "1",
      "type": "custom-fields",
      "links": {
        "self": "https://api.teamtailor.com/v1/custom-fields/1"
      },
      "attributes": {
        "name": "Additional email",
        "api-name": "additional-email",
        "field-type": "CustomField::Email",
        "created-at": "2019-09-02T15:35:50.311+02:00",
        "updated-at": "2019-09-02T15:35:50.311+02:00"
      },
      "relationships": {
        "custom-field-values": {
          "links": {
            "self": "https://api.teamtailor.com/v1/custom-fields/1/relationships/custom-field-values",
            "related": "https://api.teamtailor.com/v1/custom-fields/1/custom-field-values"
          }
        }
      }
    }
  }

Attributes

Attribute Type Description
name string Mandatory. Name of the custom field.
api-name string A lowercase, sanitized version of the name. Useful to use in combination with the Webhook Partner API. Optional, but will be set to the sanitized version of the name.
field-type string Mandatory. To see available types see description above.

Show a Custom Field

GET https://api.teamtailor.com/v1/custom-fields/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/custom-fields/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

  {
    "data": {
      "id": "1",
      "type": "custom-fields",
      "links": {
        "self": "https://api.teamtailor.com/v1/custom-fields/1"
      },
      "attributes": {
        "name": "Additional email",
        "api-name": "additional-email",
        "field-type": "CustomField::Email",
        "created-at": "2019-09-02T15:35:50.311+02:00",
        "updated-at": "2019-09-02T15:35:50.311+02:00"
      },
      "relationships": {
        "custom-field-values": {
          "links": {
            "self": "https://api.teamtailor.com/v1/custom-fields/1/relationships/custom-field-values",
            "related": "https://api.teamtailor.com/v1/custom-fields/1/custom-field-values"
          }
        }
      }
    }
  }

Retreive a specific custom field.

Parameter Description
id Custom field id.

List Custom Fields

GET https://api.teamtailor.com/v1/custom-fields HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/custom-fields" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

  {
    "data": [
      {
        "id": "1",
        "type": "custom-fields",
        "links": {
          "self": "https://api.teamtailor.com/v1/custom-fields/1"
        },
        "attributes": {
          "name": "Birthday",
          "api-name": "birthday",
          "field-type": "CustomField::Date",
          "created-at": "2019-09-02T15:35:59.518+02:00",
          "updated-at": "2019-09-02T15:35:59.518+02:00"
        },
        "relationships": {
          "custom-field-values": {
            "links": {
              "self": "https://api.teamtailor.com/v1/custom-fields/1/relationships/custom-field-values",
              "related": "https://api.teamtailor.com/v1/custom-fields/1/custom-field-values"
            }
          }
        }
      },
      {
        "id": "2",
        "type": "custom-fields",
        "links": {
          "self": "https://api.teamtailor.com/v1/custom-fields/2"
        },
        "attributes": {
          "name": "home phone",
          "api-name": "home-phone",
          "field-type": "CustomField::Phone",
          "created-at": "2019-09-02T15:35:59.518+02:00",
          "updated-at": "2019-09-02T15:35:59.518+02:00"
        },
        "relationships": {
          "custom-field-values": {
            "links": {
              "self": "https://api.teamtailor.com/v1/custom-fields/2/relationships/custom-field-values",
              "related": "https://api.teamtailor.com/v1/custom-fields/2/custom-field-values"
            }
          }
        }
      }
  ],
  "meta": {
    "record-count": 2,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/custom-fields?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/custom-fields?page%5Bnumber%5D=1&page%5Bsize%5D=10"
  }
}

Create Custom Field

POST https://api.teamtailor.com/v1/custom-fields HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{
  "data": {
    "type": "custom-fields",
    "attributes": {
      "name": "Home phone",
      "field-type": "CustomField::Phone"
    }
  }
}
curl -X "POST" "https://api.teamtailor.com/v1/custom-fields" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
     -H "Content-Type: application/vnd.api+json" \
     -d '{
       {
         "data": {
           "type": "custom-fields",
           "attributes": {
             "name": "Home phone",
             "field-type": "CustomField::Phone"
           }
         }
       }
}'

Example response

{
  "data": {
    "id": "23",
    "type": "custom-fields",
    "links": {
      "self": "https://api.teamtailor.com/v1/custom-fields/23"
    },
    "attributes": {
      "name": "Home phone",
      "api-name": "home-phone",
      "field-type": "CustomField::Phone",
      "created-at": "2019-09-04T12:49:06.076+02:00",
      "updated-at": "2019-09-04T12:49:06.076+02:00"
    },
    "relationships": {
      "custom-field-values": {
        "links": {
          "self": "https://api.teamtailor.com/v1/custom-fields/23/relationships/custom-field-values",
          "related": "https://api.teamtailor.com/v1/custom-fields/23/custom-field-values"
        }
      },
      "owner": {
        "links": {
          "self": "https://api.teamtailor.com/v1/custom-fields/23/relationships/owner",
          "related": "https://api.teamtailor.com/v1/custom-fields/23/owner"
        }
      }
    }
  }
}

Create a new custom field.

Update Custom Field

PATCH https://api.teamtailor.com/v1/custom-field-values/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{
  "data": {
    "id": 1,
    "type": "custom-fields",
    "attributes": {
      "name": "Updated name",
  }
},
curl -X "PATCH" "https://api.teamtailor.com/v1/custom-field-values/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
     -H "Content-Type: application/vnd.api+json" \
     -d '{
   "data": {
     "id": 1,
     "type": "custom-fields",
     "attributes": {
       "name": "Updated name"
     }
   }
}'

Example response

{
  "data": {
    "id": "1",
    "type": "custom-fields",
    "links": {
      "self": "https://api.teamtailor.com/v1/custom-fields/1"
    },
    "attributes": {
      "field-type": "CustomField::Date",
      "name": "Updated name",
      "api-name": "updated-name",
      "created-at": "2019-09-05T10:12:02.899+02:00",
      "updated-at": "2019-09-05T11:03:58.209+02:00"
    },
    "relationships": {
      "custom-field-values": {
        "links": {
          "self": "https://api.teamtailor.com/v1/custom-fields/1/relationships/custom-field-values",
          "related": "https://api.teamtailor.com/v1/custom-fields/1/custom-field-values"
        }
      }
    }
  }
}

Departments

Department Object

{
  "data": {
    "id": "337",
    "type": "departments",
    "links": {
      "self": "https://api.teamtailor.com/v1/departments/337"
    },
    "attributes": {
      "name": "Product Developments",
      "people-headline": "hello people",
      "people-text": "<p>this is us</p>",
      "row-order": -4194303,
      "headline": "Building the future.",
      "text": "We know how to build great products. We have built products used by over 5000 companies in the nordics. We are a small team of senior and junior product builders. We live and breath Ruby on rails. We are always looking for smart & fun people so don't be a stranger. Contact us today.",
      "pictures": [
        {
          "standard": "https://res.cloudinary.com/teamtailor-development/image/upload/c_fill,f_auto,g_faces:center,h_465,q_80,w_930/v1422365162/f3kp2yz3wickhtqrb50s.jpg"
        }
      ]
    },
    "relationships": {
      "roles": {
        "links": {
          "self": "https://api.teamtailor.com/v1/departments/337/relationships/roles",
          "related": "https://api.teamtailor.com/v1/departments/337/roles"
        }
      },
      "teams": {
        "links": {
          "self": "https://api.teamtailor.com/v1/departments/337/relationships/teams",
          "related": "https://api.teamtailor.com/v1/departments/337/teams"
        }
      }
    }
  }
}

Attributes

Attribute Type Description
name string The departmen’s name
people-headline string Headline for the people block
people-text string Text for the people block
row-order integer Value used for sorting, lowest first.
headline string Description headline
text string Description text
pictures object Array of pictures

Relations

Relation Description
roles The department’s roles
teams The teams this department is part of

List departments

GET https://api.teamtailor.com/v1/departments HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/departments" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "337",
      "type": "departments",
      "links": {
        "self": "https://api.teamtailor.com/v1/departments/337"
      },
      "attributes": {
        "name": "Product Developments",
        "people-headline": "hello people",
        "people-text": "<p>this is us</p>",
        "row-order": -4194303,
        "headline": "Building the future.",
        "text": "We know how to build great products. We have built products used by over 5000 companies in the nordics. We are a small team of senior and junior product builders. We live and breath Ruby on rails. We are always looking for smart & fun people so don't be a stranger. Contact us today.",
        "pictures": [
          {
            "standard": "https://res.cloudinary.com/teamtailor-development/image/upload/c_fill,f_auto,g_faces:center,h_465,q_80,w_930/v1422365162/f3kp2yz3wickhtqrb50s.jpg"
          }
        ]
      },
      "relationships": {
        "roles": {
          "links": {
            "self": "https://api.teamtailor.com/v1/departments/337/relationships/roles",
            "related": "https://api.teamtailor.com/v1/departments/337/roles"
          }
        },
        "teams": {
          "links": {
            "self": "https://api.teamtailor.com/v1/departments/337/relationships/teams",
            "related": "https://api.teamtailor.com/v1/departments/337/teams"
          }
        }
      }
    },
    {
      "id": "338",
      "type": "departments",
      "links": {
        "self": "https://api.teamtailor.com/v1/departments/338"
      },
      "attributes": {
        "name": "Sales and stuff",
        "people-headline": "",
        "people-text": "",
        "row-order": 1572865,
        "headline": "Users, users & users.",
        "text": "Our objective is to identify and convert HR/Marketing professionals to become Teamtailor users. The good thing is that we know we are selling a great product, makes our jobs fun. We don't believe in sell as hell at all cost. Its about educating our users and once they understand the power of the webb/social media they want to become users. Join us.",
        "pictures": [
          {
            "standard": "https://res.cloudinary.com/teamtailor-development/image/upload/c_fill,f_auto,g_faces:center,h_465,q_80,w_930/v1422369190/mqv02tchequezical6ue.jpg"
          }
        ]
      },
      "relationships": {
        "roles": {
          "links": {
            "self": "https://api.teamtailor.com/v1/departments/338/relationships/roles",
            "related": "https://api.teamtailor.com/v1/departments/338/roles"
          }
        },
        "teams": {
          "links": {
            "self": "https://api.teamtailor.com/v1/departments/338/relationships/teams",
            "related": "https://api.teamtailor.com/v1/departments/338/teams"
          }
        }
      }
    }
  ],
  "meta": {
    "record-count": 2,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/departments?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/departments?page%5Bnumber%5D=1&page%5Bsize%5D=10"
  }
}

Show a Department

GET https://api.teamtailor.com/v1/departments/337 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/departments/337" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "337",
    "type": "departments",
    "links": {
      "self": "https://api.teamtailor.com/v1/departments/337"
    },
    "attributes": {
      "name": "Product Developments",
      "people-headline": "hello people",
      "people-text": "<p>this is us</p>",
      "row-order": -4194303,
      "headline": "Building the future.",
      "text": "We know how to build great products. We have built products used by over 5000 companies in the nordics. We are a small team of senior and junior product builders. We live and breath Ruby on rails. We are always looking for smart & fun people so don't be a stranger. Contact us today.",
      "pictures": [
        {
          "standard": "https://res.cloudinary.com/teamtailor-development/image/upload/c_fill,f_auto,g_faces:center,h_465,q_80,w_930/v1422365162/f3kp2yz3wickhtqrb50s.jpg"
        }
      ]
    },
    "relationships": {
      "roles": {
        "links": {
          "self": "https://api.teamtailor.com/v1/departments/337/relationships/roles",
          "related": "https://api.teamtailor.com/v1/departments/337/roles"
        }
      },
      "teams": {
        "links": {
          "self": "https://api.teamtailor.com/v1/departments/337/relationships/teams",
          "related": "https://api.teamtailor.com/v1/departments/337/teams"
        }
      }
    }
  }
}

Create departments

POST https://api.teamtailor.com/v1/departments HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{"data":{"type":"departments","attributes":{"name":"Product","headline":"Product Development"}}}

Example response

{
  "data": {
    "id": "5",
    "type": "departments",
    "links": {
      "self": "https://api.teamtailor.com/v1/departments/5"
    },
    "attributes": {
      "name": "Product",
      "people-headline": null,
      "people-text": null,
      "row-order": 7864320,
      "pictures": [],
      "headline": "Product Development",
      "text": null
    },
    "relationships": {
      "roles": {
        "links": {
          "self": "https://api.teamtailor.com/v1/departments/5/relationships/roles",
          "related": "https://api.teamtailor.com/v1/departments/5/roles"
        }
      },
      "teams": {
        "links": {
          "self": "https://api.teamtailor.com/v1/departments/5/relationships/teams",
          "related": "https://api.teamtailor.com/v1/departments/5/teams"
        }
      }
    }
  },
  "meta": {
    "texts": {
      "name-singular": "department",
      "name-plural": "departments",
      "all": "All departments"
    }
  }
}

Update departments

PATCH https://api.teamtailor.com/v1/departments/5 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{"data":{"id":"5","type":"departments","attributes":{"name":"Magic"}}}

Example response

{
  "data": {
    "id": "5",
    "type": "departments",
    "links": {
      "self": "https://api.teamtailor.com/v1/departments/5"
    },
    "attributes": {
      "name": "Magic",
      "people-headline": null,
      "people-text": null,
      "row-order": 7864320,
      "pictures": [],
      "headline": "Product Development",
      "text": null
    },
    "relationships": {
      "roles": {
        "links": {
          "self": "https://api.teamtailor.com/v1/departments/5/relationships/roles",
          "related": "https://api.teamtailor.com/v1/departments/5/roles"
        }
      },
      "teams": {
        "links": {
          "self": "https://api.teamtailor.com/v1/departments/5/relationships/teams",
          "related": "https://api.teamtailor.com/v1/departments/5/teams"
        }
      }
    }
  },
  "meta": {
    "texts": {
      "name-singular": "department",
      "name-plural": "departments",
      "all": "All departments"
    }
  }
}

Delete departments

DELETE https://api.teamtailor.com/v1/departments/5 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

Jobs

This object represents the job ad and the job process in Teamtailor. You can retrieve a list or just a single job, update and create new jobs.

Job Object

{
  "data": {
    "id": "7199",
    "type": "jobs",
    "links": {
      "careersite-job-url": "http://career.teamtailor.com/jobs/7199-new-title",
      "careersite-job-apply-url": "https://career.teamtailor.com/jobs/7199-new-title/applications/new",
      "careersite-job-apply-iframe-url": "https://career.teamtailor.com/jobs/7199-new-title/applications/new?iframe=true",
      "self": "https://api.teamtailor.com/v1/jobs/7199"
    },
    "attributes": {
      "apply-button-text": "Join us!",
      "body": "<p>Job body HTML goes here.</p>",
      "end-date": "2016-11-25T00:00:00.000+01:00",
      "human-status": "scheduled",
      "internal": false,
      "picture": null,
      "pinned": false,
      "start-date": "2016-11-17T00:00:00.000+01:00",
      "status": "open",
      "title": "Marketing Manager",
      "pitch": "Become part of something great!",
      "tags": [
        "JavaScript",
        "Ruby"
      ],
      "external-application-url": null,
      "name-requirement": "optional",
      "resume-requirement": "optional",
      "cover-letter-requirement": "optional",
      "phone-requirement": "optional",
      "created-at": "2016-11-17T00:00:00.000+01:00",
      "mailbox": "job-2cc71305-fd98-25c6-ab07-2703c453ad9d@inbound.teamtailor.com"
    },
    "relationships": {
      "department": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/department",
          "related": "https://api.teamtailor.com/v1/jobs/7199/department"
        }
      },
      "role": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/role",
          "related": "https://api.teamtailor.com/v1/jobs/7199/role"
        }
      },
      "location": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/location",
          "related": "https://api.teamtailor.com/v1/jobs/7199/location"
        }
      },
      "locations": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/locations",
          "related": "https://api.teamtailor.com/v1/jobs/7199/locations"
        }
      },
      "user": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/user",
          "related": "https://api.teamtailor.com/v1/jobs/7199/user"
        }
      },
      "questions": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/questions",
          "related": "https://api.teamtailor.com/v1/jobs/7199/questions"
        }
      },
      "picked-questions": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/picked-questions",
          "related": "https://api.teamtailor.com/v1/jobs/7199/picked-questions"
        }
      },
      "candidates": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/candidates",
          "related": "https://api.teamtailor.com/v1/jobs/7199/candidates"
        }
      },
      "stages": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/stages",
          "related": "https://api.teamtailor.com/v1/jobs/7199/stages"
        }
      },
      "colleagues": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/colleagues",
          "related": "https://api.teamtailor.com/v1/jobs/7199/colleagues"
        }
      },
      "regions": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/regions",
          "related": "https://api.teamtailor.com/v1/jobs/7199/regions"
        }
      }
    }
  }
}

Attributes

Attribute Type Description
title string The title of the job ad
pitch string The pitch of the job ad, displayed below the title
body string The ad text, simple html is supported
apply-button-text string Custom text for apply button
created-at date When job was first created. Requires admin permission.
end-date date The Job ad’s expire date
human-status string Human readable status of the job, can be one of the following: archived, unlisted, expired, draft, published, scheduled or unsaved
internal boolean True if internal job
picture object Job ad’s picture
pinned boolean true if the job is pinned to the top on the career site
start-date date Scheduled date to publish the job ad
status string The job’s status, can be one of the following: open, draft, archived, unlisted or temp
tags array Array of string for each tag Requires admin permission.
external-application-url string Optional attribute for where candidates should be linked when applying for the job.
name-requirement string Allowed options: off, optional, required
resume_requirement string Allowed options: off, optional, required
cover-letter-requirement string Allowed options: off, optional, required
phone-requirement string Allowed options: off, optional, required
mailbox string Job email Read only
Link Description
careersite-job-url View job on the Career site
careersite-job-internal-url Secret link for internal jobs
careersite-job-apply-url URL to the application form
careersite-job-apply-iframe-url URL for application iframe src

Relations

Relation Description
user The recruiter
department The department of the job
role The role of the job
location Where the job is located. Deprecated, use locations instead. Will be removed after 2019.08.01
locations Where the job is located
questions The job’s questions
picked-questions Relation betwen job and question
candidates Candidates who have applied to the job
stages The recruitment stages of the job
team-memberships The hiring team memberships
colleagues The users that are displayed as colleagues of the job ad
regions Regions based on where the job is located

List Jobs

GET https://api.teamtailor.com/v1/jobs HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

curl -X "GET" "https://api.teamtailor.com/v1/jobs" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "7263",
      "type": "jobs",
      "links": {
        "careersite-job-url": "http://career.teamtailor.com/jobs/7263-account-manager",
        "careersite-job-apply-url": "https://career.teamtailor.com/jobs/7263-account-manager/applications/new",
        "self": "https://api.teamtailor.com/v1/jobs/7263"
      },
      "attributes": {
        "apply-button-text": null,
        "body": "hello",
        "end-date": null,
        "human-status": "published",
        "internal": false,
        "picture": null,
        "pinned": false,
        "start-date": null,
        "status": "open",
        "title": "Account manager",
        "pitch": "Become part of something great!",
        "tags": [],
        "external-application-url": null,
        "created-at": "2016-11-17T00:00:00.000+01:00"
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/department",
            "related": "https://api.teamtailor.com/v1/jobs/7263/department"
          }
        },
        "role": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/role",
            "related": "https://api.teamtailor.com/v1/jobs/7263/role"
          }
        },
        "location": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/location",
            "related": "https://api.teamtailor.com/v1/jobs/7263/location"
          }
        },
        "locations": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/locations",
            "related": "https://api.teamtailor.com/v1/jobs/7263/locations"
          }
        },
        "user": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/user",
            "related": "https://api.teamtailor.com/v1/jobs/7263/user"
          }
        },
        "candidates": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/candidates",
            "related": "https://api.teamtailor.com/v1/jobs/7263/candidates"
          }
        },
        "stages": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/stages",
            "related": "https://api.teamtailor.com/v1/jobs/7263/stages"
          }
        },
        "regions": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/regions",
            "related": "https://api.teamtailor.com/v1/jobs/7263/regions"
          }
        }
      }
    },
    {
      "id": "7262",
      "type": "jobs",
      "links": {
        "careersite-job-url": "http://career.teamtailor.com/jobs/7262-marketing-manager",
        "careersite-job-apply-url": "https://career.teamtailor.com/jobs/7262-marketing-manager/applications/new",
        "self": "https://api.teamtailor.com/v1/jobs/7262"
      },
      "attributes": {
        "apply-button-text": "Join us!",
        "body": "hello",
        "end-date": null,
        "human-status": "published",
        "picture": null,
        "pinned": false,
        "start-date": null,
        "status": "open",
        "title": "Marketing manager",
        "pitch": "Become part of something great!",
        "tags": [
          "JavaScript",
          "Ruby"
        ],
        "external-application-url": null,
        "created-at": "2016-11-17T00:00:00.000+01:00"
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7262/relationships/department",
            "related": "https://api.teamtailor.com/v1/jobs/7262/department"
          }
        },
        "role": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7262/relationships/role",
            "related": "https://api.teamtailor.com/v1/jobs/7262/role"
          }
        },
        "location": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7262/relationships/location",
            "related": "https://api.teamtailor.com/v1/jobs/7262/location"
          }
        },
        "locations": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7262/relationships/locations",
            "related": "https://api.teamtailor.com/v1/jobs/7262/locations"
          }
        },
        "user": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7262/relationships/user",
            "related": "https://api.teamtailor.com/v1/jobs/7262/user"
          }
        },
        "questions": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7262/relationships/questions",
            "related": "https://api.teamtailor.com/v1/jobs/7262/questions"
          }
        },
        "candidates": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7262/relationships/candidates",
            "related": "https://api.teamtailor.com/v1/jobs/7262/candidates"
          }
        },
        "stages": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7262/relationships/stages",
            "related": "https://api.teamtailor.com/v1/jobs/7262/stages"
          }
        },
        "regions": {
          "links": {
            "self": "https://api.teamtailor.com/v1/jobs/7262/relationships/regions",
            "related": "https://api.teamtailor.com/v1/jobs/7262/regions"
          }
        }
      }
    }
  ],
  "meta": {
    "record-count": 2,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/jobs?filter%5Bdepartment%5D=337&page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/jobs?filter%5Bdepartment%5D=337&page%5Bnumber%5D=1&page%5Bsize%5D=10"
  }
}

Use this endpoint to retrieve lists of jobs.

Example parameters

Parameter Default Description
include null Comma separated list of relations to include in the response. For example department,role.
filter[status] published Filter by job status. Available statuses: published, unlisted, archived, draft, scheduled and all. See Permissions for more info.
filter[feed] public Filter by public and/or internal jobs. See Permissions for more info.
filter[department] null Filter by department id.
filter[role] null Filter by role id.
filter[location] null Filter by location id. Removed, use filter[locations] instead.
filter[locations] null Filter by location id.
filter[regions] null Filter by region id.
sort -pinned,date Default sorting based on pinned status and publish date

Show a Job

GET https://api.teamtailor.com/v1/jobs/{id} HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/jobs/{id}" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "7199",
    "type": "jobs",
    "links": {
      "careersite-job-url": "http://career.teamtailor.com/jobs/7263-yay-horray-3",
      "careersite-job-apply-url": "https://career.teamtailor.com/jobs/7263-yay-horray-3/applications/new",
      "self": "https://api.teamtailor.com/v1/jobs/7263"
    },
    "attributes": {
      "apply-button-text": "Join us!",
      "body": "<p>hello world</p>",
      "end-date": null,
      "human-status": "published",
      "internal": false,
      "picture": null,
      "pinned": false,
      "start-date": null,
      "status": "open",
      "title": "My new job",
      "pitch": "Become part of something great!",
      "tags": [
        "Ruby"
      ],
      "external-application-url": null,
      "created-at": "2016-11-17T00:00:00.000+01:00"
    },
    "relationships": {
      "department": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/department",
          "related": "https://api.teamtailor.com/v1/jobs/7263/department"
        }
      },
      "role": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/role",
          "related": "https://api.teamtailor.com/v1/jobs/7263/role"
        }
      },
      "location": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/location",
          "related": "https://api.teamtailor.com/v1/jobs/7263/location"
        }
      },
      "locations": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/locations",
          "related": "https://api.teamtailor.com/v1/jobs/7263/locations"
        }
      },
      "user": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/user",
          "related": "https://api.teamtailor.com/v1/jobs/7263/user"
        }
      },
      "questions": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/questions",
          "related": "https://api.teamtailor.com/v1/jobs/7263/questions"
        }
      },
      "candidates": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/candidates",
          "related": "https://api.teamtailor.com/v1/jobs/7263/candidates"
        }
      },
      "stages": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/stages",
          "related": "https://api.teamtailor.com/v1/jobs/7263/stages"
        }
      },
      "regions": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/regions",
          "related": "https://api.teamtailor.com/v1/jobs/7263/regions"
        }
      }
    }
  }
}

Retreive a specific job.

Parameter Description
id The job’s id.

Create Job

POST https://api.teamtailor.com/v1/jobs HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{
  "data": {
    "type": "jobs",
    "attributes": {
      "title": "Account Manager",
      "pitch": "Become part of something great!",
      "body": "<p>hello</p>",
      "picture": "url-to-a-picture"
    },
    "relationships": {
      "user": {
        "data": {
          "id": "819",
          "type": "users"
        }
      },
      "department": {
        "data": {
          "id": "337",
          "type": "departments"
        }
      },
      "locations": {
        "data": [
          {
            "id": "89",
            "type": "locations"
          },
          {
            "id": "90",
            "type": "locations"
          }
        ]
      }
    }
  }
}
curl -X "POST" "https://api.teamtailor.com/v1/jobs" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
     -H "Content-Type: application/vnd.api+json" \
     -d "{\"data\":{\"type\":\"jobs\",\"attributes\":{\"title\":\"Account Manager\",\"pitch\":\"Become part of something great!\",\"body\":\"<p>hello</p>\"},\"relationships\":{\"user\":{\"data\":{\"id\":\"819\",\"type\":\"users\"}},\"department\":{\"data\":{\"id\":\"337\",\"type\":\"departments\"}},\"location\":{\"data\":{\"id\":\"667\",\"type\":\"locations\"}}}}}"

Example response

{
  "data": {
    "id": "7265",
    "type": "jobs",
    "links": {
      "careersite-job-url": "http://career.teamtailor.com/jobs/7265-account-manager",
      "careersite-job-apply-url": "https://career.teamtailor.com/jobs/7265-account-manager/applications/new",
      "self": "https://api.teamtailor.com/v1/jobs/7265"
    },
    "attributes": {
      "apply-button-text": null,
      "body": "<p>hello</p>",
      "end-date": null,
      "human-status": "published",
      "internal": false,
      "picture": null,
      "pinned": false,
      "start-date": null,
      "status": "open",
      "title": "Account Manager",
      "pitch": "Become part of something great!",
      "external-application-url": null,
      "created-at": "2016-11-17T00:00:00.000+01:00"
    },
    "relationships": {
      "department": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7265/relationships/department",
          "related": "https://api.teamtailor.com/v1/jobs/7265/department"
        }
      },
      "role": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7265/relationships/role",
          "related": "https://api.teamtailor.com/v1/jobs/7265/role"
        }
      },
      "location": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7265/relationships/location",
          "related": "https://api.teamtailor.com/v1/jobs/7265/location"
        }
      },
      "locations": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7265/relationships/locations",
          "related": "https://api.teamtailor.com/v1/jobs/7265/locations"
        }
      },
      "user": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7265/relationships/user",
          "related": "https://api.teamtailor.com/v1/jobs/7265/user"
        }
      },
      "questions": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7265/relationships/questions",
          "related": "https://api.teamtailor.com/v1/jobs/7265/questions"
        }
      },
      "candidates": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7265/relationships/candidates",
          "related": "https://api.teamtailor.com/v1/jobs/7265/candidates"
        }
      },
      "stages": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7265/relationships/stages",
          "related": "https://api.teamtailor.com/v1/jobs/7265/stages"
        }
      },
      "regions": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7265/relationships/regions",
          "related": "https://api.teamtailor.com/v1/jobs/7265/regions"
        }
      }
    }
  }
}

Create a new job.

Update Job

PATCH https://api.teamtailor.com/v1/jobs/7199 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{
  "data": {
    "id": "7199",
    "attributes": {
      "title": "New Title",
      "status": "unlisted"
      "tags": [
        "JavaScript"
      ]
    },
    "type": "jobs"
  }
}
curl -X "PATCH" "https://api.teamtailor.com/v1/jobs/7199" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
     -H "Content-Type: application/vnd.api+json" \
     -d '{
  "data": {
    "id": "7236",
    "attributes": {
      "title": "New Title",
      "status": "unlisted"
    },
    "type": "jobs",
    "relationships": {
      "locations": {
        "data": [{
          "type": "locations", "id": "667"
        }, {
          "type": "locations", "id": "668"
        }]
      }
    }
  }
}'

Example response

{
  "data": {
    "id": "7199",
    "type": "jobs",
    "links": {
      "careersite-job-url": "http://career.teamtailor.com/jobs/7199-yay-horray",
      "careersite-job-apply-url": "https://career.teamtailor.com/jobs/7199-yay-horray/applications/new",
      "self": "https://api.teamtailor.com/v1/jobs/7199"
    },
    "attributes": {
      "apply-button-text": "Join us!",
      "body": "<p>lopl</p>",
      "end-date": null,
      "human-status": "published",
      "internal": false,
      "picture": null,
      "pinned": false,
      "start-date": null,
      "status": "open",
      "title": "New Title",
      "pitch": "Become part of something great!",
      "tags": [
        "JavaScript"
      ],
      "external-application-url": null,
      "created-at": "2016-11-17T00:00:00.000+01:00"
    },
    "relationships": {
      "department": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/department",
          "related": "https://api.teamtailor.com/v1/jobs/7199/department"
        }
      },
      "role": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/role",
          "related": "https://api.teamtailor.com/v1/jobs/7199/role"
        }
      },
      "location": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/location",
          "related": "https://api.teamtailor.com/v1/jobs/7199/location"
        }
      },
      "locations": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/locations",
          "related": "https://api.teamtailor.com/v1/jobs/7199/locations"
        }
      },
      "user": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/user",
          "related": "https://api.teamtailor.com/v1/jobs/7199/user"
        }
      },
      "questions": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/questions",
          "related": "https://api.teamtailor.com/v1/jobs/7199/questions"
        }
      },
      "candidates": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/candidates",
          "related": "https://api.teamtailor.com/v1/jobs/7199/candidates"
        }
      },
      "stages": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7199/relationships/stages",
          "related": "https://api.teamtailor.com/v1/jobs/7199/stages"
        }
      },
      "regions": {
        "links": {
          "self": "https://api.teamtailor.com/v1/jobs/7263/relationships/regions",
          "related": "https://api.teamtailor.com/v1/jobs/7263/regions"
        }
      }
    }
  }
}

Change a job’s attributes/relationships.

Job Applications

This object represents the job applications.

Job application Object

{
  "data": {
    "id": "1337",
    "type": "job-applications",
    "links": {
      "self": "https://api.teamtailor.com/v1/job-applications/1337"
    },
    "attributes": {
      "created-at": "2017-02-20T10:30:43.910+01:00",
      "cover-letter": "Dear Sir/Madam…",
      "updated-at": "2017-02-20T10:30:43.910+01:00",
      "rejected-at": null,
      "referring-url": null,
      "referring-site": null,
      "sourced": true,
      "changed-stage-at": "2017-01-11T11:29:48.841+01:00",
      "send-user-notifications": true
    },
    "relationships": {
      "candidate": {
        "links": {
          "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/candidate",
          "related": "https://api.teamtailor.com/v1/job-applications/1337/candidate"
        }
      },
      "job": {
        "links": {
          "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/job",
          "related": "https://api.teamtailor.com/v1/job-applications/1337/job"
        }
      },
      "stage": {
        "links": {
          "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/stage",
          "related": "https://api.teamtailor.com/v1/job-applications/1337/stage"
        }
      },
      "reject-reason": {
        "links": {
          "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/reject-reason",
          "related": "https://api.teamtailor.com/v1/job-applications/1337/reject-reason"
        }
      }
    }
  }
}

Attributes

Attribute Type Description
created-at date
cover-letter string
changed-stage-at date Date when candidate was added to current stage
updated-at date
rejected-at date If set, the candidate has been rejected for this job
referring-url string
referring-site string Read only, friendly name parsed from referring-url (i.e. Facebook, Indeed etc)
sourced boolean
send-default-reply boolean Create only, set to true if you want to send the “Default reply” email to the candidate. Default: false
send-user-notifications boolean Create only, set to true if you want to send notifications to users. Default: false

Relations

The job-application object always has a relation to a candidate and a job

Relation Description
candidate
job
stage Current stage (i.e Inbox, Reviewing, Hired)
reject-reason

List Job applications

GET https://api.teamtailor.com/v1/job-applications HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/job-applications" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "1337",
      "type": "job-applications",
      "links": {
        "self": "https://api.teamtailor.com/v1/job-applications/1337"
      },
      "attributes": {
        "created-at": "2015-04-22T19:39:32.902+02:00",
        "cover-letter": "",
        "updated-at": "2015-09-09T11:26:33.991+02:00",
        "rejected-at": "2015-09-09T11:26:33.991+02:00",
        "referring-url": "http://www.teamtailor.com/sv",
        "referring-site": "Teamtailor",
        "sourced": false,
        "changed-stage-at": "2017-01-11T11:29:48.841+01:00"
      },
      "relationships": {
        "candidate": {
          "links": {
            "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/candidate",
            "related": "https://api.teamtailor.com/v1/job-applications/1337/candidate"
          }
        },
        "job": {
          "links": {
            "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/job",
            "related": "https://api.teamtailor.com/v1/job-applications/1337/job"
          }
        },
        "stage": {
          "links": {
            "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/stage",
            "related": "https://api.teamtailor.com/v1/job-applications/1337/stage"
          }
        },
        "reject-reason": {
          "links": {
            "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/reject-reason",
            "related": "https://api.teamtailor.com/v1/job-applications/1337/reject-reason"
          }
        }
      }
    },
    {
      "id": "1338",
      "type": "job-applications",
      "links": {
        "self": "https://api.teamtailor.com/v1/job-applications/1338"
      },
      "attributes": {
        "created-at": "2015-04-21T10:34:35.109+02:00",
        "cover-letter": "",
        "updated-at": "2016-06-27T12:28:37.808+02:00",
        "rejected-at": "2015-09-09T11:26:34.025+02:00",
        "referring-url": "http://se.indeed.com/visajobb?jk=abc123",
        "referring-site": "Indeed Sweden",
        "sourced": false,
        "changed-stage-at": "2017-01-11T11:29:48.841+01:00"
      },
      "relationships": {
        "candidate": {
          "links": {
            "self": "https://api.teamtailor.com/v1/job-applications/1338/relationships/candidate",
            "related": "https://api.teamtailor.com/v1/job-applications/1338/candidate"
          }
        },
        "job": {
          "links": {
            "self": "https://api.teamtailor.com/v1/job-applications/1338/relationships/job",
            "related": "https://api.teamtailor.com/v1/job-applications/1338/job"
          }
        },
        "stage": {
          "links": {
            "self": "https://api.teamtailor.com/v1/job-applications/1338/relationships/stage",
            "related": "https://api.teamtailor.com/v1/job-applications/1338/stage"
          }
        },
        "reject-reason": {
          "links": {
            "self": "https://api.teamtailor.com/v1/job-applications/1338/relationships/reject-reason",
            "related": "https://api.teamtailor.com/v1/job-applications/1338/reject-reason"
          }
        }
      }
    }
  ],
  "meta": {
    "record-count": 100,
    "page-count": 10
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/job-applications?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "next": "https://api.teamtailor.com/v1/job-applications?page%5Bnumber%5D=2&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/job-applications?page%5Bnumber%5D=106&page%5Bsize%5D=10"
  }
}

Use this endpoint to retrieve lists of job applications.

Example parameters

Parameter Default Description
include null Comma separated list of relations to include in the response. For example stage,candidate.
filter[stage-type] null Filter by current stage type (Inbox, In process or Hired)
sort null Sort applications, for example -changed_stage_at to sort by latest added to current stage.

Show a Job application

GET https://api.teamtailor.com/v1/job-applications/520 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/job-applications/520" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "1337",
    "type": "job-applications",
    "links": {
      "self": "https://api.teamtailor.com/v1/job-applications/1337"
    },
    "attributes": {
      "created-at": "2017-02-20T10:30:43.910+01:00",
      "cover-letter": "Dear Sir/Madam…",
      "updated-at": "2017-02-20T10:30:43.910+01:00",
      "rejected-at": null,
      "referring-url": null,
      "referring-site": null,
      "sourced": true,
      "changed-stage-at": "2017-01-11T11:29:48.841+01:00"
    },
    "relationships": {
      "candidate": {
        "links": {
          "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/candidate",
          "related": "https://api.teamtailor.com/v1/job-applications/1337/candidate"
        }
      },
      "job": {
        "links": {
          "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/job",
          "related": "https://api.teamtailor.com/v1/job-applications/1337/job"
        }
      },
      "stage": {
        "links": {
          "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/stage",
          "related": "https://api.teamtailor.com/v1/job-applications/1337/stage"
        }
      },
      "reject-reason": {
        "links": {
          "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/reject-reason",
          "related": "https://api.teamtailor.com/v1/job-applications/1337/reject-reason"
        }
      }
    }
  }
}

Retreive a specific job application.

Parameter Description
id The job application’s id.

Create Job application

POST https://api.teamtailor.com/v1/job-applications HTTP/1.1

X-Api-Version: 20161108
Authorization: Token token=abc123abc123

{
  "data": {
    "type": "job-applications",
    "attributes": {
      "cover-letter": "Hi, I'm a driven developer looking for new opportunities…",
      "sourced": true,
      "send-user-notifications": true
    },
    "relationships": {
      "candidate": {
        "data": {
          "id": "1337",
          "type": "candidates"
        }
      },
      "job": {
        "data": {
          "id": "12345",
          "type": "jobs"
        }
      }
    }
  }
}

## create Job Application
curl -X "POST" "https://api.teamtailor.com/v1/job-applications" \
     -H "Content-Type: application/vnd.api+json" \
     -H "X-Api-Version: 20161108" \
     -H "Authorization: Token token=abc123abc123" \
     -d $'{
  "data": {
    "type": "job-applications",
    "attributes": {
      "sourced": true,
      "cover-letter": "Dear Sir/Madam"
    },
    "relationships": {
      "job": {
        "data": {
          "id": "1337",
          "type": "jobs"
        }
      },
      "candidate": {
        "data": {
          "id": "12345",
          "type": "candidates"
        }
      }
    }
  }
}'

Example response

{
  "data": {
    "id": "1337",
    "type": "job-applications",
    "links": {
      "self": "https://api.teamtailor.com/v1/job-applications/1337"
    },
    "attributes": {
      "created-at": "2017-02-20T10:30:43.910+01:00",
      "cover-letter": "Dear Sir/Madam…",
      "updated-at": "2017-02-20T10:30:43.910+01:00",
      "rejected-at": null,
      "referring-url": null,
      "referring-site": null,
      "sourced": true,
      "changed-stage-at": "2017-01-11T11:29:48.841+01:00"
    },
    "relationships": {
      "candidate": {
        "links": {
          "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/candidate",
          "related": "https://api.teamtailor.com/v1/job-applications/1337/candidate"
        }
      },
      "job": {
        "links": {
          "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/job",
          "related": "https://api.teamtailor.com/v1/job-applications/1337/job"
        }
      },
      "stage": {
        "links": {
          "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/stage",
          "related": "https://api.teamtailor.com/v1/job-applications/1337/stage"
        }
      },
      "reject-reason": {
        "links": {
          "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/reject-reason",
          "related": "https://api.teamtailor.com/v1/job-applications/1337/reject-reason"
        }
      }
    }
  }
}

Create a new Job application.

As a convience method it’s also possible to embed an iframe that outputs the job application form. See example.

Update Job application

PATCH https://api.teamtailor.com/v1/job-applications/1337 HTTP/1.1
X-Api-Version: 20161108
Authorization: Token token=abc123abc123

{
  "data": {
    "id": "1337",
    "attributes": {
      "cover-letter": "To Whom It May Concern…"
    },
    "type": "job-applications"
  }
}
## update
curl -X "PATCH" "https://api.teamtailor.com/v1/job-applications/1337" \
     -H "Content-Type: application/vnd.api+json" \
     -H "X-Api-Version: 20161108" \
     -H "Authorization: Token token=abc123abc123" \
     -d $'{
  "data": {
    "id": "1337",
    "attributes": {
      "cover-letter": "To Whom It May Concern…"
    },
    "type": "job-applications"
  }
}'

Example response

{
  "data": {
    "id": "1337",
    "type": "job-applications",
    "links": {
      "self": "https://api.teamtailor.com/v1/job-applications/1337"
    },
    "attributes": {
      "created-at": "2017-02-20T10:30:43.910+01:00",
      "cover-letter": "To Whom It May Concern…",
      "updated-at": "2017-02-20T13:36:12.406+01:00",
      "rejected-at": null,
      "referring-url": null,
      "referring-site": null,
      "sourced": true,
      "changed-stage-at": "2017-01-11T11:29:48.841+01:00"
    },
    "relationships": {
      "candidate": {
        "links": {
          "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/candidate",
          "related": "https://api.teamtailor.com/v1/job-applications/1337/candidate"
        }
      },
      "job": {
        "links": {
          "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/job",
          "related": "https://api.teamtailor.com/v1/job-applications/1337/job"
        }
      },
      "stage": {
        "links": {
          "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/stage",
          "related": "https://api.teamtailor.com/v1/job-applications/1337/stage"
        }
      },
      "reject-reason": {
        "links": {
          "self": "https://api.teamtailor.com/v1/job-applications/1337/relationships/reject-reason",
          "related": "https://api.teamtailor.com/v1/job-applications/1337/reject-reason"
        }
      }
    }
  }
}

Change a candidates’s attributes/relationships.

Locations

Location Object

{
  "data": {
    "id": "667",
    "type": "locations",
    "links": {
      "self": "https://api.teamtailor.com/v1/locations/667"
    },
    "attributes": {
      "address": "Tegnérgatan 34",
      "city": "Stockholm",
      "country": "Sweden",
      "email": "support@example.com",
      "headquarters": true,
      "lat": "59.33855810000001",
      "long": "18.0557594",
      "name": "",
      "phone": "",
      "zip": "113 59"
    }
  }
}

Attributes

Attribute Type Description
address string Street address
city string City name
country string Full name of country, e.g Sweden
email string Contact e-mail address
headquarters boolean True if it’s the company’s main location. Can only be one headquarter per company
lat string Decimal latitude of location, e.g 59.33855810000001
long string Decimal longitude of location, e.g 18.0557594
name string Specify name if City isn’t enough information
phone string Contact phone number
zip string Postal code

List locations

GET https://api.teamtailor.com/v1/locations HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/locations" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "667",
      "type": "locations",
      "links": {
        "self": "https://api.teamtailor.com/v1/locations/667"
      },
      "attributes": {
        "address": "Tegnérgatan 34",
        "city": "Stockholm",
        "country": "Sweden",
        "email": "support@example.com",
        "headquarters": true,
        "lat": "59.33855810000001",
        "long": "18.0557594",
        "name": "",
        "phone": "",
        "zip": "113 59"
      }
    },
    {
      "id": "2980",
      "type": "locations",
      "links": {
        "self": "https://api.teamtailor.com/v1/locations/2980"
      },
      "attributes": {
        "address": "",
        "city": "Göteborg",
        "country": "Sweden",
        "email": "",
        "headquarters": false,
        "lat": "57.70887",
        "long": "11.97456",
        "name": "",
        "phone": "",
        "zip": ""
      }
    }
  ],
  "meta": {
    "record-count": 2,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/locations?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/locations?page%5Bnumber%5D=1&page%5Bsize%5D=10"
  }
}

Show a Location

GET https://api.teamtailor.com/v1/locations/667 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/locations/667" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "667",
    "type": "locations",
    "links": {
      "self": "https://api.teamtailor.com/v1/locations/667"
    },
    "attributes": {
      "address": "Tegnérgatan 34",
      "city": "Stockholm",
      "country": "Sweden",
      "email": "support@example.com",
      "headquarters": true,
      "lat": "59.33855810000001",
      "long": "18.0557594",
      "name": "",
      "phone": "",
      "zip": "113 59"
    }
  }
}

Create locations

POST https://api.teamtailor.com/v1/locations HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{"data":{"type":"locations","attributes":{"name":"Teamtailor HQ","city":"Stockholm","country":"Sweden","address":"Östgötagatan 16","zip":"116 21"}}}

Example response

{
  "data": {
    "id": "4",
    "type": "locations",
    "links": {
      "self": "https://api.teamtailor.com/v1/locations/4"
    },
    "attributes": {
      "address": "Östgötagatan 16",
      "city": "Stockholm",
      "country": "Sweden",
      "email": null,
      "headquarters": false,
      "name": "Teamtailor HQ",
      "phone": null,
      "zip": "116 21"
    }
  },
  "meta": {
    "texts": {
      "all": "All locations"
    }
  }
}

Update locations

PATCH https://api.teamtailor.com/v1/locations/5 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{"data":{"id":"4","type":"locations","attributes":{"name":"Teamtailor Stockholm"}}}

Example response

{
  "data": {
    "id": "4",
    "type": "locations",
    "links": {
      "self": "https://api.teamtailor.com/v1/locations/4"
    },
    "attributes": {
      "address": "Östgötagatan 16",
      "city": "Stockholm",
      "country": "Sweden",
      "email": null,
      "headquarters": false,
      "name": "Teamtailor Stockholm",
      "phone": null,
      "zip": "116 21"
    }
  },
  "meta": {
    "texts": {
      "all": "All locations"
    }
  }
}

Delete locations

DELETE https://api.teamtailor.com/v1/locations/4 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

Notes

Note Object

{
  "id": "1",
  "type": "notes",
  "links": {
    "self": "/v1/notes/1"
  },
  "attributes": {
    "note": "Example note",
    "user-id": 2,
    "candidate-id": 4,
    "created-by-trigger": false,
    "mentioned-user-ids": [],
    "private-note": false,
    "created-at": "2020-07-16T11:31:22.389+02:00",
    "updated-at": "2020-07-16T11:32:25.200+02:00"
  }
}

Attributes

Attribute Type Description
note string Note
user-id integer Note
candidate-id integer Note
created-by-trigger boolean Note
mentioned-user-ids array Note
private-note boolean Note
created-at datetime Note
updated-at datetime Note

Relations

Relation Description
candidate Candidate who holds the note
user User who created the note

List Notes

GET https://api.teamtailor.com/v1/notes HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/notes" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "notes": [
    {
      "data": {
        "id": 1,
        "type": "notes",
        "attributes": {
          "note": "Example note",
          "user-id": 2,
          "candidate-id": 4,
          "created-by-trigger": false,
          "mentioned-user-ids": [],
          "private-note": false,
          "created-at": "2020-07-16T11:31:22.389+02:00",
          "updated-at": "2020-07-16T11:32:25.200+02:00"

        }
      }
    }
  ]
}

Use this endpoint to retrieve lists of notes.

Show Note

GET https://api.teamtailor.com/v1/notes/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/notes/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "1",
    "type": "notes",
    "links": {
      "self": "/v1/notes/1"
    },
    "attributes": {
      "note": "Example note",
      "created-at": "2020-07-14T09:33:18.789+02:00",
      "created-by-trigger": false,
      "mentioned-user-ids": [],
      "private-note": false,
      "updated-at": "2020-07-14T09:33:18.343+02:00",
      "candidate-id": 4,
      "user-id": 2
    }
  }
}

Use this endpoint to retrieve a single note.

Create Note

POST https://api.teamtailor.com/v1/note HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{
  "data": {
    "type": "notes",
    "attributes": {
      "note": "new note for candidate"
    },
    "relationships": {
      "candidate": {
        "data": {
          "id": 4
        }
      },
      "user": {
        "data": {
          "id": 2
        }
      }
    }
  }
}
curl -X "POST" "https://api.teamtailor.com/v1/reject-reasons" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
     -H "Content-Type: application/vnd.api+json" \
     -d "{\"data\": {\"type\": \"notes\",\"attributes\": {\"note\": \"new note for candidate\"},\"relationships\": {\"candidate\": {\"data\": {\"id\": 4}},\"user\": {\"data\": {\"id\": 2}}}}}"

Example response

{
  "data": {
    "id": "2",
    "type": "notes",
    "links": {
      "self": "/v1/notes/2"
    },
    "attributes": {
      "note": "New note",
      "created-at": "2020-07-16T14:56:31.778+02:00",
      "created-by-trigger": false,
      "mentioned-user-ids": [],
      "private-note": false,
      "updated-at": "2020-07-16T14:56:31.778+02:00",
      "candidate-id": 4,
      "user-id": 2
    }
  }
}

Use this endpoint to create a new candidate note.

Update Note

PATCH https://api.teamtailor.com/v1/notes/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{
  "data": {
    "type": "notes",
    "attributes": {
      "note": "Updated note"
    }
  }
}
curl -X "PATCH" "https://api.teamtailor.com/v1/notes/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
     -H "Content-Type: application/vnd.api+json" \
     -d "{\
     "data\":{\"type\":\"notes\",\"attributes\":{\"note\":\"Updated note\"}}}"

Example response

{
  "data": {
    "id": "1",
    "type": "notes",
    "links": {
      "self": "/v1/notes/1"
    },
    "attributes": {
      "note": "Updated note",
      "created-at": "2020-07-14T09:33:18.789+02:00",
      "created-by-trigger": false,
      "mentioned-user-ids": [],
      "private-note": false,
      "updated-at": "2020-07-16T14:38:58.935+02:00",
      "candidate-id": 4,
      "user-id": 2
    }
  }
}

Use this endpoint to update the text of a note.

Delete Note

DELETE https://api.teamtailor.com/v1/notes/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "DELETE" "https://api.teamtailor.com/v1/notes/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Use this endpoint to delete a note.

Partner Results

Partner Result Object

{
  "id": "85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4",
  "type": "partner-results",
  "links": {
    "self": "https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4"
  },
  "attributes": {
    "assessment-score": 100,
    "attachments": [
      {
        "url": "https://test.com",
        "description": "Test description"
      }
    ],
    "created-at": "2019-08-07T16:14:04.289+02:00",
    "details": "",
    "partner-name": null,
    "status": "completed",
    "summary": "The candidate already taken the test",
    "url": "https://test.com"
  },
  "relationships": {
    "candidate": {
      "links": {
        "self": "https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4/relationships/candidate",
        "related": "https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4/candidate"
      }
    },
    "job": {
      "links": {
        "self": "https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4/relationships/job",
        "related": "https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4/job"
      }
    }
  }
}

Attributes

Attribute Type Description
assessment-score integer Score value
attachments array Array of attachments
details string Json string with partner-result details
partner-name string Partner name
status string Status
summary string Summary
url string Url

Relations

Relation Description
candidate Candidate which the partner result concerns
job Job the partner result was created from

List Partner Results

GET https://api.teamtailor.com/v1/partner-results HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/partner-results" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4",
      "type": "partner-results",
      "links": {
        "self": "https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4"
      },
      "attributes": {
        "assessment-score": 100,
        "attachments": [
          {
            "url": "https://test.com",
            "description": "Test description"
          }
        ],
        "created-at": "2019-08-07T16:14:04.289+02:00",
        "details": "",
        "partner-name": null,
        "status": "completed",
        "summary": "The candidate already taken the test",
        "url": "https://test.com"
      },
      "relationships": {
        "candidate": {
          "links": {
            "self": "https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4/relationships/candidate",
            "related": "https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4/candidate"
          }
        },
        "job": {
          "links": {
            "self": "https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4/relationships/job",
            "related": "https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4/job"
          }
        }
      }
    },
    
  ],
  "meta": {
    "record-count": 20,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/partner-results?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "next": "https://api.teamtailor.com/v1/partner-results?page%5Bnumber%5D=2&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/partner-results?page%5Bnumber%5D=2&page%5Bsize%5D=10"
  }
}

Example parameters

Parameter Default Description
include null Comma separated list of relations to include in the response. For example candidate.
filter[candidate] null Filter by candidate.
sort id Sort list by any of the partner result attributes.

Show a Partner Result

GET https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4",
    "type": "partner-results",
    "links": {
      "self": "https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4"
    },
    "attributes": {
      "assessment-score": 100,
      "attachments": [
        {
          "url": "https://test.com",
          "description": "Test description"
        }
      ],
      "created-at": "2019-08-07T16:14:04.289+02:00",
      "details": "",
      "partner-name": null,
      "status": "completed",
      "summary": "The candidate already taken the test",
      "url": "https://test.com"
    },
    "relationships": {
      "candidate": {
        "links": {
          "self": "https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4/relationships/candidate",
          "related": "https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4/candidate"
        }
      },
      "job": {
        "links": {
          "self": "https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4/relationships/job",
          "related": "https://api.teamtailor.com/v1/partner-results/85ab953c-b8ea-11e9-a2a3-2a2ae2dbcce4/job"
        }
      }
    }
  }
}

Picked questions

A picked question represents the relationship between job and question. It tells you if question is mandatory for that job.

Picked Question Object

GET https://api.teamtailor.com/v1/picked-question/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/picked-question/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
  {
    "data": {
      "id": "1",
      "type": "picked-questions",
      "links": {
        "self": "https://api.teamtailor.com/v1/picked-questions/1"
      },
      "attributes": {
        "mandatory": false
      },
      "relationships": {
        "question": {
          "links": {
            "self": "https://api.teamtailor.com/v1/picked-questions/1/relationships/question",
            "related": "https://api.teamtailor.com/v1/picked-questions/1/question"
          }
        }
      }
    }
  }

Attributes

Attribute Type Description
mandatory bolean Is question mandatory. Default is false

Relations

Relation Description
question The question related to job

List picked questions

GET https://api.teamtailor.com/v1/picked-questions HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/picked-questions" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "1",
      "type": "picked-questions",
      "links": {
        "self": "https://api.teamtailor.com/v1/picked-questions/1"
      },
      "attributes": {
        "mandatory": false
      },
      "relationships": {
        "question": {
          "links": {
            "self": "https://api.teamtailor.com/v1/picked-questions/1/relationships/question",
            "related": "https://api.teamtailor.com/v1/picked-questions/1/question"
          }
        }
      }
    },
    {
      "id": "2",
      "type": "picked-questions",
      "links": {
        "self": "https://api.teamtailor.com/v1/picked-questions/2"
      },
      "attributes": {
        "mandatory": false
      },
      "relationships": {
        "question": {
          "links": {
            "self": "https://api.teamtailor.com/v1/picked-questions/2/relationships/question",
            "related": "https://api.teamtailor.com/v1/picked-questions/2/question"
          }
        }
      }
    }
  ],
  "meta": {
    "record-count": 3,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/picked-questions?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/picked-questions?page%5Bnumber%5D=1&page%5Bsize%5D=10"
  }
}

Questions

There are 5 types of question as specified by the question-type attribute.

Question Object

{
  "id": "1337",
  "type": "questions",
  "links": {
    "self": "https://api.teamtailor.com/v1/questions/1337"
  },
  "attributes": {
    "alternatives": null,
    "end-with": null,
    "multiple": null,
    "question-type": "Text",
    "start-with": null,
    "title": "Can you describe your ideal work environment?",
    "unit": null,
    "single-line": false
  }
}

Attributes

Attribute Type Description
alternatives array Alternatives for choice question
end-with integer Range end
multiple boolean Allow multiple answers or not for choice question
question-type string Type of question
start-with integer Range start
title string Question title
unit string Unit for range question
single-line boolean Single line answer for text question

List questions

GET https://api.teamtailor.com/v1/questions HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/questions" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "44221",
      "type": "questions",
      "links": {
        "self": "https://api.teamtailor.com/v1/questions/44221"
      },
      "attributes": {
        "alternatives": null,
        "end-with": null,
        "multiple": null,
        "question-type": "Boolean",
        "start-with": null,
        "title": "Have you ever worked with sales before?",
        "unit": null,
        "single-line": null
      },
      "relationships": {
        "candidate": {
          "links": {
            "self": "https://api.teamtailor.com/v1/questions/44221/relationships/candidate",
            "related": "https://api.teamtailor.com/v1/questions/44221/candidate"
          }
        }
      }
    },
    
  ],
  "meta": {
    "record-count": 20,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/questions?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "next": "https://api.teamtailor.com/v1/questions?page%5Bnumber%5D=2&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/questions?page%5Bnumber%5D=2&page%5Bsize%5D=10"
  }
}

Use this endpoint to retrieve lists of questions.

Example parameters

Parameter Default Description
include null Comma separated list of relations to include in the response. For example candidate.
sort id Sort list by any of the upload attributes.

Referrals

Referral Object

{
  "id": "1",
  "type": "referrals",
  "links": {
    "self": "https://api.teamtailor.com/v1/referrals/1"
  },
  "attributes": {
    "comment": "Very nice person",
    "created-at": "2019-08-07T16:21:15.728+02:00",
    "email": "piotr@example.com",
    "name": "Piotr Klupa",
    "phone": null
  },
  "relationships": {
    "candidate": {
      "links": {
        "self": "https://api.teamtailor.com/v1/referrals/1/relationships/candidate",
        "related": "https://api.teamtailor.com/v1/referrals/1/candidate"
      }
    },
    "department": {
      "links": {
        "self": "https://api.teamtailor.com/v1/referrals/1/relationships/department",
        "related": "https://api.teamtailor.com/v1/referrals/1/department"
      }
    },
    "job": {
      "links": {
        "self": "https://api.teamtailor.com/v1/referrals/1/relationships/job",
        "related": "https://api.teamtailor.com/v1/referrals/1/job"
      }
    },
    "role": {
      "links": {
        "self": "https://api.teamtailor.com/v1/referrals/1/relationships/role",
        "related": "https://api.teamtailor.com/v1/referrals/1/role"
      }
    },
    "user": {
      "links": {
        "self": "https://api.teamtailor.com/v1/referrals/1/relationships/user",
        "related": "https://api.teamtailor.com/v1/referrals/1/user"
      }
    }
  }
}

Attributes

Attribute Type Description
comment string Referral’s comment
created-at date
email string Candidate’s email
name string Candidate’s name
phone string Candidate’s phone

Relations

Relation Description
candidate Candidate which the referral concerns
department
job Job which the referral concerns
role
user User who creates the referral

List Referrals

GET https://api.teamtailor.com/v1/referrals HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/referrals" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "1",
      "type": "referrals",
      "links": {
        "self": "https://api.teamtailor.com/v1/referrals/1"
      },
      "attributes": {
        "comment": "Very nice person",
        "created-at": "2019-08-07T16:21:15.728+02:00",
        "email": "piotr@example.com",
        "name": "Piotr Klupa",
        "phone": null
      },
      "relationships": {
        "candidate": {
          "links": {
            "self": "https://api.teamtailor.com/v1/referrals/1/relationships/candidate",
            "related": "https://api.teamtailor.com/v1/referrals/1/candidate"
          }
        },
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/referrals/1/relationships/department",
            "related": "https://api.teamtailor.com/v1/referrals/1/department"
          }
        },
        "job": {
          "links": {
            "self": "https://api.teamtailor.com/v1/referrals/1/relationships/job",
            "related": "https://api.teamtailor.com/v1/referrals/1/job"
          }
        },
        "role": {
          "links": {
            "self": "https://api.teamtailor.com/v1/referrals/1/relationships/role",
            "related": "https://api.teamtailor.com/v1/referrals/1/role"
          }
        },
        "user": {
          "links": {
            "self": "https://api.teamtailor.com/v1/referrals/1/relationships/user",
            "related": "https://api.teamtailor.com/v1/referrals/1/user"
          }
        }
      }
    },
    
  ],
  "meta": {
    "record-count": 20,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/referrals?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "next": "https://api.teamtailor.com/v1/referrals?page%5Bnumber%5D=2&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/referrals?page%5Bnumber%5D=3&page%5Bsize%5D=10"
  }
}

Example parameters

Parameter Default Description
include null Comma separated list of relations to include in the response. For example candidate,department,job,role,user.
filter[candidate] null Filter by candidate.
filter[department] null Filter by department.
filter[email] null Filter by email.
filter[job] null Filter by job.
filter[phone] null Filter by phone.
filter[role] null Filter by role.
filter[user] null Filter by user.
sort id Sort list by any of the referral attributes.

Show an Referral

GET https://api.teamtailor.com/v1/referrals/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/referrals/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "id": "1",
  "type": "referrals",
  "links": {
    "self": "https://api.teamtailor.com/v1/referrals/1"
  },
  "attributes": {
    "comment": "Very nice person",
    "created-at": "2019-08-07T16:21:15.728+02:00",
    "email": "piotr@example.com",
    "name": "Piotr Klupa",
    "phone": null
  },
  "relationships": {
    "candidate": {
      "links": {
        "self": "https://api.teamtailor.com/v1/referrals/1/relationships/candidate",
        "related": "https://api.teamtailor.com/v1/referrals/1/candidate"
      }
    },
    "department": {
      "links": {
        "self": "https://api.teamtailor.com/v1/referrals/1/relationships/department",
        "related": "https://api.teamtailor.com/v1/referrals/1/department"
      }
    },
    "job": {
      "links": {
        "self": "https://api.teamtailor.com/v1/referrals/1/relationships/job",
        "related": "https://api.teamtailor.com/v1/referrals/1/job"
      }
    },
    "role": {
      "links": {
        "self": "https://api.teamtailor.com/v1/referrals/1/relationships/role",
        "related": "https://api.teamtailor.com/v1/referrals/1/role"
      }
    },
    "user": {
      "links": {
        "self": "https://api.teamtailor.com/v1/referrals/1/relationships/user",
        "related": "https://api.teamtailor.com/v1/referrals/1/user"
      }
    }
  }
}

Regions

Regions Object

{
  "id": "1",
  "type": "regions",
  "links": {
    "self": "https://api.teamtailor.com/v1/regions/1"
  },
  "attributes": {
    "name": "Europe",
    "created-at": "2019-08-07T16:21:15.728+02:00"
  },
  "relationships": {
    "locations": {
      "links": {
        "self": "https://api.teamtailor.com/v1/regions/1/relationships/locations",
        "related": "https://api.teamtailor.com/v1/regions/1/locations"
      }
    }
  }
}

Attributes

Attribute Type Description
name string Region’s name
created-at date

Relations

Relation Description
locations Locations on the region

List Regions

GET https://api.teamtailor.com/v1/regions HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/regions" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "1",
      "type": "regions",
      "links": {
        "self": "https://api.teamtailor.com/v1/regions/1"
      },
      "attributes": {
        "name": "Europe",
        "created-at": "2019-08-07T16:21:15.728+02:00"
      },
      "relationships": {
        "locations": {
          "links": {
            "self": "https://api.teamtailor.com/v1/regions/1/relationships/locations",
            "related": "https://api.teamtailor.com/v1/regions/1/locations"
          }
        }
      }
    }
  ],
  "meta": {
    "record-count": 20,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/regions?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "next": "https://api.teamtailor.com/v1/regions?page%5Bnumber%5D=2&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/regions?page%5Bnumber%5D=3&page%5Bsize%5D=10"
  }
}

Show a Region

GET https://api.teamtailor.com/v1/regions/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/regions/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "id": "1",
  "type": "regions",
  "links": {
    "self": "https://api.teamtailor.com/v1/regions/1"
  },
  "attributes": {
    "name": "Europe",
    "created-at": "2019-08-07T16:21:15.728+02:00"
  },
  "relationships": {
    "locations": {
      "links": {
        "self": "https://api.teamtailor.com/v1/regions/1/relationships/locations",
        "related": "https://api.teamtailor.com/v1/regions/1/locations"
      }
    }
  }
}

Reject Reasons

Reject Reason Object

{
  "id": "1",
  "type": "reject-reasons",
  "links": {
    "self": "https://api.teamtailor.com/v1/reject-reasons/1"
  },
  "attributes": {
    "reason": "Not a fit",
    "rejected-by-company": true
  },
  "relationships": {
    "job-applications": {
      "links": {
        "self": "https://api.teamtailor.com/v1/reject-reasons/1/relationships/job-applications",
        "related": "https://api.teamtailor.com/v1/reject-reasons/1/job-applications"
      }
    }
  }
}

Attributes

Attribute Type Description
reason string Reason why is being rejected
rejected-by-company boolean If true, the reason is coming from the company. Otherwise from the candidate

Relations

Relation Description
job-applications

List Reject Reasons

GET https://api.teamtailor.com/v1/reject-reasons HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/reject-reasons" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "1",
      "type": "reject-reasons",
      "links": {
        "self": "https://api.teamtailor.com/v1/reject-reasons/1"
      },
      "attributes": {
        "reason": "Not a fit",
        "rejected-by-company": true
          },
      "relationships": {
        "job-applications": {
          "links": {
            "self": "https://api.teamtailor.com/v1/reject-reasons/1/relationships/job-applications",
            "related": "https://api.teamtailor.com/v1/reject-reasons/1/job-applications"
          }
        }
      }
    }
  ],
  "meta": {
    "record-count": 1,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/todos?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/todos?page%5Bnumber%5D=1&page%5Bsize%5D=10"
  }
}

Show a Reject Reason

GET https://api.teamtailor.com/v1/reject-reasons/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/reject-reasons/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "1",
    "type": "reject-reasons",
    "links": {
      "self": "https://api.teamtailor.com/v1/reject-reasons/1"
    },
    "attributes": {
      "reason": "Not a fit",
      "rejected-by-company": true
    },
    "relationships": {
      "job-applications": {
        "links": {
          "self": "https://api.teamtailor.com/v1/reject-reasons/1/relationships/job-applications",
          "related": "https://api.teamtailor.com/v1/reject-reasons/1/job-applications"
        }
      }
    }
  }
}

Update Reject Reason

PATCH https://api.teamtailor.com/v1/reject-reasons/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
{
  "type": "reject-reasons"
  "data": {
    "id": "1",
    "attributes": {
      "rejected-by-company": false
    }
  }
}
curl -X "PATCH" "https://api.teamtailor.com/v1/reject-reasons/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
     -H "Content-Type: application/vnd.api+json" \
     -d "{\"data\":{\"id\":\"1\",\"attributes\":{\"rejected-by-company\":false},\"type\":\"reject-reasons\"}}"

Example response

{
  "data": {
    "id": "1",
    "type": "reject-reasons",
    "links": {
      "self": "https://api.teamtailor.com/v1/reject-reasons/1"
    },
    "attributes": {
      "reason": "Not a fit",
      "rejected-by-company": false
    },
    "relationships": {
      "job-applications": {
        "links": {
          "self": "https://api.teamtailor.com/v1/reject-reasons/1/relationships/job-applications",
          "related": "https://api.teamtailor.com/v1/reject-reasons/1/job-applications"
        }
      }
    }
  }
}

Create Reject reason

POST https://api.teamtailor.com/v1/reject-reasons HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{
  "data": {
    "type": "reject-reasons",
    "attributes": {
      "reason": "Not a fit",
      "rejected-by-company": true
    }
  }
}
curl -X "POST" "https://api.teamtailor.com/v1/reject-reasons" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
     -H "Content-Type: application/vnd.api+json" \
     -d "{\"data\":{\"type\":\"reject-reasons\",\"attributes\":{\"reason\":\"Not a fit\", \"rejected-by-company\":true}}}

Example response

{
  "data": {
    "id": "2",
    "type": "reject-reasons",
    "links": {
      "self": "https://api.teamtailor.com/v1/reject-reasons/2"
    },
    "attributes": {
      "reason": "Not a fit",
      "rejected-by-company": true
    },
    "relationships": {
      "job-applications": {
        "links": {
          "self": "https://api.teamtailor.com/v1/reject-reasons/2/relationships/job-applications",
          "related": "https://api.teamtailor.com/v1/reject-reasons/2/job-applications"
        }
      }
    }
  }
}

Delete Reject Reason

DELETE https://api.teamtailor.com/v1/reject-reasons/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "DELETE" "https://api.teamtailor.com/v1/reject-reasons/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Requisitions

Requisition Object

{
  "id": "1",
  "type": "requisitions",
  "links": {
    "self": "https://api.teamtailor.com/v1/requisitions/1"
  },
  "attributes": {
    "job-title": "Backend developer",
    "job-description": "We need someone to refactor our API endpoints",
    "country": "Sweden",
    "min-salary": 30000,
    "max-salary": 35000,
    "currency": "SEK",
    "salary-time-unit": "monthly",
    "number-of-openings": 1,
    "custom-form-answers": {
      "division": "Europe",
      "comments": "We should make sure that the applicant is familiar with the Go programming language"
    },
    "requisition-status": "pending"
  },
  "relationships": {
    "location": {
      "links": {
        "self": "https://api.teamtailor.com/v1/requisitions/1/relationships/location",
        "related": "https://api.teamtailor.com/v1/requisitions/1/location"
      }
    },
    "department": {
      "links": {
        "self": "https://api.teamtailor.com/v1/requisitions/1/relationships/department",
        "related": "https://api.teamtailor.com/v1/requisitions/1/department"
      }
    },
    "role": {
      "links": {
        "self": "https://api.teamtailor.com/v1/requisitions/1/relationships/role",
        "related": "https://api.teamtailor.com/v1/requisitions/1/role"
      }
    },
    "recruiter": {
      "links": {
        "self": "https://api.teamtailor.com/v1/requisitions/1/relationships/recruiter",
        "related": "https://api.teamtailor.com/v1/requisitions/1/recruiter"
      }
    },
    "requisition-step-verdicts": {
      "links": {
        "self": "https://api.teamtailor.com/v1/requisitions/1/relationships/requisition-step-verdicts",
        "related": "https://api.teamtailor.com/v1/requisitions/1/requisition-step-verdicts"
      }
    }
  }
}

Attributes

Attribute Type Description
job-title string
job-description string
country string
min-salary integer
max-salary integer
currency string The currency that the salary is set in
salary-time-unit string “monthly” / “yearly” / “hourly”
number-of-openings integer The number of people expected to be hired
custom-form-answers JSON A list of key-value pairs. This will only have a value if the company has actively created a custom form in their requisition settings
requisition-status string “pending” / “rejected” / “approved” / “archived” / “completed”

Relations

Relation Description
location
department
role
recruiter A user object
requisition-step-verdicts The verdict of each user involved in the requisition’s approval flow

List requisitions

GET https://api.teamtailor.com/v1/requisitions HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/requisitions" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
       "id": "1",
       "type": "requisitions",
       "links": {
         "self": "https://api.teamtailor.com/v1/requisitions/1"
       },
       "attributes": {
         "job-title": "Backend developer",
         "job-description": "We need someone to refactor our API endpoints",
         "country": "Sweden",
         "min-salary": 30000,
         "max-salary": 35000,
         "currency": "SEK",
         "salary-time-unit": "monthly",
         "number-of-openings": 1,
         "custom-form-answers": {
           "division": "Europe",
           "comments": "We should make sure that the applicant is familiar with the Go programming language"
         },
         "requisition-status": "pending"
       },
       "relationships": {
         "location": {
           "links": {
             "self": "https://api.teamtailor.com/v1/requisitions/1/relationships/location",
             "related": "https://api.teamtailor.com/v1/requisitions/1/location"
           }
         },
         "department": {
           "links": {
             "self": "https://api.teamtailor.com/v1/requisitions/1/relationships/department",
             "related": "https://api.teamtailor.com/v1/requisitions/1/department"
           }
         },
         "role": {
           "links": {
             "self": "https://api.teamtailor.com/v1/requisitions/1/relationships/role",
             "related": "https://api.teamtailor.com/v1/requisitions/1/role"
           }
         },
         "recruiter": {
           "links": {
             "self": "https://api.teamtailor.com/v1/requisitions/1/relationships/recruiter",
             "related": "https://api.teamtailor.com/v1/requisitions/1/recruiter"
           }
         },
         "requisition-step-verdicts": {
           "links": {
             "self": "https://api.teamtailor.com/v1/requisitions/1/relationships/requisition-step-verdicts",
             "related": "https://api.teamtailor.com/v1/requisitions/1/requisition-step-verdicts"
           }
         }
       }
     }
  ]
}

Use this endpoint to retrieve lists of requisitions.

Show a requisition

GET https://api.teamtailor.com/v1/requisitions/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/requisitions/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
     "id": "1",
     "type": "requisitions",
     "links": {
       "self": "https://api.teamtailor.com/v1/requisitions/1"
     },
     "attributes": {
       "job-title": "Backend developer",
       "job-description": "We need someone to refactor our API endpoints",
       "country": "Sweden",
       "min-salary": 30000,
       "max-salary": 35000,
       "currency": "SEK",
       "salary-time-unit": "monthly",
       "number-of-openings": 1,
       "custom-form-answers": {
         "division": "Europe",
         "comments": "We should make sure that the applicant is familiar with the Go programming language"
       },
       "requisition-status": "pending"
     },
     "relationships": {
       "location": {
         "links": {
           "self": "https://api.teamtailor.com/v1/requisitions/1/relationships/location",
           "related": "https://api.teamtailor.com/v1/requisitions/1/location"
         }
       },
       "department": {
         "links": {
           "self": "https://api.teamtailor.com/v1/requisitions/1/relationships/department",
           "related": "https://api.teamtailor.com/v1/requisitions/1/department"
         }
       },
       "role": {
         "links": {
           "self": "https://api.teamtailor.com/v1/requisitions/1/relationships/role",
           "related": "https://api.teamtailor.com/v1/requisitions/1/role"
         }
       },
       "recruiter": {
         "links": {
           "self": "https://api.teamtailor.com/v1/requisitions/1/relationships/recruiter",
           "related": "https://api.teamtailor.com/v1/requisitions/1/recruiter"
         }
       },
       "requisition-step-verdicts": {
         "links": {
           "self": "https://api.teamtailor.com/v1/requisitions/1/relationships/requisition-step-verdicts",
           "related": "https://api.teamtailor.com/v1/requisitions/1/requisition-step-verdicts"
         }
       }
     }
  }
}

Use this endpoint to retrieve a specific requisition.

Requisition Step Verdicts

Requisition Step Verdict Object

{
  "id": "1",
  "type": "requisition-step-verdicts",
  "links": {
    "self": "https://api.teamtailor.com/v1/requisition-step-verdicts/1"
  },
  "attributes": {
    "status": "rejected",
    "requisition-step-index": 0,
    "updated-at": "2019-11-06T15:43:11.043+01:00"
  },
  "relationships": {
    "user": {
      "links": {
        "self": "https://api.teamtailor.com/v1/requisition-step-verdicts/1/relationships/user",
        "related": "https://api.teamtailor.com/v1/requisition-step-verdicts/1/user"
      }
    }
  }
}

Show a requisition step verdict

GET https://api.teamtailor.com/v1/requisition-step-verdicts/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/requisition-step-verdicts/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "1",
    "type": "requisition-step-verdicts",
    "links": {
      "self": "https://api.teamtailor.com/v1/requisition-step-verdicts/1"
    },
    "attributes": {
      "status": "rejected",
      "requisition-step-index": 0,
      "updated-at": "2019-11-06T15:43:11.043+01:00"
    },
    "relationships": {
      "user": {
        "links": {
          "self": "https://api.teamtailor.com/v1/requisition-step-verdicts/1/relationships/user",
          "related": "https://api.teamtailor.com/v1/requisition-step-verdicts/1/user"
        }
      }
    }
  }
}

Update a requisition step verdict

PATCH https://api.teamtailor.com/v1/requisition-step-verdicts/1 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{
  "data": {
    "type": "requisition-step-verdicts",
    "id": "1",
    "attributes": {
      "status": "approved"
    }
  }
}
curl -X "PATCH" "https://api.teamtailor.com/v1/requisition-step-verdicts/1" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
     -H "Content-Type: application/vnd.api+json" \
     -d "{\"data\":{\"id\":\"1\",\"attributes\":{\"status\":\"approved\"},\"type\":\"requisition-step-verdicts\"}}"

Example response

{
  "data": {
    "id": "1",
    "type": "requisition-step-verdicts",
    "links": {
      "self": "https://api.teamtailor.com/v1/requisition-step-verdicts/1"
    },
    "attributes": {
      "status": "approved",
      "requisition-step-index": 0,
      "updated-at": "2019-11-06T15:43:11.043+01:00"
    },
    "relationships": {
      "user": {
        "links": {
          "self": "https://api.teamtailor.com/v1/requisition-step-verdicts/1/relationships/user",
          "related": "https://api.teamtailor.com/v1/requisition-step-verdicts/1/user"
        }
      }
    }
  }
}

Roles

Role Object

{
  "data": {
    "id": "8",
    "type": "roles",
    "links": {
      "self": "https://api.teamtailor.com/v1/roles/8"
    },
    "attributes": {
      "name": "Designer"
    },
    "relationships": {
      "department": {
        "links": {
          "self": "https://api.teamtailor.com/v1/roles/8/relationships/department",
          "related": "https://api.teamtailor.com/v1/roles/8/department"
        }
      },
      "teams": {
        "links": {
          "self": "https://api.teamtailor.com/v1/roles/8/relationships/teams",
          "related": "https://api.teamtailor.com/v1/roles/8/teams"
        }
      }
    }
  }
}

Attributes

Attribute Type Description
name string The name of the role

Relations

Relation Description
department Parent Department
teams The teams this role is part of

List roles

GET https://api.teamtailor.com/v1/roles HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/roles" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "8",
      "type": "roles",
      "links": {
        "self": "https://api.teamtailor.com/v1/roles/8"
      },
      "attributes": {
        "name": "Designer"
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/roles/8/relationships/department",
            "related": "https://api.teamtailor.com/v1/roles/8/department"
          }
        },
        "teams": {
          "links": {
            "self": "https://api.teamtailor.com/v1/roles/8/relationships/teams",
            "related": "https://api.teamtailor.com/v1/roles/8/teams"
          }
        }
      }
    },
    {
      "id": "9",
      "type": "roles",
      "links": {
        "self": "https://api.teamtailor.com/v1/roles/9"
      },
      "attributes": {
        "name": "Developer"
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/roles/9/relationships/department",
            "related": "https://api.teamtailor.com/v1/roles/9/department"
          }
        },
        "teams": {
          "links": {
            "self": "https://api.teamtailor.com/v1/roles/9/relationships/teams",
            "related": "https://api.teamtailor.com/v1/roles/9/teams"
          }
        }
      }
    }
  ],
  "meta": {
    "record-count": 2,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/roles?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/roles?page%5Bnumber%5D=1&page%5Bsize%5D=10"
  }
}

Show a Role

GET https://api.teamtailor.com/v1/roles/8 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/roles/8" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "8",
    "type": "roles",
    "links": {
      "self": "https://api.teamtailor.com/v1/roles/8"
    },
    "attributes": {
      "name": "Designer"
    },
    "relationships": {
      "department": {
        "links": {
          "self": "https://api.teamtailor.com/v1/roles/8/relationships/department",
          "related": "https://api.teamtailor.com/v1/roles/8/department"
        }
      },
      "teams": {
        "links": {
          "self": "https://api.teamtailor.com/v1/roles/8/relationships/teams",
          "related": "https://api.teamtailor.com/v1/roles/8/teams"
        }
      }
    }
  }
}

Create roles

POST https://api.teamtailor.com/v1/roles HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{"data":{"type":"roles","attributes":{"name":"Front-end developer"}}}

Example response

{
  "data": {
    "id": "10",
    "type": "roles",
    "links": {
      "self": "https://api.teamtailor.com/v1/roles/10"
    },
    "attributes": {
      "name": "Front-end developer"
    },
    "relationships": {
      "department": {
        "links": {
          "self": "https://api.teamtailor.com/v1/roles/10/relationships/department",
          "related": "https://api.teamtailor.com/v1/roles/10/department"
        }
      },
      "teams": {
        "links": {
          "self": "https://api.teamtailor.com/v1/roles/10/relationships/teams",
          "related": "https://api.teamtailor.com/v1/roles/10/teams"
        }
      }
    }
  }
}

Delete roles

DELETE https://api.teamtailor.com/v1/roles/5 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

Stages

A stage indicate the candidate status for a job-application. The stages are defined for each job. Each job has two default stages which can’t be deleted or modified:

All other user created stages have the stage-type In process

Stage Object

{
  "id": "22505",
  "type": "stages",
  "links": {
    "self": "https://api.teamtailor.com/v1/stages/22505"
  },
  "attributes": {
    "created-at": "2015-11-05T20:12:27.984+01:00",
    "updated-at": "2015-11-06T10:02:57.452+01:00",
    "name": "Inbox",
    "stage-type": "Inbox",
    "row-order": -4194303,
    "active-job-applications-count": 7,
    "rejected-job-applications-count": 2
  },
  "relationships": {
    "job-applications": {
      "links": {
        "self": "https://api.teamtailor.com/v1/stages/22505/relationships/job-applications",
        "related": "https://api.teamtailor.com/v1/stages/22505/job-applications"
      }
    },
    "triggers": {
      "links": {
        "self": "https://api.teamtailor.com/v1/stages/22505/relationships/triggers",
        "related": "https://api.teamtailor.com/v1/stages/22505/triggers"
      }
    },
    "job": {
      "links": {
        "self": "https://api.teamtailor.com/v1/stages/22505/relationships/job",
        "related": "https://api.teamtailor.com/v1/stages/22505/job"
      }
    }
  }
}

Attributes

Attribute Type Description
created-at date
updated-at date
name string
stage-type string Possible values: Inbox, In process, Hired
row-order integer Value stages are manually sorted by in Teamtailor
active-job-applications-count integer Number of active applications in the stage
rejected-job-applications-count integer Number of rejected applications in the stage

Relations

Relation
job-applications
job
triggers

Show a stage

GET https://api.teamtailor.com/v1/stages/22505 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/stages/22505" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "22505",
    "type": "stages",
    "links": {
      "self": "https://api.teamtailor.com/v1/stages/22505"
    },
    "attributes": {
      "created-at": "2015-11-05T20:12:27.984+01:00",
      "updated-at": "2015-11-06T10:02:57.452+01:00",
      "name": "Inbox",
      "stage-type": "Inbox",
      "row-order": -4194303,
      "active-job-applications-count": 12,
      "rejected-job-applications-count": 32
    },
    "relationships": {
      "job-applications": {
        "links": {
          "self": "https://api.teamtailor.com/v1/stages/22505/relationships/job-applications",
          "related": "https://api.teamtailor.com/v1/stages/22505/job-applications"
        }
      },
      "triggers": {
        "links": {
          "self": "https://api.teamtailor.com/v1/stages/22505/relationships/triggers",
          "related": "https://api.teamtailor.com/v1/stages/22505/triggers"
        }
      },
      "job": {
        "links": {
          "self": "https://api.teamtailor.com/v1/stages/22505/relationships/job",
          "related": "https://api.teamtailor.com/v1/stages/22505/job"
        }
      }
    }
  }
}

Use this endpoint to retrieve a specific stage.

Example parameters

Parameter Default Description
include null Comma separated list of relations to include in the response. For example job-applications.

List stages

GET https://api.teamtailor.com/v1/stages HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/stages" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "22505",
      "type": "stages",
      "links": {
        "self": "https://api.teamtailor.com/v1/stages/22505"
      },
      "attributes": {
        "created-at": "2015-11-05T20:12:27.984+01:00",
        "updated-at": "2015-11-06T10:02:57.452+01:00",
        "name": "Inbox",
        "stage-type": "Inbox",
        "row-order": -4194303,
        "active-job-applications-count": 7,
        "rejected-job-applications-count": 0
      },
      "relationships": {
        "job-applications": {
          "links": {
            "self": "https://api.teamtailor.com/v1/stages/22505/relationships/job-applications",
            "related": "https://api.teamtailor.com/v1/stages/22505/job-applications"
          }
        },
        "triggers": {
          "links": {
            "self": "https://api.teamtailor.com/v1/stages/22505/relationships/triggers",
            "related": "https://api.teamtailor.com/v1/stages/22505/triggers"
          }
        },
        "job": {
          "links": {
            "self": "https://api.teamtailor.com/v1/stages/22505/relationships/job",
            "related": "https://api.teamtailor.com/v1/stages/22505/job"
          }
        }
      }
    },
    {
      "id": "22508",
      "type": "stages",
      "links": {
        "self": "https://api.teamtailor.com/v1/stages/22508"
      },
      "attributes": {
        "created-at": "2015-11-05T20:12:28.038+01:00",
        "updated-at": "2015-11-06T10:02:57.492+01:00",
        "name": "Reviewing",
        "stage-type": "In process",
        "row-order": 4194304,
        "active-job-applications-count": 3,
        "rejected-job-applications-count": 12
      },
      "relationships": {
        "job-applications": {
          "links": {
            "self": "https://api.teamtailor.com/v1/stages/22508/relationships/job-applications",
            "related": "https://api.teamtailor.com/v1/stages/22508/job-applications"
          }
        },
        "triggers": {
          "links": {
            "self": "https://api.teamtailor.com/v1/stages/22508/relationships/triggers",
            "related": "https://api.teamtailor.com/v1/stages/22508/triggers"
          }
        },
        "job": {
          "links": {
            "self": "https://api.teamtailor.com/v1/stages/22508/relationships/job",
            "related": "https://api.teamtailor.com/v1/stages/22508/job"
          }
        }
      }
    }
  ],
  "meta": {
    "record-count": 2,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/jobs/1426/stages?page%5Bnumber%5D=1\u0026page%5Bsize%5D=10\u0026sort=row_order",
    "last": "https://api.teamtailor.com/v1/jobs/1426/stages?page%5Bnumber%5D=1\u0026page%5Bsize%5D=10\u0026sort=row_order"
  }
}

Use this endpoint to retrieve lists of stages.

Example parameters

Parameter Default Description
include null Comma separated list of relations to include in the response. For example job-applications.
sort id Sort list by any of the stage attributes. Note! Use row-order to sort as in Teamtailor, but only when in the scope of a job.

Teams

Use teams to customize your users access to candidates and jobs.

Read more about how to use Teams

Team Object

{
  "data": {
    "id": "189",
    "type": "teams",
    "links": {
      "self": "https://api.teamtailor.com/v1/teams/189"
    },
    "attributes": {
      "name": "Product Development",
      "emoji": "👩‍💻",
      "no-department": false
    },
    "relationships": {
      "user": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/user",
          "related": "https://api.teamtailor.com/v1/teams/189/user"
        }
      },
      "users": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/users",
          "related": "https://api.teamtailor.com/v1/teams/189/users"
        }
      },
      "departments": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/departments",
          "related": "https://api.teamtailor.com/v1/teams/189/departments"
        }
      },
      "locations": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/locations",
          "related": "https://api.teamtailor.com/v1/teams/189/locations"
        }
      },
      "roles": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/roles",
          "related": "https://api.teamtailor.com/v1/teams/189/roles"
        }
      }
    }
  }
}

Attributes

Attribute Type Description
name string The team name
emoji string The team icon
no-department boolean true if the team have access to candidates without department. Default: false.

Relations

Relation Description
user The team mananger
users The team members
departments The departments the team has access to
roles The roles the team has access to
locations The locations the team access is limited to

List teams

GET https://api.teamtailor.com/v1/teams HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/teams" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "189",
      "type": "teams",
      "links": {
        "self": "https://api.teamtailor.com/v1/teams/189"
      },
      "attributes": {
        "name": "Product Development",
        "emoji": "👩‍💻",
        "no-department": false
      },
      "relationships": {
        "user": {
          "links": {
            "self": "https://api.teamtailor.com/v1/teams/189/relationships/user",
            "related": "https://api.teamtailor.com/v1/teams/189/user"
          }
        },
        "users": {
          "links": {
            "self": "https://api.teamtailor.com/v1/teams/189/relationships/users",
            "related": "https://api.teamtailor.com/v1/teams/189/users"
          }
        },
        "departments": {
          "links": {
            "self": "https://api.teamtailor.com/v1/teams/189/relationships/departments",
            "related": "https://api.teamtailor.com/v1/teams/189/departments"
          }
        },
        "locations": {
          "links": {
            "self": "https://api.teamtailor.com/v1/teams/189/relationships/locations",
            "related": "https://api.teamtailor.com/v1/teams/189/locations"
          }
        },
        "roles": {
          "links": {
            "self": "https://api.teamtailor.com/v1/teams/189/relationships/roles",
            "related": "https://api.teamtailor.com/v1/teams/189/roles"
          }
        }
      }
    },
    
  ]
  "meta": {
    "record-count": 2,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/teams?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/teams?page%5Bnumber%5D=1&page%5Bsize%5D=10"
  }
}

Show a Team

GET https://api.teamtailor.com/v1/teams/189 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/teams/189" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "189",
    "type": "teams",
    "links": {
      "self": "https://api.teamtailor.com/v1/teams/189"
    },
    "attributes": {
      "name": "Product Development",
      "emoji": "👩‍💻",
      "no-department": false
    },
    "relationships": {
      "user": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/user",
          "related": "https://api.teamtailor.com/v1/teams/189/user"
        }
      },
      "users": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/users",
          "related": "https://api.teamtailor.com/v1/teams/189/users"
        }
      },
      "departments": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/departments",
          "related": "https://api.teamtailor.com/v1/teams/189/departments"
        }
      },
      "locations": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/locations",
          "related": "https://api.teamtailor.com/v1/teams/189/locations"
        }
      },
      "roles": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/roles",
          "related": "https://api.teamtailor.com/v1/teams/189/roles"
        }
      }
    }
  }
}

Update teams

PATCH https://api.teamtailor.com/v1/teams/189 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{"data":{"id":"189","type":"teams","attributes":{"name":"Front-end team"}}}

Example response

{
  "data": {
    "id": "189",
    "type": "teams",
    "links": {
      "self": "https://api.teamtailor.com/v1/teams/189"
    },
    "attributes": {
      "name": "Front-end team",
      "emoji": "👩‍💻",
      "no-department": false
    },
    "relationships": {
      "user": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/user",
          "related": "https://api.teamtailor.com/v1/teams/189/user"
        }
      },
      "users": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/users",
          "related": "https://api.teamtailor.com/v1/teams/189/users"
        }
      },
      "departments": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/departments",
          "related": "https://api.teamtailor.com/v1/teams/189/departments"
        }
      },
      "locations": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/locations",
          "related": "https://api.teamtailor.com/v1/teams/189/locations"
        }
      },
      "roles": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/roles",
          "related": "https://api.teamtailor.com/v1/teams/189/roles"
        }
      }
    }
  }
}

Create teams

POST https://api.teamtailor.com/v1/teams HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{"data":{"type":"teams","attributes":{"name":"Product Development","emoji": "👩‍💻"},"relationships":{"user":{"data":{"type":"users","id": "2199"}}}}

Example response

{
  "data": {
    "id": "189",
    "type": "teams",
    "links": {
      "self": "https://api.teamtailor.com/v1/teams/189"
    },
    "attributes": {
      "name": "Product Development",
      "emoji": "👩‍💻",
      "no-department": false
    },
    "relationships": {
      "user": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/user",
          "related": "https://api.teamtailor.com/v1/teams/189/user"
        }
      },
      "users": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/users",
          "related": "https://api.teamtailor.com/v1/teams/189/users"
        }
      },
      "departments": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/departments",
          "related": "https://api.teamtailor.com/v1/teams/189/departments"
        }
      },
      "locations": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/locations",
          "related": "https://api.teamtailor.com/v1/teams/189/locations"
        }
      },
      "roles": {
        "links": {
          "self": "https://api.teamtailor.com/v1/teams/189/relationships/roles",
          "related": "https://api.teamtailor.com/v1/teams/189/roles"
        }
      }
    }
  }
}

Delete teams

DELETE https://api.teamtailor.com/v1/teams/5 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

Team memberships (Hiring teams)

This object represents the team memberships of a job or team.

Team Membership Object

{
  "data": {
    "id": "21",
    "type": "team-memberships",
    "links": {
      "self": "https://api.teamtailor.com/v1/team-memberships/21"
    },
    "relationships": {
      "user": {
        "links": {
          "self": "https://api.teamtailor.com/v1/team-memberships/21/relationships/user",
          "related": "https://api.teamtailor.com/v1/team-memberships/21/user"
        }
      },
      "team": {
        "links": {
          "self": "https://api.teamtailor.com/v1/team-memberships/21/relationships/team",
          "related": "https://api.teamtailor.com/v1/team-memberships/21/team"
        }
      }
    }
  }
}

Attributes

The team-membership object has no attributes.

Relations

The team-membership object always has a relation to a user and a team, which is either a job or team.

Relation Description
user One of your company’s registered users.
team Either a Team or a Job.

List Team Memberships

GET https://api.teamtailor.com/v1/team-memberships HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/team-memberships" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "7",
      "type": "team-memberships",
      "links": {
        "self": "https://api.teamtailor.com/v1/team-memberships/7"
      },
      "relationships": {
        "user": {
          "links": {
            "self": "https://api.teamtailor.com/v1/team-memberships/7/relationships/user",
            "related": "https://api.teamtailor.com/v1/team-memberships/7/user"
          }
        },
        "team": {
          "links": {
            "self": "https://api.teamtailor.com/v1/team-memberships/7/relationships/team",
            "related": "https://api.teamtailor.com/v1/team-memberships/7/team"
          }
        }
      }
    },
    {
      "id": "8",
      "type": "team-memberships",
      "links": {
        "self": "https://api.teamtailor.com/v1/team-memberships/8"
      },
      "relationships": {
        "user": {
          "links": {
            "self": "https://api.teamtailor.com/v1/team-memberships/8/relationships/user",
            "related": "https://api.teamtailor.com/v1/team-memberships/8/user"
          }
        },
        "team": {
          "links": {
            "self": "https://api.teamtailor.com/v1/team-memberships/8/relationships/team",
            "related": "https://api.teamtailor.com/v1/team-memberships/8/team"
          }
        }
      }
    }
  ],
  "meta": {
      "record-count": 2,
      "page-count": 1
  },
  "links": {
      "first": "https://api.teamtailor.com/v1/team-memberships?page%5Bnumber%5D=1&page%5Bsize%5D=3",
      "last": "https://api.teamtailor.com/v1/team-memberships?page%5Bnumber%5D=1&page%5Bsize%5D=3"
  }
}

Use this endpoint to retrieve lists of team memberships.

Example parameters

Parameter Default Description
include null Comma separated list of relations to include in the response. For example user,team

Show a Team Membership

GET https://api.teamtailor.com/v1/team-memberships/21 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/team-memberships/21" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "21",
    "type": "team-memberships",
    "links": {
      "self": "https://api.teamtailor.com/v1/team-memberships/21"
    },
    "relationships": {
      "user": {
        "links": {
          "self": "https://api.teamtailor.com/v1/team-memberships/21/relationships/user",
          "related": "https://api.teamtailor.com/v1/team-memberships/21/user"
        }
      },
      "team": {
        "links": {
          "self": "https://api.teamtailor.com/v1/team-memberships/21/relationships/team",
          "related": "https://api.teamtailor.com/v1/team-memberships/21/team"
        }
      }
    }
  }
}

Create Hiring Team / Add Team Member

POST https://api.teamtailor.com/v1/team-memberships HTTP/1.1

X-Api-Version: 20161108
Authorization: Token token=abc123abc123

{
  "data": {
    "type": "team-memberships",
    "relationships": {
      "team": {
        "data": {
          "id": "17",
          "type": "teams"
        }
      },
      "user": {
        "data": {
          "id": "3",
          "type": "users"
        }
      }
    }
  }
}

## create Team Membership
curl -X "POST" "https://api.teamtailor.com/v1/team-memberships" \
     -H "Content-Type: application/vnd.api+json" \
     -H "X-Api-Version: 20161108" \
     -H "Authorization: Token token=abc123abc123" \
     -d $'{
   "data": {
     "type": "team-memberships",
     "relationships": {
      "team": {
        "data": {
          "id": "17",
          "type": "teams"
        }
      },
       "user": {
         "data": {
           "id": "3",
           "type": "users"
         }
       }
     }
   }
 }'

Example response

{
  "data": {
    "id": "21",
    "type": "team-memberships",
    "links": {
      "self": "https://api.teamtailor.com/v1/team-memberships/21"
    },
    "relationships": {
      "user": {
        "links": {
          "self": "https://api.teamtailor.com/v1/team-memberships/21/relationships/user",
          "related": "https://api.teamtailor.com/v1/team-memberships/21/user"
        }
      },
      "team": {
        "links": {
          "self": "https://api.teamtailor.com/v1/team-memberships/21/relationships/team",
          "related": "https://api.teamtailor.com/v1/team-memberships/21/team"
        }
      }
    }
  }
}

Create a new Team Membership.

Delete Team Membership

DELETE https://api.teamtailor.com/v1/team-memberships/21 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "DELETE" "https://api.teamtailor.com/v1/team-memberships/21" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Delete a team membership, i.e. remove a user from a hiring team.

Todos

Todo Object

{
  "id": "15",
  "type": "todos",
  "links": {
    "self": "https://api.teamtailor.com/v1/todos/15"
  },
  "attributes": {
    "completed-at": null,
    "created-at": "2019-07-30T15:14:09.311+02:00",
    "due": "2019-08-13",
    "value": "Arrange an interview with him"
  },
  "relationships": {
    "assignee": {
      "links": {
        "self": "https://api.teamtailor.com/v1/todos/15/relationships/assignee",
        "related": "https://api.teamtailor.com/v1/todos/15/assignee"
      }
    },
    "assigner": {
      "links": {
        "self": "https://api.teamtailor.com/v1/todos/15/relationships/assigner",
        "related": "https://api.teamtailor.com/v1/todos/15/assigner"
      }
    },
    "candidate": {
      "links": {
        "self": "https://api.teamtailor.com/v1/todos/15/relationships/candidate",
        "related": "https://api.teamtailor.com/v1/todos/15/candidate"
      }
    },
    "user": {
      "links": {
        "self": "https://api.teamtailor.com/v1/todos/15/relationships/user",
        "related": "https://api.teamtailor.com/v1/todos/15/user"
      }
    }
  }
}

Attributes

Attribute Type Description
completed-at date Date of completion
created-at date
due date Due date
value string Text value

Relations

Relation Description
assignee User who is assigned to the todo
assigner User who assigned the todo
candidate Candidate which the todo concerns
user User who creates the todo

List Todos

GET https://api.teamtailor.com/v1/todos HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/todos" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "15",
      "type": "todos",
      "links": {
        "self": "https://api.teamtailor.com/v1/todos/15"
      },
      "attributes": {
        "completed-at": null,
        "created-at": "2019-07-30T15:14:09.311+02:00",
        "due": "2019-08-13",
        "value": "Arrange an interview with him"
      },
      "relationships": {
        "assignee": {
          "links": {
            "self": "https://api.teamtailor.com/v1/todos/15/relationships/assignee",
            "related": "https://api.teamtailor.com/v1/todos/15/assignee"
          }
        },
        "assigner": {
          "links": {
            "self": "https://api.teamtailor.com/v1/todos/15/relationships/assigner",
            "related": "https://api.teamtailor.com/v1/todos/15/assigner"
          }
        },
        "candidate": {
          "links": {
            "self": "https://api.teamtailor.com/v1/todos/15/relationships/candidate",
            "related": "https://api.teamtailor.com/v1/todos/15/candidate"
          }
        },
        "user": {
          "links": {
            "self": "https://api.teamtailor.com/v1/todos/15/relationships/user",
            "related": "https://api.teamtailor.com/v1/todos/15/user"
          }
        }
      }
    },
    
  ],
  "meta": {
    "record-count": 20,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/todos?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "next": "https://api.teamtailor.com/v1/todos?page%5Bnumber%5D=2&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/todos?page%5Bnumber%5D=2&page%5Bsize%5D=10"
  }
}

Example parameters

Parameter Default Description
include null Comma separated list of relations to include in the response. For example assigne,assigner,candidate,user.
filter[assignee] null Filter by assignee.
filter[assigner] null Filter by assigner.
filter[candidate] null Filter by candidate.
filter[due] null Filter by due date.
filter[user] null Filter by user.
sort id Sort list by any of the todo attributes.

Show a Todo

GET https://api.teamtailor.com/v1/todos/15 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/todos/15" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "15",
    "type": "todos",
    "links": {
      "self": "https://api.teamtailor.com/v1/todos/15"
    },
    "attributes": {
      "completed-at": null,
      "created-at": "2019-07-30T15:14:09.311+02:00",
      "due": "2019-08-13",
      "value": "Arrange an interview with him"
    },
    "relationships": {
      "assignee": {
        "links": {
          "self": "https://api.teamtailor.com/v1/todos/15/relationships/assignee",
          "related": "https://api.teamtailor.com/v1/todos/15/assignee"
        }
      },
      "assigner": {
        "links": {
          "self": "https://api.teamtailor.com/v1/todos/15/relationships/assigner",
          "related": "https://api.teamtailor.com/v1/todos/15/assigner"
        }
      },
      "candidate": {
        "links": {
          "self": "https://api.teamtailor.com/v1/todos/15/relationships/candidate",
          "related": "https://api.teamtailor.com/v1/todos/15/candidate"
        }
      },
      "user": {
        "links": {
          "self": "https://api.teamtailor.com/v1/todos/15/relationships/user",
          "related": "https://api.teamtailor.com/v1/todos/15/user"
        }
      }
    }
  }
}

Update Todo

PATCH https://api.teamtailor.com/v1/todos/15 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{
  "data": {
    "id": "15",
    "attributes": {
      "due": "2019-08-15"
    },
    "type": "todos"
  }
}
curl -X "PATCH" "https://api.teamtailor.com/v1/todos/15" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
     -H "Content-Type: application/vnd.api+json" \
     -d "{\"data\":{\"id\":\"15\",\"attributes\":{\"due\":\"2019-08-15\"},\"type\":\"todos\"}}"

Example response

{
  "data": {
    "id": "15",
    "type": "todos",
    "links": {
      "self": "https://api.teamtailor.com/v1/todos/15"
    },
    "attributes": {
      "completed-at": null,
      "created-at": "2019-07-30T15:14:09.311+02:00",
      "due": "2019-08-15",
      "value": "Arrange an interview with him"
    },
    "relationships": {
      "assignee": {
        "links": {
          "self": "https://api.teamtailor.com/v1/todos/15/relationships/assignee",
          "related": "https://api.teamtailor.com/v1/todos/15/assignee"
        }
      },
      "assigner": {
        "links": {
          "self": "https://api.teamtailor.com/v1/todos/15/relationships/assigner",
          "related": "https://api.teamtailor.com/v1/todos/15/assigner"
        }
      },
      "candidate": {
        "links": {
          "self": "https://api.teamtailor.com/v1/todos/15/relationships/candidate",
          "related": "https://api.teamtailor.com/v1/todos/15/candidate"
        }
      },
      "user": {
        "links": {
          "self": "https://api.teamtailor.com/v1/todos/15/relationships/user",
          "related": "https://api.teamtailor.com/v1/todos/15/user"
        }
      }
    }
  }
}

Create Todo

POST https://api.teamtailor.com/v1/todos HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{
  "data": {
    "type": "todos",
    "attributes": {
      "value": "Arrange an interview with him"
    },
    "relationships": {
      "candidate": {
        "data": {
          "id": 105,
          "type": "candidates"
        }
      },
      "user": {
        "data": {
          "id": 30,
          "type": "users"
        }
      },
      "assigner": {
        "data": {
          "id": 25,
          "type": "users"
        }
      },
      "assignee": {
        "data": {
          "id": 28,
          "type": "users"
        }
      }
    }
  }
}
curl -X "POST" "https://api.teamtailor.com/v1/todos" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
     -H "Content-Type: application/vnd.api+json" \
     -d "{\"data\":{\"type\":\"todos\",\"attributes\":{\"value\":\"Arrange an interview with him\"},\"relationships\":{\"candidate\":{\"data\":{\"id\":105,\"type\":\"candidates\"}},\"user\":{\"data\":{\"id\":30,\"type\":\"users\"}},\"assigner\":{\"data\":{\"id\":25,\"type\":\"users\"}},\"assignee\":{\"data\":{\"id\":28,\"type\":\"users\"}}}}}
"

Example response

{
  "data": {
    "id": "15",
    "type": "todos",
    "links": {
      "self": "https://api.teamtailor.com/v1/todos/15"
    },
    "attributes": {
      "completed-at": null,
      "created-at": "2019-07-30T15:14:09.311+02:00",
      "due": null,
      "value": "Arrange an interview with him"
    },
    "relationships": {
      "assignee": {
        "links": {
          "self": "https://api.teamtailor.com/v1/todos/15/relationships/assignee",
          "related": "https://api.teamtailor.com/v1/todos/15/assignee"
        }
      },
      "assigner": {
        "links": {
          "self": "https://api.teamtailor.com/v1/todos/15/relationships/assigner",
          "related": "https://api.teamtailor.com/v1/todos/15/assigner"
        }
      },
      "candidate": {
        "links": {
          "self": "https://api.teamtailor.com/v1/todos/15/relationships/candidate",
          "related": "https://api.teamtailor.com/v1/todos/15/candidate"
        }
      },
      "user": {
        "links": {
          "self": "https://api.teamtailor.com/v1/todos/15/relationships/user",
          "related": "https://api.teamtailor.com/v1/todos/15/user"
        }
      }
    }
  }
}

Delete Todo

DELETE https://api.teamtailor.com/v1/todos/15 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

Triggers

A trigger is created per stage to execute various actions on the candidates placed in the stage.

Trigger Object

{
  "id": "44",
  "type": "triggers",
  "links": {
    "self": "https://api.teamtailor.com/v1/triggers/44"
  },
  "attributes": {
    "created-at": "2019-05-02T11:50:05.939+02:00",
    "updated-at": "2019-05-02T11:50:05.939+02:00",
    "trigger-type": "Message",
    "data": "{\"subject\":\"Welcome for interview!\",\"body\":\"\Welcome to our office for interview...\",\"is_sms\":\"0\",\"fallback_sms_to_email\":\"0\"}"
  },
  "relationships": {
    "stage": {
      "links": {
        "self": "https://api.teamtailor.com/v1/triggers/44/relationships/stage",
        "related": "https://api.teamtailor.com/v1/triggers/44/stage"
      }
    }
  }
}

Attributes

Attribute Type Description
created-at date
updated-at date
trigger-type string Possible values: Assessment, Message, Note, Nps, Share, SmartMove, SmartSchedule, Tag, Todo, Webhook
data string Json string with trigger settings, specific to the trigger type.

Relations

Relation
stage

Show a trigger

GET https://api.teamtailor.com/v1/triggers/44 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/triggers/44" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "44",
    "type": "triggers",
    "links": {
      "self": "https://api.teamtailor.com/v1/triggers/44"
    },
    "attributes": {
      "created-at": "2019-05-02T11:50:05.939+02:00",
      "updated-at": "2019-05-02T11:50:05.939+02:00",
      "trigger-type": "Message",
      "data": "{\"subject\":\"ASD!\",\"body\":\"\\u003cp\\u003e-- \\u003cbr\\u003eRichard Johansson\\u003cbr\\u003eTeamtailor\\u003cbr\\u003e\\u003c/p\\u003e\",\"is_sms\":\"0\",\"fallback_sms_to_email\":\"0\"}"
    },
    "relationships": {
      "stage": {
        "links": {
          "self": "https://api.teamtailor.com/v1/triggers/44/relationships/stage",
          "related": "https://api.teamtailor.com/v1/triggers/44/stage"
        }
      }
    }
  }
}

Use this endpoint to retrieve a specific trigger.

List triggers

GET https://api.teamtailor.com/v1/triggers HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/triggers" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "1",
      "type": "triggers",
      "links": {
        "self": "https://api.teamtailor.com/v1/triggers/1"
      },
      "attributes": {
        "created-at": "2017-10-06T17:55:43.979+02:00",
        "updated-at": "2019-03-26T17:53:13.261+01:00",
        "trigger-type": "Tag",
        "data": "{\"tags\":[\"interesting\"]}"
      },
      "relationships": {
        "stage": {
          "links": {
            "self": "https://api.teamtailor.com/v1/triggers/1/relationships/stage",
            "related": "https://api.teamtailor.com/v1/triggers/1/stage"
          }
        }
      }
    },
    {
      "id": "2",
      "type": "triggers",
      "links": {
        "self": "https://api.teamtailor.com/v1/triggers/2"
      },
      "attributes": {
        "created-at": "2017-11-01T10:49:12.252+01:00",
        "updated-at": "2019-03-26T17:53:13.387+01:00",
        "trigger-type": "Share",
        "data": "{\"subject\":\"Please help me review candidates.\",\"body\":\"Hi!\\r\\n\\r\\nIf you have a moment, it would be great to hear your feedback on this candidate.\",\"emails\":\"john.doe@example.com\",\"share_options\":{\"pitch\":true,\"answers\":false,\"locations\":true,\"linked_in\":true,\"recommendations\":true,\"attachments\":true}}"
      },
      "relationships": {
        "stage": {
          "links": {
            "self": "https://api.teamtailor.com/v1/triggers/2/relationships/stage",
            "related": "https://api.teamtailor.com/v1/triggers/2/stage"
          }
        }
      }
    }
  ],
  "meta": {
    "record-count": 2,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/jobs/1426/triggers?page%5Bnumber%5D=1\u0026page%5Bsize%5D=10\u0026sort=row_order",
    "last": "https://api.teamtailor.com/v1/jobs/1426/triggers?page%5Bnumber%5D=1\u0026page%5Bsize%5D=10\u0026sort=row_order"
  }
}

Use this endpoint to retrieve lists of triggers.

Example parameters

Parameter Default Description
include null Comma separated list of relations to include in the response. For example stage.
sort id Sort list by any of the trigger attributes.

Users

User Object

{
  "data": {
    "id": "4468",
    "type": "users",
    "links": {
      "self": "https://api.teamtailor.com/v1/users/4468"
    },
    "attributes": {
      "description": "<p>test</p>",
      "email": "jonas@example.com",
      "external-id": null,
      "facebook-profile": "https://www.facebook.com/himynameisjonas",
      "google-profile": "",
      "hide-email": false,
      "instagram-profile": "http://instagram.com/himynameisjonas",
      "linkedin-profile": "https://www.linkedin.com/in/himynameisjonas",
      "login-email": "jonas@example.com",
      "name": "Jonas Brusman",
      "other-profile": "http://himynameisjonas.net",
      "phone": "",
      "picture": {
        "standard": "https://res.cloudinary.com/teamtailor-development/image/upload/c_fill,dpr_2.0,f_auto,g_faces:center,h_160,q_80,w_160/v1423832344/hbwennnqa7uo7kubkzry.jpg"
      },
      "role": "admin",
      "title": "Developer",
      "twitter-profile": "https://twitter.com/himynameisjonas",
      "username": "jonas5",
      "visible": true,
      "signature": " -- John Doe",
      "notification-candidate-message": true,
      "notification-job": true,
      "notification-connected-candidate": true,
      "notification-mention": true,
      "notification-lead-message": true,
      "notification-hiring-team-application": true,
      "notification-daily-digest": true,
      "notification-recruiter-application": true,
      "notification-removal-request": true,
      "notification-gdpr-digest": true
    },
    "relationships": {
      "department": {
        "links": {
          "self": "https://api.teamtailor.com/v1/users/4468/relationships/department",
          "related": "https://api.teamtailor.com/v1/users/4468/department"
        }
      },
      "location": {
        "links": {
          "self": "https://api.teamtailor.com/v1/users/4468/relationships/location",
          "related": "https://api.teamtailor.com/v1/users/4468/location"
        }
      },
      "jobs": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/4468/relationships/jobs",
            "related": "https://api.teamtailor.com/v1/users/4468/jobs"
          }
        }
      }
    }
  }
}

Attributes

Attribute Type Description
description string About text, visible on the public profile
email string Used for notifications and might be visible on career site profile Requires admin permission if hidden.
external-id string Use to store your own ID to reference users by. Will also be used in SSO logins to look up users if sent as name-id.
facebook-profile string URL to Facebook profile
google-profile string URL to Google+ profile
hide-email boolean If e-mail address should be hidden on career site
instagram-profile string URL to Instagram profile
linkedin-profile string URL to LinkedIn profile
login-email string Account email used to login (might be separate than email on career site profile). Can be null until user accepts invitation. Requires admin permission
merge boolean Write only True if the attributes should be merged with an existing user, matched by email address.
name string The user’s name
other-profile string URL to other profile
phone string Phone number
picture string Url to user picture
role string Permission role (no_access, user, recruiter, designer, admin or external_recruiter)
title string Title, e.g ‘CEO’ or 'Account manager’
twitter-profile string URL to Twitter profile
username string Internal username, used in mentions
visible boolean If profile is visible on the career site
signature string Email signature
notification-candidate-message boolean Notify user when candidate replies to an email Requires admin permission.
notification-job boolean Notify user when new job is published Requires admin permission.
notification-connected-candidate boolean Notify user when a candidate connects with your company Requires admin permission.
notification-mention boolean Notify user when a team member mentions them Requires admin permission.
notification-lead-message boolean Notify user when a visitor writes a message Requires admin permission.
notification-hiring-team-application boolean Notify user when a candidate applies for a job where they’re part of the hiring team Requires admin permission.
notification-daily-digest boolean Receive a daily digest email with all activities in the hiring teams Requires admin permission.
notification-recruiter-application boolean Notify user when a candidate applies for a job where they are a recruiter Requires admin permission.
notification-removal-request boolean Notify user when a candidate asked to be removed (for GDPR managers only) Requires admin permission.
notification-gdpr-digest boolean Sends daily digest of GDPR/data retention activities (for GDPR managers only) Requires admin permission.

Relations

Relation Description
department Listed under this department on the career site
location Listed under this location on the career site
jobs Jobs the user is recruiter for

List users

GET https://api.teamtailor.com/v1/users HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/users" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "819",
      "type": "users",
      "links": {
        "self": "https://api.teamtailor.com/v1/users/819"
      },
      "attributes": {
        "description": "<p>I have been doing IT-related business/product development for the last 10 years.</p>",
        "email": "erik@example.com",
        "external-id": null,
        "facebook-profile": "https://www.facebook.com/eandersson",
        "google-profile": "",
        "hide-email": false,
        "instagram-profile": "http://instagram.com/erianderssson",
        "linkedin-profile": "http://se.linkedin.com/in/erikandersson",
        "login-email": "erik@example.com",
        "name": "Erik Andersson",
        "other-profile": "",
        "phone": "+46735000131",
        "picture": {
          "standard": "https://res.cloudinary.com/teamtailor-development/image/upload/c_fill,dpr_2.0,f_auto,g_faces:center,h_160,q_80,w_160/v1418376224/bhtsaivvnjj1zk4kpgjn.jpg"
        },
        "role": "admin",
        "title": "CEO",
        "twitter-profile": "",
        "username": "erikandersson2",
        "visible": true,
        "notification-candidate-message": true,
        "notification-job": true,
        "notification-connected-candidate": true,
        "notification-mention": true,
        "notification-lead-message": true,
        "notification-hiring-team-application": true,
        "notification-daily-digest": true,
        "notification-recruiter-application": true,
        "notification-removal-request": true,
        "notification-gdpr-digest": true
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/819/relationships/department",
            "related": "https://api.teamtailor.com/v1/users/819/department"
          }
        },
        "location": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/819/relationships/location",
            "related": "https://api.teamtailor.com/v1/users/819/location"
          }
        }
      }
    },
    {
      "id": "1801",
      "type": "users",
      "links": {
        "self": "https://api.teamtailor.com/v1/users/1801"
      },
      "attributes": {
        "description": "<p>I'm a passionate web developer.</p>",
        "email": "richard@example.com",
        "facebook-profile": "https://www.facebook.com/richard.johansson",
        "google-profile": "",
        "hide-email": false,
        "instagram-profile": "http://instagram.com/richardjohansso",
        "linkedin-profile": "http://se.linkedin.com/in/richardjohansson",
        "login-email": "richard@example.com",
        "name": "Richard Erik Johansson",
        "other-profile": "",
        "phone": "",
        "picture": {
          "standard": "https://res.cloudinary.com/teamtailor-development/image/upload/c_fill,dpr_2.0,f_auto,g_faces:center,h_160,q_80,w_160/v1472197022/ctiiyiwfpif7nhdjuf6l.jpg"
        },
        "role": "user",
        "title": "Developer",
        "twitter-profile": "http://Twitter.com/richardjohansso",
        "username": "richardjohansson",
        "visible": true,
        "notification-candidate-message": true,
        "notification-job": true,
        "notification-connected-candidate": true,
        "notification-mention": true,
        "notification-lead-message": true,
        "notification-hiring-team-application": true,
        "notification-daily-digest": true,
        "notification-recruiter-application": true,
        "notification-removal-request": true,
        "notification-gdpr-digest": true
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/1801/relationships/department",
            "related": "https://api.teamtailor.com/v1/users/1801/department"
          }
        },
        "location": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/1801/relationships/location",
            "related": "https://api.teamtailor.com/v1/users/1801/location"
          }
        }
      }
    }
  ],
  "meta": {
    "record-count": 20,
    "page-count": 2
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/users?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "next": "https://api.teamtailor.com/v1/users?page%5Bnumber%5D=2&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/users?page%5Bnumber%5D=2&page%5Bsize%5D=10"
  }
}

Use this endpoint to retrieve lists of users.

Example parameters

Parameter Default Description
include null Comma separated list of relations to include in the response. For example department,location.
filter[email] null Filter by email address.
filter[department] null Filter by department.
filter[external-id] null Filter by external-id.
sort id Sort list by any of the user attributes.

Show a User

GET https://api.teamtailor.com/v1/users/4468 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/users/4468" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": {
    "id": "4468",
    "type": "users",
    "links": {
      "self": "https://api.teamtailor.com/v1/users/4468"
    },
    "attributes": {
      "description": "<p>test</p>",
      "email": "jonas@example.com",
      "external-id": null,
      "facebook-profile": "https://www.facebook.com/himynameisjonas",
      "google-profile": "",
      "hide-email": false,
      "instagram-profile": "http://instagram.com/himynameisjonas",
      "linkedin-profile": "https://www.linkedin.com/in/himynameisjonas",
      "login-email": "jonas@example.com",
      "name": "Jonas Brusman",
      "other-profile": "http://himynameisjonas.net",
      "phone": "",
      "picture": {
        "standard": "https://res.cloudinary.com/teamtailor-development/image/upload/c_fill,dpr_2.0,f_auto,g_faces:center,h_160,q_80,w_160/v1423832344/hbwennnqa7uo7kubkzry.jpg"
      },
      "role": "admin",
      "title": "Developer",
      "twitter-profile": "https://twitter.com/himynameisjonas",
      "username": "jonas5",
      "visible": true,
      "notification-candidate-message": true,
      "notification-job": true,
      "notification-connected-candidate": true,
      "notification-mention": true,
      "notification-lead-message": true,
      "notification-hiring-team-application": true,
      "notification-daily-digest": true,
      "notification-recruiter-application": true,
      "notification-removal-request": true,
      "notification-gdpr-digest": true
    },
    "relationships": {
      "department": {
        "links": {
          "self": "https://api.teamtailor.com/v1/users/4468/relationships/department",
          "related": "https://api.teamtailor.com/v1/users/4468/department"
        }
      },
      "location": {
        "links": {
          "self": "https://api.teamtailor.com/v1/users/4468/relationships/location",
          "related": "https://api.teamtailor.com/v1/users/4468/location"
        }
      }
    }
  }
}

Update User

PATCH https://api.teamtailor.com/v1/users/819 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{
  "data": {
    "id": "819",
    "attributes": {
      "title": "My New Title",
      "name": "Erik Eriksson",
      "notification-daily-digest": false
    },
    "type": "users"
  }
}
curl -X "PATCH" "https://api.teamtailor.com/v1/users/819" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
     -H "Content-Type: application/vnd.api+json" \
     -d "{\"data\":{\"id\":\"819\",\"attributes\":{\"title\":\"My New Title\",\"name\":\"Erik Eriksson\"},\"type\":\"users\"}}"

Example response

{
  "data": {
    "id": "819",
    "type": "users",
    "links": {
      "self": "http://api.teamtailor.com/v1/users/819"
    },
    "attributes": {
      "description": "<p>Hi! This is my public profile.</p><p>I can introduce myself with HTML here.</p>",
      "email": "erik@example.com",
      "external-id": null,
      "facebook-profile": "https://www.facebook.com/erikeriksson",
      "google-profile": "",
      "hide-email": false,
      "instagram-profile": "http://instagram.com/erikeriksson",
      "linkedin-profile": "http://se.linkedin.com/in/erikeriksson",
      "login-email": "erik@example.com",
      "name": "Erik Eriksson",
      "other-profile": "",
      "phone": "+46731231231",
      "picture": {
        "standard": "https://res.cloudinary.com/teamtailor-production/image/upload/c_fill,dpr_2.0,f_auto,g_faces:center,h_160,q_80,w_160/v150512323/bhtsaivvnjj1zasvv12sa.jpg"
      },
      "role": "admin",
      "title": "My New Title",
      "twitter-profile": "",
      "username": "erikeriksson",
      "visible": true,
      "signature": " -- John Doe",
      "notification-candidate-message": true,
      "notification-job": true,
      "notification-connected-candidate": true,
      "notification-mention": true,
      "notification-lead-message": true,
      "notification-hiring-team-application": true,
      "notification-daily-digest": false,
      "notification-recruiter-application": true,
      "notification-removal-request": true,
      "notification-gdpr-digest": true
    },
    "relationships": {
      "department": {
        "links": {
          "self": "http://api.teamtailor.com/v1/users/819/relationships/department",
          "related": "http://api.teamtailor.com/v1/users/819/department"
        }
      },
      "location": {
        "links": {
          "self": "http://api.teamtailor.com/v1/users/819/relationships/location",
          "related": "http://api.teamtailor.com/v1/users/819/location"
        }
      }
    }
  }
}

Change a users’s attributes/relationships.

Create User

POST https://api.teamtailor.com/v1/users HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{
  "data": {
    "attributes": {
      "title": "CMO",
      "name": "Erik Eriksson",
      "email": "erik@example.com",
      "role": "recruiter",
      "signature": "// Erik"
      "merge": true
    },
    "type": "users"
  }
}
curl -X "PATCH" "https://api.teamtailor.com/v1/users" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"
     -H "Content-Type: application/vnd.api+json" \
     -d "{\"data\":{\"attributes\":{\"title\":\"My New Title\",\"name\":\"Erik Eriksson\",\"email\":\"erik@example.com\",\"role\":\"recruiter\",\"signature\":\"// Erik\"},\"type\":\"users\"}}"

Example response

{
  "data": {
    "id": "819",
    "type": "users",
    "links": {
      "self": "http://api.teamtailor.com/v1/users/819"
    },
    "attributes": {
      "description": null,
      "email": "erik@example.com",
      "external-id": null,
      "facebook-profile": null,
      "google-profile": null,
      "hide-email": false,
      "instagram-profile": null,
      "linkedin-profile": null,
      "login-email": null,
      "name": "Erik Eriksson",
      "other-profile": null,
      "phone": null,
      "picture": null,
      "role": "recruiter",
      "title": null,
      "twitter-profile": null,
      "username": "erikeriksson",
      "visible": true,
      "signature": "// Erik",
      "notification-candidate-message": true,
      "notification-job": true,
      "notification-connected-candidate": true,
      "notification-mention": true,
      "notification-lead-message": true,
      "notification-hiring-team-application": false,
      "notification-daily-digest": true,
      "notification-recruiter-application": true,
      "notification-removal-request": true,
      "notification-gdpr-digest": true
    },
    "relationships": {
      "department": {
        "links": {
          "self": "http://api.teamtailor.com/v1/users/819/relationships/department",
          "related": "http://api.teamtailor.com/v1/users/819/department"
        }
      },
      "location": {
        "links": {
          "self": "http://api.teamtailor.com/v1/users/819/relationships/location",
          "related": "http://api.teamtailor.com/v1/users/819/location"
        }
      }
    }
  }
}

Create a user. An email invitation will be sent to the specified email if role is not “no-access”. The user will be able to create a password using the link in the invitation email.

Use the merge attribute to merge the candidate attributes in case a candidate with a matching email address already exists.

Delete a User

DELETE https://api.teamtailor.com/v1/users/4468?assign_jobs_to_user_id=5542 HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "DELETE" "https://api.teamtailor.com/v1/users/4468?assign_jobs_to_user_id=5542" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

When a user is recruiter for a job, you can’t delete the user without first assigning the jobs to a different user. To automatically assign all jobs to a different user, use the parameter assign_jobs_to_user_id.

Uploads

A file uploaded to a candidate. Can be uploaded by either the candidate, or a user.

Upload Object

{
  "data": {
    "id": "446842",
    "type": "uploads",
    "links": {
      "self": "https://api.teamtailor.com/v1/uploads/446842"
    },
    "attributes": {
      "url": "https://teamtailor-production.s3.amazonaws.com/uploads/213fd22e8dce6665edfb3922d31f4c22124547e8/cover_letter.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EKIAI4NUY2WMURK1W5HA%2F20181106%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20181106T140003Z&X-Amz-Expires=10&X-Amz-SignedHeaders=host&X-Amz-Signature=468a0c89385dc39e5981d0003d84488a492fdc0b44d3bce4522bc01896509863",
      "file-name": "cover_letter.pdf",
      "internal": false
    },
    "relationships": {
      "candidate": {
        "links": {
          "self": "https://api.teamtailor.com/v1/uploads/446842/relationships/candidate",
          "related": "https://api.teamtailor.com/v1/uploads/446842/candidate"
        }
      },
      "job": {
        "links": {
          "self": "https://api.teamtailor.com/v1/uploads/446842/relationships/job",
          "related": "https://api.teamtailor.com/v1/uploads/446842/job"
        }
      }
    }
  }
}

Attributes

Attribute Type Description
url string Signed URL to file, valid for 1 minute.
file-name string Original file name
internal boolean Internal files were uploaded by a user, not the candidate

Relations

Relation Description
candidate
job The job for which this upload was created

List uploads

GET https://api.teamtailor.com/v1/uploads HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108
curl -X "GET" "https://api.teamtailor.com/v1/uploads" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108"

Example response

{
  "data": [
    {
      "id": "446842",
      "type": "uploads",
      "links": {
        "self": "https://api.teamtailor.com/v1/uploads/446842"
      },
      "attributes": {
        "url": "https://teamtailor-production.s3.amazonaws.com/uploads/213fd22e8dce6665edfb3922d31f4c22124547e8/cover_letter.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EKIAI4NUY2WMURK1W5HA%2F20181106%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20181106T140003Z&X-Amz-Expires=10&X-Amz-SignedHeaders=host&X-Amz-Signature=468a0c89385dc39e5981d0003d84488a492fdc0b44d3bce4522bc01896509863",
        "file-name": "cover_letter.pdf",
        "internal": false
      },
      "relationships": {
        "candidate": {
          "links": {
            "self": "https://api.teamtailor.com/v1/uploads/446842/relationships/candidate",
            "related": "https://api.teamtailor.com/v1/uploads/446842/candidate"
          }
        },
        "job": {
          "links": {
            "self": "https://api.teamtailor.com/v1/uploads/446842/relationships/job",
            "related": "https://api.teamtailor.com/v1/uploads/446842/job"
          }
        }
      }
    },
    
  ],
  "meta": {
    "record-count": 20,
    "page-count": 1
  },
  "links": {
    "first": "https://api.teamtailor.com/v1/uploads?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "next": "https://api.teamtailor.com/v1/uploads?page%5Bnumber%5D=2&page%5Bsize%5D=10",
    "last": "https://api.teamtailor.com/v1/uploads?page%5Bnumber%5D=2&page%5Bsize%5D=10"
  }
}

Use this endpoint to retrieve lists of uploads.

Example parameters

Parameter Default Description
include null Comma separated list of relations to include in the response. For example candidate.
sort id Sort list by any of the upload attributes.
filter[job] null Filter uploads for by job.

Create a upload

POST https://api.teamtailor.com/v1/uploads HTTP/1.1
Authorization: Token token=abc123abc123
X-Api-Version: 20161108

{
  "data": {
    "type": "uploads",
    "attributes": {
      "url": "https://my.fileurl.com/testfile.pdf",
      "file-name": "testfile.pdf"
    },
    "relationships": {
      "candidate": {
        "data":{
          "id": "12345",
          "type": "candidates"
        }
      }
    }
  }
}
curl -X "GET" "https://api.teamtailor.com/v1/uploads" \
     -H "Authorization: Token token=abc123abc123" \
     -H "X-Api-Version: 20161108" \
     -d "{\"data\":{\"type\":\"uploads\",\"attributes\":{\"url\":\"https://my.fileurl.com/testfile.pdf\",\"file-name\":\"testfile.pdf\"},\"relationships\":{\"candidate\":{\"data\":{\"id\":\"12345\",\"type\":\"candidates\"}}}}}"

Example response

{
  "data": {
    "id": "1234",
    "type": "uploads",
    "links": {
      "self": "https://api.teamtailor.com/v1/uploads/1234"
    },
    "attributes": {
      "url": "http://file-download-url.com/testfile.pdf",
      "file-name": "testfile.pdf",
      "internal": false
    },
    "relationships": {
      "candidate": {
        "links": {
          "self": "https://api.teamtailor.com/v1/uploads/1234/relationships/candidate",
          "related": "https://api.teamtailor.com/v1/uploads/1234/candidate"
        }
      },
      "job": {
        "links": {
          "self": "https://api.teamtailor.com/v1/uploads/1234/relationships/job",
          "related": "https://api.teamtailor.com/v1/uploads/1234/job"
        }
      }
    }
  }
}

Create an upload for a specific candidate.