Skip to main content

Creating a Guide API Key

Create an API key to read interviewer pool data and more

A Guide API key lets another tool your company uses look up people and interviewer pools from your Guide account. The key only works for your own account, and every endpoint below is read-only. Creating a key does not change scheduling, people, or your other settings.

Create a key

Go to Settings, then Integrations, and find Guide API keys. Admins can create a key.

Click Create new API key. Guide shows the full key once. Copy it before you close the window. After that, the page shows only the last four characters, who created it, and when. Guide cannot show the full key again, and there is no option in Settings to turn a key off.

Treat the key like a password. Anyone who has it can read the information below for your whole account.
​
The key will offer read access to the following account data:

Users in your Guide account

  • Email address

  • Time zone

  • The days and hours they are available to interview

  • How many interviews they can take in a day, and in a week, when those limits are set

  • Note: People who are no longer active on the account can still appear in this list.

Interviewer pools

  • The name of each pool

  • How many shadow interviews, and how many reverse shadow interviews, someone needs to complete for that pool

  • Who is currently on the pool

  • Whether each person is qualified

  • How many shadow interviews and reverse shadow interviews they have already completed

  • Note: Archived pools are left out. Only people who are still active appear on a pool.

Calling the API

Send the key on every request in a header named api_key. Use the same Guide address you sign in on. The examples below use https://app.guide.co.

curl https://app.guide.co/api/external/users \   -H "api_key: YOUR_KEY"

A successful response has "success": true plus the data for that endpoint. A failed response has "success": false and an error message.

A missing or wrong key returns 401 and "Invalid API key". These endpoints accept GET only. Any other method returns 405.

List endpoints return up to 50 items at a time. Add maxResults to ask for a different page size, from 1 to 250. When more results remain, the response includes a nextPageToken. Send that value back as pageToken to get the next page. nextPageToken is null on the last page.

curl "https://app.guide.co/api/external/users?maxResults=50&pageToken=TOKEN_FROM_THE_PREVIOUS_RESPONSE" \   -H "api_key: YOUR_KEY"

People

GET /api/external/users

Everyone on your account, including people who are no longer active.

Each person includes:

  • email

  • timezone

  • workingHours, seven days from Monday through Sunday. A working day has isWorkingDay: true plus startTime and endTime, each with hour and minute. A day off has isWorkingDay: false.

  • maxInterviewsPerDay and maxInterviewsPerWeek, or null when no limit is set

{   "success": true,   "users": [     {       "email": "ada@example.com",       "timezone": "America/Los_Angeles",       "workingHours": [         {           "isWorkingDay": true,           "startTime": { "hour": 9, "minute": 0 },           "endTime": { "hour": 17, "minute": 0 }         }       ],       "maxInterviewsPerDay": 2,       "maxInterviewsPerWeek": 5     }   ],   "nextPageToken": null }

The example above shows one day. A real response has one entry per day.

GET /api/external/users/{email}

The same details for one person. Put the email in the path, and encode @ as %40.

curl https://app.guide.co/api/external/users/ada%40example.com \   -H "api_key: YOUR_KEY"

The person comes back under user. An email that is not on your account returns 404 and "User not found".

Interviewer pools

GET /api/external/interviewer-pools

Your current interviewer pools. Archived pools are left out.

Each pool includes:

  • id and name

  • shadowerInterviewCount, how many shadow interviews someone needs to complete for this pool

  • reverseShadowerInterviewCount, how many reverse shadow interviews they need

  • createdAt and updatedAt

{   "success": true,   "interviewerPools": [     {       "id": "22222222-2222-2222-2222-222222222222",       "name": "Technical screen",       "shadowerInterviewCount": 2,       "reverseShadowerInterviewCount": 1,       "createdAt": "2024-01-15T10:30:00.000Z",       "updatedAt": "2024-01-15T10:30:00.000Z"     }   ],   "nextPageToken": null }

GET /api/external/interviewer-pools/{id}

One pool, using the id from the list. The pool comes back under interviewerPool.

A pool that is missing, archived, or on another account returns 404. The error text is "Training path not found".

GET /api/external/interviewer-pools/{id}/members

The people currently on that pool. Only active people are included.

Each person has the same fields as in the people endpoints, plus:

  • isQualified, whether they are qualified to interview for this pool

  • shadowsCompleted

  • reverseShadowsCompleted

Those people come back under users, with a nextPageToken when the list continues. A missing, archived, or other-account pool returns the same 404 as the single-pool request.

What this API does not include

These endpoints cover people and interviewer pools only. They do not return candidates, scheduled interviews, or anything from your ATS. A key always covers the whole account. It cannot be limited to one person or one pool.

Did this answer your question?