Get Respondent

POST

getRespondent

curl --request POST \
  --url https://api.redem.io/getRespondent \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "surveyName": "Global Vacation Insights 2024",
  "respondentId": "RESP497770"
}'

{
  "success": true,
  "message": "Respondent quality successfully retrieved",
  "results": {
    "respondentId": "RESP497770",
    "status": "COMPLETED",
    "respondentQuality": {
      "isExcluded": true,
      "reasonsForExclusion": [
        "Open Ended Score Threshold",
        "Coherence Score Threshold"
      ],
      "redemScore": 85,
      "qualityScoreSummary": [
        {
          "qualityCheck": "OES",
          "score": 80
        },
        {
          "qualityCheck": "CHS",
          "score": 75,
          "reason": "The user shows several inconsistencies and contradictions, such as different ..."
        },
        {
          "qualityCheck": "GQS",
          "score": 85
        },
        {
          "qualityCheck": "TS",
          "score": 70
        },
        {
          "qualityCheck": "BAS",
          "score": 75
        }
      ],
      "dataPointsSummary": [
        {
          "qualityCheck": "OES",
          "dataPointId": "Q1",
          "score": 85,
          "category": "VALID_ANSWER"
        },
        {
          "qualityCheck": "TS",
          "dataPointId": "durationQ1",
          "score": 95
        },
        {
          "qualityCheck": "GQS",
          "dataPointId": "Q2",
          "score": 90
        },
        {
          "qualityCheck": "OES",
          "dataPointId": "Q3",
          "score": 75,
          "category": "VALID_ANSWER"
        },
        {
          "qualityCheck": "TS",
          "dataPointId": "durationQ3",
          "score": 50
        },
        {
          "qualityCheck": "CHS",
          "dataPointId": "CHS_Question",
          "score": 75,
          "reason": "The user shows several inconsistencies and contradictions, such as different ..."
        },
        {
          "qualityCheck": "GQS",
          "dataPointId": "Q4",
          "score": 80
        },
        {
          "qualityCheck": "TS",
          "dataPointId": "totalDuration",
          "score": 65
        },
        {
          "qualityCheck": "BAS",
          "dataPointId": "interactionsQ1",
          "score": 75,
          "category": "NATURAL_TYPING"
        }
      ]
    }
  }
}

Authorizations

api-key

string

header

required

Body

application/json

Request body for getting a respondent

surveyName

string

required

The name of the survery.

Example:

"Global Vacation Insights 2024"

respondentId

string

required

The unique identifier for a respondent, making it easy to distinguish them from others in the survey

Example:

"RESP497770"

Response

200

application/json

When a request is successfully processed, the API responds with a `200 OK` status code and the expected data. The structure of the response varies based on the respondent's status.

This response mode available when respondent status is COMPLETED.

In this case, the system generates a comprehensive, quality assessment of the respondent.

success

boolean

A variable indicating whether the operation was successful.

message

string

A variable that human-readable message providing additional context or confirmation of the requested action.

results

object

This variable includes all quality parameters associated with a respondent.

results.respondentId

string

A variable that indicates the respondent.

results.status

string

A variable that represents the current state of the respondent evaluation. For respondents who have been successfully evaluated, this value will always be COMPLETED.

results.respondentQuality

object

This variable represents respondent data that has been evaluated based on the quality checks specified in the /addRespondent request.

💡Important: Even if a respondent fails evaluation, the response will still be returned with results with an error code of -999 instead of valid scores.

⭕ Note: The value -999 is a predefined code returned by ReDem whenever a respondent cannot be evaluated. This applies to all quality scores, including ReDem Score (R-Score), OES, GQS, CHS, TS, and BAS.

results.respondentQuality.isExcluded

boolean

Indicates whether a respondent is excluded based on the cleaning settings specified in the request. If cleaning is not activated, the respondent is always included by default.

Example:

false

results.respondentQuality.reasonsForExclusion

string[]

Reasons for exclusion will only be available if the respondent is excluded based on the cleaning settings specified in the request. If the respondent is not excluded, the array will be empty.

results.respondentQuality.redemScore

number

A weighted average score (0–100) calculated based on the applied quality scores..

For more information refer to the ReDem Score section.

Example:

85

results.respondentQuality.qualityScoreSummary

object[]

An object containing detailed results for each quality score applied

Aggregated results for a quality score type

results.respondentQuality.qualityScoreSummary.qualityCheck

enum<string>

The specific type of quality check applied to a respondent.

Available options:

OES,

TS,

GQS,

CHS,

BAS

Example:

"OES"

results.respondentQuality.qualityScoreSummary.score

number

A numerical score from 0 to 100 that represents the overall result of a specific quality check. It is calculated based on the combined evaluation of all data point scores of the same quality type.

Example:

78

results.respondentQuality.qualityScoreSummary.reason

string

The reason behind the score — available only when the quality score type is set to CHS.

Example:

"The user shows several inconsistencies and contradictions, such as different ..."

results.respondentQuality.qualityScoreSummary.incoherentQuestions

string[]

List of incoherent questions identified during the CHS quality check. This will be only available if the quality score type is set to CHS

⭕ Note: The questions are named in numerical order, reflecting the sequence in which they were presented to the respondent.

Example:

["Q1", "Q2"]

results.respondentQuality.dataPointsSummary

object[]

Detailed results of quality checks performed at the individual data point level.

Quality check results for a single datapoint

This response mode available when respondent status is COMPLETED.

In this case, the system generates a comprehensive, quality assessment of the respondent.

success

boolean

A variable indicating whether the operation was successful.

message

string

A variable that human-readable message providing additional context or confirmation of the requested action.

results

object

This variable includes all quality parameters associated with a respondent.

results.respondentId

string

A variable that indicates the respondent.

results.status

string

A variable that represents the current state of the respondent evaluation. For respondents who have been successfully evaluated, this value will always be COMPLETED.

results.respondentQuality

object

This variable represents respondent data that has been evaluated based on the quality checks specified in the /addRespondent request.

💡Important: Even if a respondent fails evaluation, the response will still be returned with results with an error code of -999 instead of valid scores.

results.respondentQuality.isExcluded

boolean

Indicates whether a respondent is excluded based on the cleaning settings specified in the request. If cleaning is not activated, the respondent is always included by default.

Example:

false

results.respondentQuality.reasonsForExclusion

string[]

Reasons for exclusion will only be available if the respondent is excluded based on the cleaning settings specified in the request. If the respondent is not excluded, the array will be empty.

results.respondentQuality.redemScore

number

A weighted average score (0–100) calculated based on the applied quality scores..

For more information refer to the ReDem Score section.

Example:

85

results.respondentQuality.qualityScoreSummary

object[]

An object containing detailed results for each quality score applied

Aggregated results for a quality score type

results.respondentQuality.qualityScoreSummary.qualityCheck

enum<string>

The specific type of quality check applied to a respondent.

Available options:

OES,

TS,

GQS,

CHS,

BAS

Example:

"OES"

results.respondentQuality.qualityScoreSummary.score

number

Example:

78

results.respondentQuality.qualityScoreSummary.reason

string

The reason behind the score — available only when the quality score type is set to CHS.

Example:

"The user shows several inconsistencies and contradictions, such as different ..."

results.respondentQuality.qualityScoreSummary.incoherentQuestions

string[]

List of incoherent questions identified during the CHS quality check. This will be only available if the quality score type is set to CHS

⭕ Note: The questions are named in numerical order, reflecting the sequence in which they were presented to the respondent.

Example:

["Q1", "Q2"]

results.respondentQuality.dataPointsSummary

object[]

Detailed results of quality checks performed at the individual data point level.

Quality check results for a single datapoint

This response mode available when respondent status is QUEUED.

In this case, the system will only return the status of the respondent, without the quality assessment of the respondent.

success

boolean

A variable that indicates whether the operation was successful or not.

message

string

A variable that human-readable message providing additional context or confirmation of the requested action.

results

object

This object serves as a container to hold the results for the requested data, encapsulating all relevant information and outputs in a structured format.

Add Respondent Get All Respondents

curl --request POST \
  --url https://api.redem.io/getRespondent \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "surveyName": "Global Vacation Insights 2024",
  "respondentId": "RESP497770"
}'

{
  "success": true,
  "message": "Respondent quality successfully retrieved",
  "results": {
    "respondentId": "RESP497770",
    "status": "COMPLETED",
    "respondentQuality": {
      "isExcluded": true,
      "reasonsForExclusion": [
        "Open Ended Score Threshold",
        "Coherence Score Threshold"
      ],
      "redemScore": 85,
      "qualityScoreSummary": [
        {
          "qualityCheck": "OES",
          "score": 80
        },
        {
          "qualityCheck": "CHS",
          "score": 75,
          "reason": "The user shows several inconsistencies and contradictions, such as different ..."
        },
        {
          "qualityCheck": "GQS",
          "score": 85
        },
        {
          "qualityCheck": "TS",
          "score": 70
        },
        {
          "qualityCheck": "BAS",
          "score": 75
        }
      ],
      "dataPointsSummary": [
        {
          "qualityCheck": "OES",
          "dataPointId": "Q1",
          "score": 85,
          "category": "VALID_ANSWER"
        },
        {
          "qualityCheck": "TS",
          "dataPointId": "durationQ1",
          "score": 95
        },
        {
          "qualityCheck": "GQS",
          "dataPointId": "Q2",
          "score": 90
        },
        {
          "qualityCheck": "OES",
          "dataPointId": "Q3",
          "score": 75,
          "category": "VALID_ANSWER"
        },
        {
          "qualityCheck": "TS",
          "dataPointId": "durationQ3",
          "score": 50
        },
        {
          "qualityCheck": "CHS",
          "dataPointId": "CHS_Question",
          "score": 75,
          "reason": "The user shows several inconsistencies and contradictions, such as different ..."
        },
        {
          "qualityCheck": "GQS",
          "dataPointId": "Q4",
          "score": 80
        },
        {
          "qualityCheck": "TS",
          "dataPointId": "totalDuration",
          "score": 65
        },
        {
          "qualityCheck": "BAS",
          "dataPointId": "interactionsQ1",
          "score": 75,
          "category": "NATURAL_TYPING"
        }
      ]
    }
  }
}

How to integrate

API Specifications

Endpoints

Others

Authorizations

Body

Response