curl --request POST \
  --url https://api-{region}.sesametime.com/poll/v1/evaluations/candidate-recruitment/{evaluationId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "candidateId": "123e4567-e89b-12d3-a456-426614174000",
  "answers": [
    {
      "questionId": "123e4567-e89b-12d3-a456-426614174001",
      "questionOptionIds": [
        "123e4567-e89b-12d3-a456-426614174010"
      ],
      "comment": "Answer for radio question - single choice"
    },
    {
      "questionId": "123e4567-e89b-12d3-a456-426614174002",
      "questionOptionIds": [
        "123e4567-e89b-12d3-a456-426614174011",
        "123e4567-e89b-12d3-a456-426614174012"
      ],
      "comment": "Answer for check question - multiple choices"
    },
    {
      "questionId": "123e4567-e89b-12d3-a456-426614174003",
      "answer": "The candidate demonstrates excellent communication skills and works well in team environments.",
      "comment": "Answer for text question - free text response"
    },
    {
      "questionId": "123e4567-e89b-12d3-a456-426614174004",
      "answer": "8.5",
      "comment": "Answer for float question - numeric value"
    },
    {
      "questionId": "123e4567-e89b-12d3-a456-426614174005",
      "questionOptionIds": [
        "123e4567-e89b-12d3-a456-426614174015"
      ],
      "comment": "Answer for stars question - star rating"
    }
  ]
}
'

This response has no body data.

{
  "message": "Validation failed",
  "errors": [
    {
      "field": "questionId",
      "message": "This value is not a valid UUID."
    },
    {
      "field": "answer",
      "message": "This field is required for text-based questions."
    }
  ]
}

{
  "message": "Evaluation with ID 123e4567-e89b-12d3-a456-426614174000 was not found",
  "code": "EVALUATION_NOT_FOUND"
}

{
  "message": "Cannot submit answers for an evaluation that has already been completed",
  "code": "EVALUATION_ALREADY_COMPLETED",
  "conflictDetails": {
    "currentState": "completed",
    "completedAt": "2024-01-15T10:30:00Z"
  }
}

Polls

Answer a candidate recruitment evaluation

Submit answers for a candidate recruitment evaluation. Each answer must include either ‘questionOptionIds’ for choice-based questions or ‘answer’ for text-based questions, but not both. The required field depends on the question type:

Choice-based questions (require questionOptionIds):

radio: Single choice selection
check: Multiple choice selection
faces: Emoji/face rating selection
range: Numeric range selection
ranking: Order-based selection
stars: Star rating selection
organization_chart: Organizational hierarchy selection

Text-based questions (require answer):

text: Free text response
float: Numeric value input

POST

poll

evaluations

candidate-recruitment

{evaluationId}

curl --request POST \
  --url https://api-{region}.sesametime.com/poll/v1/evaluations/candidate-recruitment/{evaluationId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "candidateId": "123e4567-e89b-12d3-a456-426614174000",
  "answers": [
    {
      "questionId": "123e4567-e89b-12d3-a456-426614174001",
      "questionOptionIds": [
        "123e4567-e89b-12d3-a456-426614174010"
      ],
      "comment": "Answer for radio question - single choice"
    },
    {
      "questionId": "123e4567-e89b-12d3-a456-426614174002",
      "questionOptionIds": [
        "123e4567-e89b-12d3-a456-426614174011",
        "123e4567-e89b-12d3-a456-426614174012"
      ],
      "comment": "Answer for check question - multiple choices"
    },
    {
      "questionId": "123e4567-e89b-12d3-a456-426614174003",
      "answer": "The candidate demonstrates excellent communication skills and works well in team environments.",
      "comment": "Answer for text question - free text response"
    },
    {
      "questionId": "123e4567-e89b-12d3-a456-426614174004",
      "answer": "8.5",
      "comment": "Answer for float question - numeric value"
    },
    {
      "questionId": "123e4567-e89b-12d3-a456-426614174005",
      "questionOptionIds": [
        "123e4567-e89b-12d3-a456-426614174015"
      ],
      "comment": "Answer for stars question - star rating"
    }
  ]
}
'

This response has no body data.

{
  "message": "Validation failed",
  "errors": [
    {
      "field": "questionId",
      "message": "This value is not a valid UUID."
    },
    {
      "field": "answer",
      "message": "This field is required for text-based questions."
    }
  ]
}

{
  "message": "Evaluation with ID 123e4567-e89b-12d3-a456-426614174000 was not found",
  "code": "EVALUATION_NOT_FOUND"
}

{
  "message": "Cannot submit answers for an evaluation that has already been completed",
  "code": "EVALUATION_ALREADY_COMPLETED",
  "conflictDetails": {
    "currentState": "completed",
    "completedAt": "2024-01-15T10:30:00Z"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

evaluationId

string<uuid>

required

Evaluation ID

Body

application/json

Recruitment evaluation that needs to be answered

answers

object[]

Array of answers for the evaluation questions

For choice-based questions (radio, check, faces, range, ranking, stars, organization_chart): questionOptionIds is required

Option 1
Option 2

Show child attributes

candidateId

string<uuid>

API Reference

Answer a candidate recruitment evaluation

Authorizations

Path Parameters

Body

Response