Account menu, then Integrations, then the API key section.
Your credentials
A credential is a key and a secret, used as a username and password pair.
The secret is shown once, when it is created. Save it somewhere safe at that moment. Reveal on the integrations page shows the key only; it cannot show you the secret again. If you have lost it, regenerate the credential and update whatever was using it.
Authenticating a request
HTTP Basic authentication. The key is the username, the secret is the password.
Authorization: Basic <base64 of key:secret>
Most HTTP clients do this for you if you hand them the two values. The in-app guide has worked examples for Guzzle, HTTParty and Axios.
The base URL
https://api.picked.ai
The one endpoint
GET /assessment/candidates
Fetches your candidates with their assessments, sittings and attempts. It is scoped to the organisation the credential belongs to, so you cannot reach anyone else's data and nor can anyone reach yours.
Parameters
| Parameter | Meaning |
|---|---|
per_page |
How many records per page. There is a maximum, and asking for more returns an error rather than silently capping. |
sort_by |
Only created_at is accepted. |
sort_order |
asc or desc. |
The response is paginated and carries the sort you asked for in its metadata.
What the API cannot do
It is read-only, and this is the only endpoint. You cannot create an assessment, invite a candidate, unlock a result or change a setting through it. Anything that writes has to happen in the app.
Plan around that before you design something. If your plan requires writing, it is not going to work today, and it is better to find that out now than after a sprint.
Locked results
A result that has not been unlocked for your organisation is not readable through the API any more than it is in the app. Unlock it first. See unlock results.
Regenerating your key
Regenerate issues a new key and secret and the old ones stop working immediately. There is no overlap period, so update your systems in the same sitting. You are shown both new values once and asked to confirm you have saved them.
Keeping your key secret
The key grants full access to your account's candidate data. See keep your API key safe.