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 unlisted jobs

read

Can read all public data, for example jobs (including 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://www.teamtailor.com/widget/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"

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

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

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.

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

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": {
      "body": "<p>lopl</p>",
      "end-date": "2016-11-25T00:00:00.000+01:00",
      "human-status": "scheduled",
      "picture": null,
      "pinned": false,
      "start-date": "2016-11-17T00:00:00.000+01:00",
      "status": "open",
      "title": "New Title"
    },
    "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"
        }
      }
    }
  }
}

Attributes

Attribute Type Description
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
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
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
candidates Candidates who have applied to the job
stages The recruitment stages of the job

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": {
        "body": "hello",
        "end-date": null,
        "human-status": "published",
        "picture": null,
        "pinned": false,
        "start-date": null,
        "status": "open",
        "title": "yay horray 3"
      },
      "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": {
        "body": "hello",
        "end-date": null,
        "human-status": "published",
        "picture": null,
        "pinned": false,
        "start-date": null,
        "status": "open",
        "title": "yay horray 3"
      },
      "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[department] null Filter by department id.
filter[role] null Filter by role id.
filter[location] null Filter by location id.

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": {
      "body": "<p>hello world</p>",
      "end-date": null,
      "human-status": "published",
      "picture": null,
      "pinned": false,
      "start-date": null,
      "status": "open",
      "title": "My new job"
    },
    "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>"
    },
    "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": {
      "body": "<p>hello</p>",
      "end-date": null,
      "human-status": "published",
      "picture": null,
      "pinned": false,
      "start-date": null,
      "status": "open",
      "title": "Account Manager"
    },
    "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"
    },
    "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": {
      "body": "<p>lopl</p>",
      "end-date": null,
      "human-status": "published",
      "picture": null,
      "pinned": false,
      "start-date": null,
      "status": "open",
      "title": "yay horray"
    },
    "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"
    }
  }
}

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

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

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

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