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 jobs

read

Can read all public data, for example jobs (including internal and unlisted 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 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:

Examples

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

List published jobs with their department and location

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

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

Parameters used in this example

Parameter Value Description
include department,location Comma separated list of relations to include in the response.
page[size] 15 Page size, get 15 jobs in one request

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

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"

2018-05-11 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

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.

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

When sourced the candidate was added to the system by a recruiter.

A candidate that is connected has opted in to recieve new job notifications and has also the option to create a richer and more personal profile.

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",
      "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"
        }
      },
      "locations": {
        "links": {
          "self": "https://api.teamtailor.com/v1/candidates/1337/relationships/locations",
          "related": "https://api.teamtailor.com/v1/candidates/1337/locations"
        }
      }
    }
  }
}

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
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
resume string Url to Pdf-verison of resume
sourced boolean True if added by a recruiter without applying
tags array
unsubscribed boolean If true no new job notifications are sent
updated-at date

Relations

Relation Description
department
role
job-applications
questions
answers
locations
uploads

List Candidates

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/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",
        "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": []
        }
      }
    },
    {
      "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",
        "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": []
        }
      }
    },
  ],
  "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[email] null Filter by email address.
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",
      "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"
        }
      }
    }
  }
}

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"
         }
       }
     }'

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,
      "resume": null,
      "sourced": false,
      "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"
        }
      }
    }
  }
}

Use the merge attribute to merge the candidate attributes in case a candidate with the supplied 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",
      "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"
        }
      }
    }
  }
}

Change a candidates attributes/relationships.

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"
        }
      }
    }
  }
}

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

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"
          }
        }
      }
    },
    {
      "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"
          }
        }
      }
    },
    {
      "id": "339",
      "type": "departments",
      "links": {
        "self": "https://api.teamtailor.com/v1/departments/339"
      },
      "attributes": {
        "name": "Marketing & PR",
        "people-headline": "",
        "people-text": "",
        "row-order": 7340032,
        "headline": "Spread the word.",
        "text": "Do you want to help us spread the word of modern & effective recruting? We are on to something but we need others to know it as well. Help us make the HR/Marketing world a happier place!",
        "pictures": [
          {
            "standard": "https://res.cloudinary.com/teamtailor-development/image/upload/c_fill,f_auto,g_faces:center,h_465,q_80,w_930/v1422370235/mbdlqjzneliyy0l5kcjn.jpg"
          }
        ]
      },
      "relationships": {
        "roles": {
          "links": {
            "self": "https://api.teamtailor.com/v1/departments/339/relationships/roles",
            "related": "https://api.teamtailor.com/v1/departments/339/roles"
          }
        }
      }
    }
  ],
  "meta": {
    "record-count": 3,
    "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"
        }
      }
    }
  }
}

Hiring Teams

This object represents the team membership.

Team Membership Object

{
  "data": {
    "id": "21",
    "type": "team-memberships",
    "links": {
      "self": "https://api.teamtailor.localhost/v1/team-memberships/21"
    },
    "relationships": {
      "user": {
        "links": {
          "self": "https://api.teamtailor.localhost/v1/team-memberships/21/relationships/user",
          "related": "https://api.teamtailor.localhost/v1/team-memberships/21/user"
        }
      },
      "team": {
        "links": {
          "self": "https://api.teamtailor.localhost/v1/team-memberships/21/relationships/team",
          "related": "https://api.teamtailor.localhost/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 department.

Relation Description
user One of your company’s registered users.
team Either a department 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.localhost/v1/team-memberships/7"
      },
      "relationships": {
        "user": {
          "links": {
            "self": "https://api.teamtailor.localhost/v1/team-memberships/7/relationships/user",
            "related": "https://api.teamtailor.localhost/v1/team-memberships/7/user"
          }
        },
        "team": {
          "links": {
            "self": "https://api.teamtailor.localhost/v1/team-memberships/7/relationships/team",
            "related": "https://api.teamtailor.localhost/v1/team-memberships/7/team"
          }
        }
      }
    },
    {
      "id": "8",
      "type": "team-memberships",
      "links": {
        "self": "https://api.teamtailor.localhost/v1/team-memberships/8"
      },
      "relationships": {
        "user": {
          "links": {
            "self": "https://api.teamtailor.localhost/v1/team-memberships/8/relationships/user",
            "related": "https://api.teamtailor.localhost/v1/team-memberships/8/user"
          }
        },
        "team": {
          "links": {
            "self": "https://api.teamtailor.localhost/v1/team-memberships/8/relationships/team",
            "related": "https://api.teamtailor.localhost/v1/team-memberships/8/team"
          }
        }
      }
    },
    {
      "id": "9",
      "type": "team-memberships",
      "links": {
        "self": "https://api.teamtailor.localhost/v1/team-memberships/9"
      },
      "relationships": {
        "user": {
          "links": {
            "self": "https://api.teamtailor.localhost/v1/team-memberships/9/relationships/user",
            "related": "https://api.teamtailor.localhost/v1/team-memberships/9/user"
          }
        },
        "team": {
          "links": {
            "self": "https://api.teamtailor.localhost/v1/team-memberships/9/relationships/team",
            "related": "https://api.teamtailor.localhost/v1/team-memberships/9/team"
          }
        }
      }
    }
  ],
  "meta": {
      "record-count": 3,
      "page-count": 1
  },
  "links": {
      "first": "https://api.teamtailor.localhost/v1/team-memberships?page%5Bnumber%5D=1&page%5Bsize%5D=3",
      "last": "https://api.teamtailor.localhost/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.localhost/v1/team-memberships/21"
    },
    "relationships": {
      "user": {
        "links": {
          "self": "https://api.teamtailor.localhost/v1/team-memberships/21/relationships/user",
          "related": "https://api.teamtailor.localhost/v1/team-memberships/21/user"
        }
      },
      "team": {
        "links": {
          "self": "https://api.teamtailor.localhost/v1/team-memberships/21/relationships/team",
          "related": "https://api.teamtailor.localhost/v1/team-memberships/21/team"
        }
      }
    }
  }
}

Retreive a specific team membership.

Parameter Description
id The team membership’s id.

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": "departments"
        }
      },
      "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": "departments"
        }
      },
       "user": {
         "data": {
           "id": "3",
           "type": "users"
         }
       }
     }
   }
 }'

Example response

{
  "data": {
    "id": "21",
    "type": "team-memberships",
    "links": {
      "self": "https://api.teamtailor.localhost/v1/team-memberships/21"
    },
    "relationships": {
      "user": {
        "links": {
          "self": "https://api.teamtailor.localhost/v1/team-memberships/21/relationships/user",
          "related": "https://api.teamtailor.localhost/v1/team-memberships/21/user"
        }
      },
      "team": {
        "links": {
          "self": "https://api.teamtailor.localhost/v1/team-memberships/21/relationships/team",
          "related": "https://api.teamtailor.localhost/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.

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>lopl</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": "New Title",
      "tags": [
        "JavaScript",
        "Ruby"
      ],
      "external-application-url": null,
      "name-requirement": "optional",
      "resume-requirement": "optional",
      "cover-letter-requirement": "optional",
      "phone-requirement": "optional"
    },
    "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"
        }
      },
      "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"
        }
      }
    }
  }
}

Attributes

Attribute Type Description
apply-button-text string Custom text for apply button
body string The ad text, simple html is supported
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
title string The title on the job ad
tags array Array of string for each tag
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
Link Description
careersite-job-url View job on the Career site
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
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
colleagues The users that are displayed as colleagues on the job ad

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-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": null,
        "body": "hello",
        "end-date": null,
        "human-status": "published",
        "internal": false,
        "picture": null,
        "pinned": false,
        "start-date": null,
        "status": "open",
        "title": "yay horray 3",
        "tags": [],
        "external-application-url": null
      },
      "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"
          }
        },
        "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"
          }
        }
      }
    },
    {
      "id": "7262",
      "type": "jobs",
      "links": {
        "careersite-job-url": "http://career.teamtailor.com/jobs/7262-yay-horray-3",
        "careersite-job-apply-url": "https://career.teamtailor.com/jobs/7262-yay-horray-3/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": "yay horray 3",
        "tags": [
          "JavaScript",
          "Ruby"
        ],
        "external-application-url": null
      },
      "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"
          }
        },
        "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"
          }
        }
      }
    }
  ],
  "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 and unlisted. 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.
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",
      "tags": [
        "Ruby"
      ],
      "external-application-url": null
    },
    "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"
        }
      },
      "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"
        }
      }
    }
  }
}

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",
      "body": "<p>hello</p>",
      "picture": "url-to-a-picture"
    },
    "relationships": {
      "user": {
        "data": {
          "id": "819",
          "type": "users"
        }
      },
      "department": {
        "data": {
          "id": "337",
          "type": "departments"
        }
      },
      "location": {
        "data": {
          "id": "667",
          "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\",\"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",
      "external-application-url": null
    },
    "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"
        }
      },
      "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"
        }
      }
    }
  }
}

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\":\"7199\",\"attributes\":{\"title\":\"New Title\",\"status\":\"unlisted\"},\"type\":\"jobs\"}}"

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": "yay horray",
      "tags": [
        "JavaScript"
      ],
      "external-application-url": null
    },
    "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"
        }
      },
      "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"
        }
      }
    }
  }
}

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"
    },
    "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"
        }
      }
    }
  }
}

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

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)

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"
          }
        }
      }
    },
    {
      "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"
          }
        }
      }
    },
    {
      "id": "1339",
      "type": "job-applications",
      "links": {
        "self": "https://api.teamtailor.com/v1/job-applications/1339"
      },
      "attributes": {
        "created-at": "2015-04-16T11:34:54.636+02:00",
        "cover-letter": "",
        "updated-at": "2016-06-27T12:28:38.980+02:00",
        "rejected-at": "2015-04-28T13:43:03.947+02:00",
        "referring-url": "https://www.google.fr/",
        "referring-site": "Google",
        "sourced": false,
        "changed-stage-at": "2017-01-11T11:29:48.841+01:00"
      },
      "relationships": {
        "candidate": {
          "links": {
            "self": "https://api.teamtailor.com/v1/job-applications/1339/relationships/candidate",
            "related": "https://api.teamtailor.com/v1/job-applications/1339/candidate"
          }
        },
        "job": {
          "links": {
            "self": "https://api.teamtailor.com/v1/job-applications/1339/relationships/job",
            "related": "https://api.teamtailor.com/v1/job-applications/1339/job"
          }
        },
        "stage": {
          "links": {
            "self": "https://api.teamtailor.com/v1/job-applications/1339/relationships/stage",
            "related": "https://api.teamtailor.com/v1/job-applications/1339/stage"
          }
        }
      }
    },
  ],
  "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"
        }
      }
    }
  }
}

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": "hej jag gillar data",
      "sourced": 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"
        }
      }
    }
  }
}

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"
        }
      }
    }
  }
}

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": ""
      }
    },
    {
      "id": "2981",
      "type": "locations",
      "links": {
        "self": "https://api.teamtailor.com/v1/locations/2981"
      },
      "attributes": {
        "address": "",
        "city": "Münich",
        "country": "Germany",
        "email": "",
        "headquarters": false,
        "lat": "48.1351253",
        "long": "11.5819806",
        "name": "",
        "phone": "",
        "zip": ""
      }
    }
  ],
  "meta": {
    "record-count": 3,
    "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"
    }
  }
}

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"
            }
          }
        }
      },
      {
        "id": "3",
        "type": "picked-questions",
        "links": {
          "self": "https://api.teamtailor.com/v1/picked-questions/3"
        },
        "attributes": {
          "mandatory": false
        },
        "relationships": {
          "question": {
            "links": {
              "self": "https://api.teamtailor.com/v1/picked-questions/3/relationships/question",
              "related": "https://api.teamtailor.com/v1/picked-questions/3/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.

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"
        }
      }
    }
  }
}

Attributes

Attribute Type Description
name string The name of the role

Relations

Relation Description
department Parent Department

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"
          }
        }
      }
    },
    {
      "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"
          }
        }
      }
    },
    {
      "id": "50",
      "type": "roles",
      "links": {
        "self": "https://api.teamtailor.com/v1/roles/50"
      },
      "attributes": {
        "name": "Product owner"
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/roles/50/relationships/department",
            "related": "https://api.teamtailor.com/v1/roles/50/department"
          }
        }
      }
    },
    {
      "id": "2106",
      "type": "roles",
      "links": {
        "self": "https://api.teamtailor.com/v1/roles/2106"
      },
      "attributes": {
        "name": "Pre-sales"
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/roles/2106/relationships/department",
            "related": "https://api.teamtailor.com/v1/roles/2106/department"
          }
        }
      }
    },
    {
      "id": "2107",
      "type": "roles",
      "links": {
        "self": "https://api.teamtailor.com/v1/roles/2107"
      },
      "attributes": {
        "name": "Field sales"
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/roles/2107/relationships/department",
            "related": "https://api.teamtailor.com/v1/roles/2107/department"
          }
        }
      }
    },
    {
      "id": "2108",
      "type": "roles",
      "links": {
        "self": "https://api.teamtailor.com/v1/roles/2108"
      },
      "attributes": {
        "name": "Sales Manager"
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/roles/2108/relationships/department",
            "related": "https://api.teamtailor.com/v1/roles/2108/department"
          }
        }
      }
    },
    {
      "id": "1",
      "type": "roles",
      "links": {
        "self": "https://api.teamtailor.com/v1/roles/1"
      },
      "attributes": {
        "name": "Copywriter"
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/roles/1/relationships/department",
            "related": "https://api.teamtailor.com/v1/roles/1/department"
          }
        }
      }
    },
    {
      "id": "2",
      "type": "roles",
      "links": {
        "self": "https://api.teamtailor.com/v1/roles/2"
      },
      "attributes": {
        "name": "PR Manager"
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/roles/2/relationships/department",
            "related": "https://api.teamtailor.com/v1/roles/2/department"
          }
        }
      }
    },
    {
      "id": "3",
      "type": "roles",
      "links": {
        "self": "https://api.teamtailor.com/v1/roles/3"
      },
      "attributes": {
        "name": "Online Marketeer"
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/roles/3/relationships/department",
            "related": "https://api.teamtailor.com/v1/roles/3/department"
          }
        }
      }
    }
  ],
  "meta": {
    "record-count": 9,
    "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"
        }
      }
    }
  }
}

Stages

A stage indicate the candidate status for a job-application. The stages are defined for each job. There is always two default stages present which can’t be deleted or modified.

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

Stage Object

{
  "id": "1337",
  "type": "stages",
  "links": {
    "self": "https://api.teamtailor.com/v1/stages/1337"
  },
  "attributes": {
    "created-at": "2015-11-05T20:12:16.053+01:00",
    "updated-at": "2016-10-05T10:11:04.615+02:00",
    "name": "Inbox",
    "stage-type": "Inbox"
  },
  "relationships": {
    "candidates": {
      "links": {
        "self": "https://api.teamtailor.com/v1/stages/1337/relationships/candidates",
        "related": "https://api.teamtailor.com/v1/stages/1337/candidates"
      }
    },
    "job": {
      "links": {
        "self": "https://api.teamtailor.com/v1/stages/1337/relationships/job",
        "related": "https://api.teamtailor.com/v1/stages/1337/job"
      }
    }
  }
}

Attributes

Attribute Type Description
created-at date
name string
stage-type string Inbox, In process, Hired
updated-at date

Relations

Relation Description
candidates
job

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",
      "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",
      "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
    },
    "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"
        }
      }
    }
  }
}

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
facebook-profile string URL to Facebook profile
google-profile string URL to Google+ profile
hide-email boolean true if e-mail address should be hidden on career site
instagram-profile string URL to Instagram profile
linkedin-profile string URL to LinkedIn profile
name string The user’s name
other-profile string URL to other profile
phone string Phone number
picture object Picture object (Profile picture)
role string Permission role (no_access, user, recruiter or admin)
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 true if profile is visible on the career site
notification-candidate-message boolean true notifies user when candidate replies to an email
notification-job boolean true notifies user when new job is published
notification-connected-candidate boolean true notifies user when candidate connects with your company
notification-mention boolean true notifies user when team member mentions them
notification-lead-message boolean true notifies user when lead writes a message
notification-hiring-team-application boolean true notifies user when candidate applies for a job where they’re part of the hiring team
notification-daily-digest boolean true means the user will receive the daily digest email with all activities in their hiring teams
notification-recruiter-application boolean true notifies user when candidate applies for a job where they are a recruiter

Relations

Relation Description
department Listed under this department on the career site
location Listed under this location on the career site

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>\r\n\t I have been doing IT-related business/product development for the last 10 years. Working with great companies such as Skype, Mynewsdesk and now Teamtailor.</p><p>\r\n\t<span style=\"line-height: 1.45em; background-color: initial;\">At Teamtailor we do not have any formal HR-experience, we just love the web. Through our own recruitment activities the last couple of years we have come to realize that there is much that can be done and improved.</span><span style=\"line-height: 1.45em; background-color: initial;\">.. We just had to do something.</span></p>",
        "email": "erik@example.com",
        "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",
        "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
      },
      "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>\r\n\t          Coming from no computer science background, I'm a passionate web developer with lots of love for the frameworks and tools I use.</p><p>\r\n\t         I love building modern applications for businesses, using the web to solve problems – and improving the way people work. And I have done so in the last 10 years, previously building Mynewsdesk from a small startup, to the international company today.</p><p>\r\n\t          My daily work include Ruby on Rails, Ember.js, Sass, redis, PostgreSQL, Elasticsearch, and managing our cloud hosting. All the stuff you need to build modern web applications!</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",
        "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": "richarderikjohansson",
        "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
      },
      "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"
          }
        }
      }
    },
    {
      "id": "2199",
      "type": "users",
      "links": {
        "self": "https://api.teamtailor.com/v1/users/2199"
      },
      "attributes": {
        "description": "<p>\r\n\t   I love working at Teamtailor because I think we're trying to solve a <strong>real</strong> and <strong>important</strong> problem. The way HR and recruiting works needs to change. We help companies to become better at market themselves as an attractive workplace, and to engage their current employees in the recruiting process.</p><p>\r\n\t   I've been building products/services on the web since 1999. A lot of strange stuff <span style=\"line-height: 1.45em; background-color: initial;\">and the occasional success.</span></p><p>\r\n\t <span style=\"line-height: 1.45em; background-color: initial;\"></span></p><p>\r\n\t <span style=\"line-height: 1.45em; background-color: initial;\"></span></p><p>\r\n\t <span style=\"line-height: 1.45em; background-color: initial;\"> </span></p><p>\r\n\t <span style=\"line-height: 1.45em; background-color: initial;\"></span></p>",
        "email": "david@example.com",
        "facebook-profile": "http://www.facebook.com/david.wennergren",
        "google-profile": "",
        "hide-email": false,
        "instagram-profile": "",
        "linkedin-profile": "http://se.linkedin.com/in/davidwennergren/",
        "name": "David Richard Wennergren",
        "other-profile": "",
        "phone": "070-7164007",
        "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/v1418376331/e5xiuhwkkyy1lkpoc5vv.jpg"
        },
        "role": "recruiter",
        "title": "Developer",
        "twitter-profile": "http://twitter.com/davidwennergren",
        "username": "david",
        "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
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/2199/relationships/department",
            "related": "https://api.teamtailor.com/v1/users/2199/department"
          }
        },
        "location": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/2199/relationships/location",
            "related": "https://api.teamtailor.com/v1/users/2199/location"
          }
        }
      }
    },
    {
      "id": "3362",
      "type": "users",
      "links": {
        "self": "https://api.teamtailor.com/v1/users/3362"
      },
      "attributes": {
        "description": "<p>\r\n\t<img src=\"http://res.cloudinary.com/teamtailor/image/upload/t_span8/iveduppqqyywm12wmn3z.jpg\"></p>",
        "email": "kim@example.com",
        "facebook-profile": "https://www.facebook.com/kimchipchop",
        "google-profile": "",
        "hide-email": false,
        "instagram-profile": "http://instagram.com/kimchipchop",
        "linkedin-profile": "http://se.linkedin.com/pub/kim-alm/4b/4a7/2b1/",
        "name": "Kim Alm",
        "other-profile": "",
        "phone": "0709-851211",
        "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/v1418376420/boneodn9lviq2h94suqo.jpg"
        },
        "role": "user",
        "title": "Sales",
        "twitter-profile": "https://twitter.com/kimchipchop",
        "username": "kimalm1",
        "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
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/3362/relationships/department",
            "related": "https://api.teamtailor.com/v1/users/3362/department"
          }
        },
        "location": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/3362/relationships/location",
            "related": "https://api.teamtailor.com/v1/users/3362/location"
          }
        }
      }
    },
    {
      "id": "3595",
      "type": "users",
      "links": {
        "self": "https://api.teamtailor.com/v1/users/3595"
      },
      "attributes": {
        "description": "<p>\r\n\t <span style=\"line-height: 1.45em; background-color: initial;\">I’m an artisan and a digital creative, in other words &mdash; I’m a web designer. I push pixels for a clear and beautiful web, making your screen look so delicious you may want to lick it. However, good web design is not just about the pretty things. Web sites have users that interacts with them &mdash; that’s why I like to realise my design solutions as well, making sure it works just the way it is meant to.</span></p>",
        "email": "joakim@example.com",
        "facebook-profile": "",
        "google-profile": "",
        "hide-email": false,
        "instagram-profile": "http://instagram.com/joakimnordlund",
        "linkedin-profile": "http://www.linkedin.com/pub/joakim-nordlund/31/ba4/b32",
        "name": "Joakim Nordlund",
        "other-profile": "http://joakimnordlund.com",
        "phone": "0701099987",
        "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/v1430314931/lou1lraaahi9g6cueajf.jpg"
        },
        "role": "admin",
        "title": "Web Designer",
        "twitter-profile": "https://twitter.com/northgrove",
        "username": "joakimnordlund",
        "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
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/3595/relationships/department",
            "related": "https://api.teamtailor.com/v1/users/3595/department"
          }
        },
        "location": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/3595/relationships/location",
            "related": "https://api.teamtailor.com/v1/users/3595/location"
          }
        }
      }
    },
    {
      "id": "4468",
      "type": "users",
      "links": {
        "self": "https://api.teamtailor.com/v1/users/4468"
      },
      "attributes": {
        "description": "<p>test</p>",
        "email": "jonas@example.com",
        "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",
        "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
      },
      "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"
          }
        }
      }
    },
    {
      "id": "4660",
      "type": "users",
      "links": {
        "self": "https://api.teamtailor.com/v1/users/4660"
      },
      "attributes": {
        "description": "",
        "email": "calle@example.com",
        "facebook-profile": "",
        "google-profile": "",
        "hide-email": false,
        "instagram-profile": "",
        "linkedin-profile": "http://se.linkedin.com/in/callehenningsson",
        "name": "Calle Henningsson",
        "other-profile": "",
        "phone": "070-8765959",
        "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/v1442566435/wjnnrxolc1zd0pqrksbv.jpg"
        },
        "role": "no_access",
        "title": "Sales",
        "twitter-profile": "",
        "username": "callehenningsson1",
        "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
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/4660/relationships/department",
            "related": "https://api.teamtailor.com/v1/users/4660/department"
          }
        },
        "location": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/4660/relationships/location",
            "related": "https://api.teamtailor.com/v1/users/4660/location"
          }
        }
      }
    },
    {
      "id": "5334",
      "type": "users",
      "links": {
        "self": "https://api.teamtailor.com/v1/users/5334"
      },
      "attributes": {
        "description": "",
        "email": "suzan@example.com",
        "facebook-profile": "",
        "google-profile": "",
        "hide-email": false,
        "instagram-profile": "",
        "linkedin-profile": "http://se.linkedin.com/in/suzandil",
        "name": "Suzan Dil",
        "other-profile": "",
        "phone": "+46 70-547 06 44",
        "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/v1438766374/mynvx9ypejez1xafegn6.jpg"
        },
        "role": "no_access",
        "title": "Marketing",
        "twitter-profile": "",
        "username": "suzandil",
        "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
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/5334/relationships/department",
            "related": "https://api.teamtailor.com/v1/users/5334/department"
          }
        },
        "location": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/5334/relationships/location",
            "related": "https://api.teamtailor.com/v1/users/5334/location"
          }
        }
      }
    },
    {
      "id": "9067",
      "type": "users",
      "links": {
        "self": "https://api.teamtailor.com/v1/users/9067"
      },
      "attributes": {
        "description": "",
        "email": "christoffer@example.com",
        "facebook-profile": "",
        "google-profile": "",
        "hide-email": false,
        "instagram-profile": "",
        "linkedin-profile": "",
        "name": "Christoffer Ankarstrand",
        "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/v1438700213/tbmdlece0wleejpuw410.jpg"
        },
        "role": "admin",
        "title": "Sales",
        "twitter-profile": "",
        "username": "christofferankarstrand2",
        "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
      },
      "relationships": {
        "department": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/9067/relationships/department",
            "related": "https://api.teamtailor.com/v1/users/9067/department"
          }
        },
        "location": {
          "links": {
            "self": "https://api.teamtailor.com/v1/users/9067/relationships/location",
            "related": "https://api.teamtailor.com/v1/users/9067/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.
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",
      "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",
      "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
    },
    "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",
      "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",
      "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,
      "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
    },
    "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"
    },
    "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\"},\"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",
      "facebook-profile": null,
      "google-profile": null,
      "hide-email": false,
      "instagram-profile": null,
      "linkedin-profile": null,
      "name": "Erik Eriksson",
      "other-profile": null,
      "phone": null,
      "picture": null,
      "role": "recruiter",
      "title": null,
      "twitter-profile": null,
      "username": "erikeriksson",
      "visible": true,
      "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
    },
    "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.

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",
      "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"
        }
      }
    }
  }
}

Attributes

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

Relations

Relation Description
candidate

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",
        "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"
          }
        }
      }
    },
    
  ],
  "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.