Skip to main content

​
What are candidate keys?

Candidate keys are one-time access codes in the format PST-XXXX-XXXX. Each key links a specific candidate to an assessment. When a candidate runs promptster start PST-XXXX-XXXX, their session is automatically associated with your assessment and your organization’s scoring rubric. Keys are valid until their expiry date (set by the assessment’s expiresInDays value) or until they are revoked.

​
Generate keys

POST /v1/assessments/:id/keys Generates one or more candidate keys for an assessment. If you supply candidateEmails, invite emails are sent automatically.

​
Request body

​
count
integer
required
Number of keys to generate. Must be between 1 and 50.
​
candidateEmails
string[]
Candidate email addresses. When provided, Promptster sends each candidate an invite email containing their key. Must have the same number of entries as count if provided.
​
candidateNames
string[]
Candidate display names used in invite emails and the reviewer dashboard. Must match the length of candidateEmails if provided.
​
orgName
string
Your company name as it appears in the invite email.

​
Example request

curl -X POST https://api.promptster.ai/v1/assessments/ASSESSMENT_ID/keys \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "count": 2,
    "candidateEmails": ["alice@example.com", "bob@example.com"],
    "candidateNames": ["Alice Smith", "Bob Jones"],
    "orgName": "Acme Corp"
  }'

​
Example response

Returns 201 Created with an array of generated key objects. 
{
  "keys": [
    {
      "id": "ckid_aaa111",
      "key": "PST-AB3Z-QW7R",
      "assessmentId": "01234567-89ab-cdef-0123-456789abcdef",
      "orgId": "org_abc123",
      "candidateEmail": "alice@example.com",
      "candidateName": "Alice Smith",
      "status": "pending",
      "expiresAt": "2026-04-08T10:00:00Z",
      "redeemedAt": null,
      "completedAt": null
    },
    {
      "id": "ckid_bbb222",
      "key": "PST-MN4K-XY9T",
      "assessmentId": "01234567-89ab-cdef-0123-456789abcdef",
      "orgId": "org_abc123",
      "candidateEmail": "bob@example.com",
      "candidateName": "Bob Jones",
      "status": "pending",
      "expiresAt": "2026-04-08T10:00:00Z",
      "redeemedAt": null,
      "completedAt": null
    }
  ]
}

​
Response fields (per key)

​
id
string
Internal ID for the candidate key record. Use this to revoke a specific key.
​
key
string
The PST-XXXX-XXXX access code you send to the candidate.
​
assessmentId
string
UUID of the associated assessment.
​
candidateEmail
string | null
Candidate email address, or null if not provided.
​
candidateName
string | null
Candidate display name, or null if not provided.
​
status
string
Current key status. See Key lifecycle below.
​
expiresAt
string
ISO 8601 timestamp after which the key can no longer be redeemed.
​
redeemedAt
string | null
ISO 8601 timestamp of when the candidate ran promptster start, or null if not yet redeemed.
​
completedAt
string | null
ISO 8601 timestamp of when the candidate ran promptster done, or null if not yet completed.

​
List keys

GET /v1/assessments/:id/keys Returns all active (non-revoked) keys for an assessment, ordered by creation date, with their current status. 
curl https://api.promptster.ai/v1/assessments/ASSESSMENT_ID/keys \
  -H "Authorization: Bearer <your-token>"

​
Revoke a key

DELETE /v1/assessments/:id/keys/:keyId Soft-deletes a single candidate key. The candidate can no longer use this key to start an assessment. Revoked keys do not appear in subsequent list responses. 
curl -X DELETE https://api.promptster.ai/v1/assessments/ASSESSMENT_ID/keys/KEY_ID \
  -H "Authorization: Bearer <your-token>"
Returns { "ok": true, "id": "<keyId>" } on success.

​
Key lifecycle

Every candidate key moves through a defined set of statuses:
StatusMeaning
pendingGenerated but not yet redeemed. The candidate has not run promptster start.
redeemedThe candidate ran promptster start — their session is in progress.
completedThe candidate ran promptster done — the session has been submitted for scoring.
expiredThe key passed its expiry date without the session being completed.
hiredManually marked by a reviewer to indicate the candidate was hired.

​
List all candidates across assessments

GET /v1/candidates Returns a paginated list of all candidates across your entire organization, joined with their assessment details.

​
Query parameters

​
limit
integer
Number of results per page. Defaults to 50, maximum 200.
​
offset
integer
Number of results to skip for pagination. Defaults to 0.

​
Example request

curl "https://api.promptster.ai/v1/candidates?limit=50&offset=0" \
  -H "Authorization: Bearer <your-token>"

​
Example response

{
  "candidates": [
    {
      "id": "ckid_aaa111",
      "key": "PST-AB3Z-QW7R",
      "candidateName": "Alice Smith",
      "candidateEmail": "alice@example.com",
      "status": "completed",
      "sessionId": "sess_xyz789",
      "assessmentId": "01234567-89ab-cdef-0123-456789abcdef",
      "assessmentTitle": "Backend API Challenge",
      "redeemedAt": "2026-04-02T09:00:00Z",
      "completedAt": "2026-04-02T11:30:00Z",
      "expiresAt": "2026-04-08T10:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

​
Response fields

​
candidates
array
Array of candidate key records, each enriched with assessmentId and assessmentTitle from the linked assessment.
​
total
integer
Total number of candidates across your organization (before pagination).
​
limit
integer
The effective page size used for this response.
​
offset
integer
The offset applied for this response.