Back to top

Toggl Hire

Toggl Hire API lets you export candidate data for custom integrations or analytics.

Authentication

All endpoints require an API key to be supplied in the request. API keys for each workspace in Toggl Hire can be generated on the integration settings page.

Once you have the API key, set the Authorization header to the value Bearer [your-api-key], for example:

Authorization: Bearer 11ZU1ZOJ0PDOQPVEZ12PPZTPRR933L6VE25LM0R0BEP7961KY3JVDE8VJZY2U28

Errors

If a request fails, the API will return a 4xx or 5xx response with error details in the response body. Currently only the error.type field is provided, which contains the type of the error that occurred. The type should not be shown to the user, but it is human-readable.

{
    "error": {
        "type": "NotFoundError"
    }
}

Pagination

Some endpoints do not return all records, but only a limited amount. This amount is specified using the limit parameter, which has a certain maximum value. To fetch more records than the maximum value, use the URL in the links.next attribute in the response.

Toggl Hire API uses seek pagination, where each page is identified by the ID of the record from the previous page. For example, if an endpoint returns 3 records with IDs 100, 101 and 102 for the URL /example-endpoint?limit=3, you can get the next 3 endpoints using the ID of the last record: /example-endpoint?limit=3&after_id=102.

Job openings

Job openings collection

List all job openings
GET/openings

Example URI

GET https://api.hire.toggl.com/api/v2.1/openings
Request
HideShow
Headers
Authorization: Bearer xyz
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "id": "100",
      "name": "Senior JavaScript Developer",
      "slug": "JFHSAK2879FLKJE",
      "created_at": "2020-02-10T10:00:00",
      "published_at": "2020-02-10T10:00:00",
      "closed_at": "2020-02-10T10:00:00"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the job opening"
          },
          "name": {
            "type": "string",
            "description": "Name of the job opening"
          },
          "slug": {
            "type": "string",
            "description": "Public unique identifier for the job opening\n\nThe job opening link can be constructed by appending the slug to `https://apply.hire.toggl.com/`, for example `https://apply.hire.toggl.com/KLJFD9283FLKDJ`."
          },
          "created_at": {
            "type": "string",
            "description": "Date and time when the job opening was created"
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "Date and time when the job opening was published\n\nThis is usually the same as when the job opening was created, except for some older job openings."
          },
          "closed_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "Date and time when the job opening was closed\n\nIf this value is not `null` the job opening is closed and candidates cannot take the test anymore"
          }
        }
      }
    }
  }
}

Job opening

Get a single job opening
GET/openings/{id}

Example URI

GET https://api.hire.toggl.com/api/v2.1/openings/100
URI Parameters
HideShow
id
string (required) Example: 100

ID of the requested job opening

Request
HideShow
Headers
Authorization: Bearer xyz
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "100",
  "name": "Senior JavaScript Developer",
  "slug": "JFHSAK2879FLKJE",
  "created_at": "2020-02-10T10:00:00",
  "published_at": "2020-02-10T10:00:00",
  "closed_at": "2020-02-10T10:00:00"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the job opening"
    },
    "name": {
      "type": "string",
      "description": "Name of the job opening"
    },
    "slug": {
      "type": "string",
      "description": "Public unique identifier for the job opening\n\nThe job opening link can be constructed by appending the slug to `https://apply.hire.toggl.com/`, for example `https://apply.hire.toggl.com/KLJFD9283FLKDJ`."
    },
    "created_at": {
      "type": "string",
      "description": "Date and time when the job opening was created"
    },
    "published_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "Date and time when the job opening was published\n\nThis is usually the same as when the job opening was created, except for some older job openings."
    },
    "closed_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "Date and time when the job opening was closed\n\nIf this value is not `null` the job opening is closed and candidates cannot take the test anymore"
    }
  }
}

Candidates

Candidates collection

Note that the candidates collection will return only candidates who have submitted the test and it will not return any demo candidates.

The parameters are combined using the AND operator, meaning that the candidate must match every parameter to be included in the result.

List candidates
GET/candidates{?job_opening_id,category_id,tag_ids,hire_state,min_score,max_score,min_rating,max_rating,email,after_id,limit,order}

Example URI

GET https://api.hire.toggl.com/api/v2.1/candidates?job_opening_id=100&category_id=200&tag_ids=300,301,302&hire_state=possible-hire&min_score=40&max_score=70&min_rating=1&max_rating=3&email=john@example.com&after_id=200&limit=30&order=asc
URI Parameters
HideShow
job_opening_id
string (optional) Example: 100

Returns candidates from the specified job opening

category_id
string (optional) Example: 200

Returns candidates from the specified category

tag_ids
string (optional) Example: 300,301,302

Returns candidates that have all of the specified tags

To specify multiple tags, separate the IDs with a comma, for example: 100,200,300

hire_state
string (optional) Example: possible-hire

Returns candidates with the specified hire state

Choices: possible-hire rejected

min_score
number (optional) Example: 40

Returns candidates with at least the specified score

max_score
number (optional) Example: 70

Returns candidates with at most the specified score

min_rating
number (optional) Example: 1

Returns candidates with at least the specified rating

Rating corresponds to the stars in the application, so 1 star = rating value 1, 3 stars = rating value 3.

max_rating
number (optional) Example: 3

Returns candidates with at most the specified rating

email
string (optional) Example: john@example.com

Returns candidates with the specified email address

after_id
string (optional) Example: 200

Used for pagination; returns candidates after the candidate with the specified ID

limit
number (optional) Default: 100 Example: 30

Returns only at most the specified number of candidates

order
string (optional) Default: asc Example: asc

Sorts the candidates based on the started_at attribute in ascending or descending order

Choices: asc desc

Request
HideShow
Headers
Authorization: Bearer xyz
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "id": "100",
      "name": "Cord Briemer",
      "email": "rosario84@real.com",
      "profile_url": "https://github.com/debitis",
      "contact_info": {
        "full_name": "Cord Briemer",
        "contact_email": "acarmona@duran-gomez.info",
        "linkedin": "https://linkedin.com/in/debitis",
        "phone": "+49(0)9859 103312",
        "city": "Lake Justinville",
        "country": "Gibraltar"
      },
      "started_at": "2019-03-10T02:39:32.59275",
      "finished_at": "2019-03-10T02:53:29.05823",
      "points": 12,
      "score": 85.714286,
      "rating": 0,
      "hire_state": "possible-hire",
      "category_id": "100",
      "job_opening_id": "100"
    }
  ],
  "links": {
    "next": "Hello, world!"
  },
  "total": 1
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the candidate"
          },
          "name": {
            "type": "string",
            "description": "Name of the candidate retrieved from their third party login provider\n\nNote that this can be an empty string, for example if the candidate has no name set in their GitHub profile."
          },
          "email": {
            "type": "string",
            "description": "Email of the candidate retrieved from their third party login provider"
          },
          "profile_url": {
            "type": "string",
            "description": "Profile URL retrieved from the candidate's third party login provider\n\nNote that the profile URL is available only if the candidate uses GitHub to log in."
          },
          "contact_info": {
            "type": "object",
            "properties": {
              "full_name": {
                "type": "string",
                "description": "Candidate's full name"
              },
              "contact_email": {
                "type": "string",
                "description": "Candidate's preferred contact email address"
              },
              "linkedin": {
                "type": "string",
                "description": "Candidate's LinkedIn profile URL"
              },
              "phone": {
                "type": "string",
                "description": "Candidate's phone number"
              },
              "city": {
                "type": "string",
                "description": "Candidate's city"
              },
              "country": {
                "type": "string",
                "description": "Candidate's country"
              }
            },
            "description": "Contact info submitted by the candidate after they have finished the test"
          },
          "started_at": {
            "type": "string",
            "description": "Date and time when the candidate started the test"
          },
          "finished_at": {
            "type": "string",
            "description": "Date and time when the candidate finished the test"
          },
          "points": {
            "type": "number",
            "description": "Total number of points that the candidate scored for all answers"
          },
          "score": {
            "type": "number",
            "description": "Percentage score calculated as `(actual points) / (maximum points)`"
          },
          "rating": {
            "type": "number",
            "enum": [
              0,
              1,
              2,
              3
            ],
            "description": "Candidate's star rating"
          },
          "hire_state": {
            "type": "string",
            "enum": [
              "possible-hire",
              "rejected",
              "(empty string)"
            ],
            "description": "Candidate's hire state"
          },
          "category_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "ID of the candidate's category"
          },
          "job_opening_id": {
            "type": "string",
            "description": "ID of the candidate's job opening"
          }
        }
      }
    },
    "links": {
      "type": "object",
      "properties": {
        "next": {
          "type": "string",
          "description": "URL that can be used to fetch the next page"
        }
      }
    },
    "total": {
      "type": "number",
      "description": "Total number of candidates matching the parameters"
    }
  }
}

Candidate

Fetch a candidate
GET/candidates/{id}

Example URI

GET https://api.hire.toggl.com/api/v2.1/candidates/id
URI Parameters
HideShow
id
string (required) 

ID of the requested candidate

Request
HideShow
Headers
Authorization: Bearer xyz
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "100",
  "name": "Cord Briemer",
  "email": "rosario84@real.com",
  "profile_url": "https://github.com/debitis",
  "contact_info": {
    "full_name": "Cord Briemer",
    "contact_email": "acarmona@duran-gomez.info",
    "linkedin": "https://linkedin.com/in/debitis",
    "phone": "+49(0)9859 103312",
    "city": "Lake Justinville",
    "country": "Gibraltar"
  },
  "started_at": "2019-03-10T02:39:32.59275",
  "finished_at": "2019-03-10T02:53:29.05823",
  "points": 12,
  "score": 85.714286,
  "rating": 0,
  "hire_state": "possible-hire",
  "category_id": "100",
  "job_opening_id": "100",
  "tag_ids": [
    "Hello, world!"
  ],
  "questions": [
    {
      "id": 400,
      "question_type": "single-choice",
      "skill": "Personality",
      "content": "Which one describes **you** better?",
      "points": 3,
      "options": [
        {
          "id": "500",
          "content": "Done is better than perfect",
          "correct": true
        }
      ]
    }
  ],
  "answers": [
    {
      "question_id": "400",
      "text_answer": "Hello, world!",
      "points": 3,
      "chosen_option_ids": [
        "Hello, world!"
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the candidate"
    },
    "name": {
      "type": "string",
      "description": "Name of the candidate retrieved from their third party login provider\n\nNote that this can be an empty string, for example if the candidate has no name set in their GitHub profile."
    },
    "email": {
      "type": "string",
      "description": "Email of the candidate retrieved from their third party login provider"
    },
    "profile_url": {
      "type": "string",
      "description": "Profile URL retrieved from the candidate's third party login provider\n\nNote that the profile URL is available only if the candidate uses GitHub to log in."
    },
    "contact_info": {
      "type": "object",
      "properties": {
        "full_name": {
          "type": "string",
          "description": "Candidate's full name"
        },
        "contact_email": {
          "type": "string",
          "description": "Candidate's preferred contact email address"
        },
        "linkedin": {
          "type": "string",
          "description": "Candidate's LinkedIn profile URL"
        },
        "phone": {
          "type": "string",
          "description": "Candidate's phone number"
        },
        "city": {
          "type": "string",
          "description": "Candidate's city"
        },
        "country": {
          "type": "string",
          "description": "Candidate's country"
        }
      },
      "description": "Contact info submitted by the candidate after they have finished the test"
    },
    "started_at": {
      "type": "string",
      "description": "Date and time when the candidate started the test"
    },
    "finished_at": {
      "type": "string",
      "description": "Date and time when the candidate finished the test"
    },
    "points": {
      "type": "number",
      "description": "Total number of points that the candidate scored for all answers"
    },
    "score": {
      "type": "number",
      "description": "Percentage score calculated as `(actual points) / (maximum points)`"
    },
    "rating": {
      "type": "number",
      "enum": [
        0,
        1,
        2,
        3
      ],
      "description": "Candidate's star rating"
    },
    "hire_state": {
      "type": "string",
      "enum": [
        "possible-hire",
        "rejected",
        "(empty string)"
      ],
      "description": "Candidate's hire state"
    },
    "category_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "ID of the candidate's category"
    },
    "job_opening_id": {
      "type": "string",
      "description": "ID of the candidate's job opening"
    },
    "tag_ids": {
      "type": "array",
      "description": "IDs of tags assigned to the candidate"
    },
    "questions": {
      "type": "array",
      "description": "Questions shown to the candidate"
    },
    "answers": {
      "type": "array",
      "description": "Answers the candidate provided"
    }
  }
}

Categories

Categories collection

List all categories
GET/categories{?job_opening_id}

Example URI

GET https://api.hire.toggl.com/api/v2.1/categories?job_opening_id=
URI Parameters
HideShow
job_opening_id
number (optional) 

Returns only categories from the specified job opening

Request
HideShow
Headers
Authorization: Bearer xyz
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "id": "100",
      "name": "Interview",
      "job_opening_id": "200"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the category"
          },
          "name": {
            "type": "string",
            "description": "Name of the category"
          },
          "job_opening_id": {
            "type": "string",
            "description": "ID of the job opening the category belongs to"
          }
        }
      }
    }
  }
}

Tags

Tags collection

List all tags
GET/tags

Example URI

GET https://api.hire.toggl.com/api/v2.1/tags
Request
HideShow
Headers
Authorization: Bearer xyz
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "id": "100",
      "name": "optimistic"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the tag"
          },
          "name": {
            "type": "string",
            "description": "Name of the tag"
          }
        }
      }
    }
  }
}

Generated by aglio on 02 Oct 2020