Skip to content
/
Create Participant or Ret...

Clearspeed Integration API

Overview

The Clearspeed Integration API enables you to programmatically manage participants within your questionnaires — create new participants, initiate retakes, and update outcome tracking. Additionally, Clearspeed delivers assessment results directly to your system via webhooks, eliminating the need to poll for results.

Authentication

All requests must include your API key in the Authorization header:

Authorization: <your-api-key>

API keys are scoped to a specific questionnaire and carry explicit permissions. Your first key must be created from the Clearspeed web application by a questionnaire Admin. Once you have a key with the apikey:write scope you can create additional keys via the API.

See the API Keys & Authentication guide for a step-by-step walkthrough and a full description of all available scopes.

Environments

RegionBase URL
US Productionhttps://api.us.clearspeed.com/questionnaire/v1
UK Productionhttps://api.uk.clearspeed.com/questionnaire/v1
Download OpenAPI description
integration-api.json
integration-api.yaml
Languages
Servers
US Production server
https://api.us.clearspeed.com/questionnaire/v1
UK Production server
https://api.uk.clearspeed.com/questionnaire/v1

Create Participant or Retake Questionnaire

Request

Create a new participant or retake a questionnaire for an existing participant.

Behavior is determined by request body:

  • If participant_uuid is not provided, a new participant is created.
  • If participant_uuid is provided, retake flow is used for that participant.
Security
authorization
Bodyapplication/jsonrequired
One of:
project_uuidstringrequired

UUID of the project/questionnaire

Example: "fd9690b0-9050-4acd-ad74-7f906c07fe93"
phone_number1string

Primary phone number (optional)

Example: "+916263877039"
phone_number2string

Secondary phone number (optional)

Example: ""
interview_ref_numstringrequired

Interview reference number

Example: "7858934895810"
external_ref_idstring

External reference ID (optional)

Example: "12345-46b5-464d-a8e4-afecc"
emailstring

Email address (optional)

Example: "participant@gmail.com"
languagestring

Language name (optional)

Example: "English"
curl -i -X POST \
  https://api.us.clearspeed.com/questionnaire/v1/participant \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "project_uuid": "fd9690b0-9050-4acd-ad74-7f906c07fe93",
    "phone_number1": "+916263877039",
    "phone_number2": "",
    "interview_ref_num": "7858934895810",
    "external_ref_id": "12345-46b5-464d-a8e4-afecc",
    "email": "participant@gmail.com",
    "language": "English"
  }'

Responses

Participant created or questionnaire retake initiated

Bodyapplication/json
project_uuidstring

UUID of the project/questionnaire

Example: "fd9690b0-9050-4acd-ad74-7f906c07fe93"
phone_number1string

Primary phone number

Example: "+916263877039"
phone_number2string

Secondary phone number

Example: ""
interview_ref_numstring

Interview reference number

Example: "7858934895810"
external_ref_idstring

External reference ID

Example: "12345-46b5-464d-a8e4-afecc"
participant_uuidstring

UUID of the participant

Example: "01977df0-57c1-7dcf-8916-df741aa66691"
emailstring

Email address

Example: "participant@gmail.com"
languagestring

Participant language

Example: "English"
particpant_guide_linkstring

Link to the participant guide

Example: "https://guide.example.com?id=01977df0-57c1-7dcf-8916-df741aa66691"
is_participant_allowedboolean

Whether participant is allowed after call-blocking checks

Example: true
outcomestring or null
outcome_tsstring or null
Response
application/json
{
  "project_uuid": "fd9690b0-9050-4acd-ad74-7f906c07fe93",
  "phone_number1": "+916263877039",
  "phone_number2": "",
  "interview_ref_num": "7858934895810",
  "external_ref_id": "12345-46b5-464d-a8e4-afecc",
  "participant_uuid": "01977df0-57c1-7dcf-8916-df741aa66691",
  "email": "participant@gmail.com",
  "language": "English",
  "particpant_guide_link": "https://guide.example.com?id=01977df0-57c1-7dcf-8916-df741aa66691",
  "is_participant_allowed": true,
  "outcome": null,
  "outcome_ts": null
}

Update participant outcome tracking

Request

Update the outcome tracking fields for an existing participant using the v1 external API format.

  • Authenticated using the authorization header.
  • Validates that the API key is associated with the participant's questionnaire tenant.
  • Updates the participant's outcome and optional outcome timestamp.
Security
authorization
Path
participant_idstring(uuid)required

UUID of the participant whose outcome tracking should be updated

Bodyapplication/jsonrequired
outcomestringrequired

Outcome code to set for the participant

Example: "$10,Reviewed and Mitigated"
outcome_tsstring(date-time)

Outcome timestamp in RFC3339 format. If omitted, the current UTC time will be used.

Example: "2025-12-12T06:06:29Z"
curl -i -X PUT \
  'https://api.us.clearspeed.com/questionnaire/v1/participant/{participant_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "outcome": "$10,Reviewed and Mitigated",
    "outcome_ts": "2025-12-12T06:06:29Z"
  }'

Responses

Outcome tracking updated successfully

Bodyapplication/json
project_uuidstring

UUID of the project/questionnaire

Example: "fd9690b0-9050-4acd-ad74-7f906c07fe93"
phone_number1string

Primary phone number

Example: "+916263877039"
phone_number2string

Secondary phone number

Example: ""
interview_ref_numstring

Interview reference number

Example: "7858934895810"
external_ref_idstring

External reference ID

Example: "12345-46b5-464d-a8e4-afecc"
participant_uuidstring

UUID of the participant

Example: "01977df0-57c1-7dcf-8916-df741aa66691"
emailstring

Email address

Example: "participant@gmail.com"
languagestring

Participant language

Example: "English"
particpant_guide_linkstring

Link to the participant guide

Example: "https://guide.example.com?id=01977df0-57c1-7dcf-8916-df741aa66691"
is_participant_allowedboolean

Whether participant is allowed after call-blocking checks

Example: true
outcomestring or null

Outcome code for the participant

Example: "$10,Reviewed and Mitigated"
outcome_tsstring or null(date-time)

Outcome timestamp in RFC3339 format

Example: "2025-12-12T06:06:29Z"
Response
application/json
{
  "project_uuid": "fd9690b0-9050-4acd-ad74-7f906c07fe93",
  "phone_number1": "+916263877039",
  "phone_number2": "",
  "interview_ref_num": "7858934895810",
  "external_ref_id": "12345-46b5-464d-a8e4-afecc",
  "participant_uuid": "01977df0-57c1-7dcf-8916-df741aa66691",
  "email": "participant@gmail.com",
  "language": "English",
  "particpant_guide_link": "https://guide.example.com?id=01977df0-57c1-7dcf-8916-df741aa66691",
  "is_participant_allowed": true,
  "outcome": "$10,Reviewed and Mitigated",
  "outcome_ts": "2025-12-12T06:06:29Z"
}

Create API key

Request

Create a new API key for the specified questionnaire.

Requires a key with the apikey:write scope. The full key value is returned only in this response — store it securely immediately. Subsequent list calls return a masked version.

Security
authorization
Path
tenant_idstring(uuid)required

UUID of the tenant

questionnaire_idstring(uuid)required

UUID of the questionnaire

Bodyapplication/jsonrequired
key_namestringrequired

Human-readable name to identify this key

Example: "ci-participant-writer"
permissionsArray of stringsrequired

List of scopes to grant this key. Valid values:

  • participant:read — read participant records
  • participant:write — create participants and initiate retakes
  • participant:delete — delete participant records
  • apikey:write — create API keys for the same questionnaire
  • apikey:delete — delete API keys for the same questionnaire
Items Enum"participant:read""participant:write""participant:delete""apikey:write""apikey:delete"
Example: ["participant:write"]
curl -i -X POST \
  'https://api.us.clearspeed.com/questionnaire/v1/tenants/{tenant_id}/questionnaires/{questionnaire_id}/apikeys' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "key_name": "ci-participant-writer",
    "permissions": [
      "participant:write"
    ]
  }'

Responses

API key created. The api_key value is shown only once — save it now.

Bodyapplication/json
idstring(uuid)

Unique identifier of the API key

Example: "a1b2c3d4-0000-0000-0000-000000000001"
api_keystring

The API key value. Returned in full only on creation — masked in all subsequent responses.

Example: "cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
key_namestring

Human-readable name for the key

Example: "ci-participant-writer"
permissionsArray of strings

Scopes granted to this key

Example: ["participant:write"]
questionnaire_idstring(uuid)

UUID of the questionnaire this key is scoped to

Example: "fd9690b0-9050-4acd-ad74-7f906c07fe93"
create_tsstring(date-time)

Creation timestamp (UTC)

Example: "2026-04-10T10:00:00Z"
update_tsstring(date-time)

Last updated timestamp (UTC)

Example: "2026-04-10T10:00:00Z"
Response
application/json
{
  "id": "a1b2c3d4-0000-0000-0000-000000000001",
  "api_key": "cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key_name": "ci-participant-writer",
  "permissions": [
    "participant:write"
  ],
  "questionnaire_id": "fd9690b0-9050-4acd-ad74-7f906c07fe93",
  "create_ts": "2026-04-10T10:00:00Z",
  "update_ts": "2026-04-10T10:00:00Z"
}

List API keys

Request

Retrieve all API keys for the specified questionnaire.

Requires a key with the apikey:write or apikey:delete scope. Key values are masked in the response — only a partial value is visible.

Security
authorization
Path
tenant_idstring(uuid)required

UUID of the tenant

questionnaire_idstring(uuid)required

UUID of the questionnaire

curl -i -X GET \
  'https://api.us.clearspeed.com/questionnaire/v1/tenants/{tenant_id}/questionnaires/{questionnaire_id}/apikeys' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

List of API keys

Bodyapplication/jsonArray [
idstring(uuid)

Unique identifier of the API key

Example: "a1b2c3d4-0000-0000-0000-000000000001"
api_keystring

The API key value. Returned in full only on creation — masked in all subsequent responses.

Example: "cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
key_namestring

Human-readable name for the key

Example: "ci-participant-writer"
permissionsArray of strings

Scopes granted to this key

Example: ["participant:write"]
questionnaire_idstring(uuid)

UUID of the questionnaire this key is scoped to

Example: "fd9690b0-9050-4acd-ad74-7f906c07fe93"
create_tsstring(date-time)

Creation timestamp (UTC)

Example: "2026-04-10T10:00:00Z"
update_tsstring(date-time)

Last updated timestamp (UTC)

Example: "2026-04-10T10:00:00Z"
]
Response
application/json
[
  {
    "id": "a1b2c3d4-0000-0000-0000-000000000001",
    "api_key": "cs_live_xxxx...xxxx",
    "key_name": "ci-participant-writer",
    "permissions": [ … ],
    "questionnaire_id": "fd9690b0-9050-4acd-ad74-7f906c07fe93",
    "create_ts": "2026-04-10T10:00:00Z",
    "update_ts": "2026-04-10T10:00:00Z"
  }
]

Delete API key

Request

Permanently delete an API key. Requires the apikey:delete scope.

This action cannot be undone. Any integration using the deleted key will immediately start receiving 401 Unauthorized responses.

Security
authorization
Path
tenant_idstring(uuid)required

UUID of the tenant

questionnaire_idstring(uuid)required

UUID of the questionnaire

key_idstring(uuid)required

UUID of the API key to delete

curl -i -X DELETE \
  'https://api.us.clearspeed.com/questionnaire/v1/tenants/{tenant_id}/questionnaires/{questionnaire_id}/apikeys/{key_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

API key deleted successfully

Response
No content

Result Update Webhook
Webhook

Request

Clearspeed sends a POST request to the customer's webhook endpoint when a result is published or updated. Customers must return HTTP 200 to acknowledge receipt.

Bodyapplication/json
project_uuidstring
Example: "XXXXXXXX-ef1f-4d91-a2e2-7b33132b00f1"
callback_typestring
Example: "Result Update"
access_codestring
Example: "7136XXXX59"
interview_ref_numstring
Example: "456XXXX642"
statusstring
Example: "Result Published"
questions_risk_ratingArray of objects
Example: [{"sequence":"7","risk_level":"LR","text":"Q7 "},{"sequence":"2","risk_level":"HR","text":"Q2 "}]
overall_evaluationstring
Example: "HR"
is_admissionboolean
is_counter_measureboolean
is_not_completeboolean
participant_languagestring
Example: "English"
summarystring

Result summary label (for example, HR/LR/G/AR/NC)

Example: "AR"
summary_bgcolorstring

Hex color code associated with the summary label

Example: "#dc3545"
clearboolean

Whether result is clear

Example: true
timestampstring(date-time)
application/json
{
  "project_uuid": "XXXXXXXX-ef1f-4d91-a2e2-7b33132b00f1",
  "callback_type": "Result Update",
  "access_code": "7136XXXX59",
  "interview_ref_num": "456XXXX642",
  "status": "Result Published",
  "questions_risk_rating": [
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … }
  ],
  "overall_evaluation": "HR",
  "is_admission": false,
  "is_counter_measure": false,
  "is_not_complete": false,
  "participant_language": "English",
  "summary": "AR",
  "summary_bgcolor": "#dc3545",
  "clear": true
}

Responses

Result received