Skip to main content
POST
Add a new respondent

Authorizations

​
api-key
string
header
required

Body

application/json

Request body for adding a new respondent (v3 with OES v3 categories)

🔒 Authentication: This endpoint can be accessed using both PRIVATE and PUBLIC API key types

​
respondentId
string
required

The unique identifier for a respondent, making it easy to distinguish them from others in the survey. The respondent ID can be freely chosen for flexibility.

💡 Important: The system utilizes this ID, combined with the survey name, to uniquely identify the respondent within a survey. This allows the same respondent ID to participate in multiple surveys without conflicts.

If the combination of survey name and respondent ID already exists, an error will be displayed.

🔦 Tip: You can use the same respondent ID as in the survey tool to easily identify the respondent later.

Example:

"RESP497770"

​
surveyName
string
required

The name of the survery, which helps identify different surveys. The survey name can be assigned freely.

💡Important: If the survey name already exists, the system will add the respondent under the appropriate survey. If the survey name is new, a new survey will be created, and the respondent will be added to the new survey.

⭕ Note: Each survey identifier must be unique.

🔦 Tip: you can simply make survey name unique by adding a timestamp. As Example: Global Vacation Insights - 1709040600

​
dataPoints
(OES · object | TS · object | GQS · object | CHS · object | BAS · object)[]
required

An array of data points used for quality checks on each respondent. For the Coherence Score (CHS), only a single data point is allowed, which must contain the entire interview.

🧪 Validations:

  • A maximum of 30 OES data points are allowed per respondent.
  • A maximum of 500 TS data points are allowed per respondent.
  • A maximum of 20 GQS data points are allowed per respondent.
  • A maximum of 1 with 300 question/answer pairs CHS data point is allowed per respondent.
  • A maximum of 30 BAS data points are allowed per respondent.

Exceeding these limits will trigger validation errors. Ensure that the number of data points per respondent remains within the allowed limits.

An array of data points used to perform quality checks on each respondent.

​
surveyPlatform
string

Optional platform identifier for the source system where the respondent was collected (for example, Qualtrics, Decipher, or custom panel tooling). This helps identify the origin of respondents created through API integrations.

Recommendation for integrators: Always populate this field with a stable platform name for API-based survey tool integrations.

Example:

"qualtrics"

​
referenceSurveyId
string

Optional external survey identifier from your own system (for example, the project or survey id in your survey tool). When ReDem creates a new survey for the given surveyName, this value is stored on the survey. If the survey already exists, the existing stored value is not overwritten by a different referenceSurveyId in a later request.

​
activateCleaning
boolean
default:false

Indicates whether cleaning should be applied to the respondent.

💡Important: To get an indicator whether respondents should be removed from the sample, ensure this variable is set to true.

When cleaning is enabled, the response will include the variable isExcluded, which indicates whether the respondent has been excluded based on the applied criteria.

Example:

true

​
cleaningSettings
object

Cleaning settings define the rules for determining whether a respondent should be excluded and marked as low quality. If a respondent's scores fall below the threshold, they will be excluded and flagged as low quality.

💡Important: If no custom cleaning settings are defined and cleaning is enabled, the system will apply ReDem's recommended cleaning settings. You can view the recommended settings here: ReDem Recommended Cleaning Settings

For more details on how cleaning works, refer to the Data Cleaning section.

​
synchronousResponse
boolean
default:true

Indicates whether the response should be processed synchronously.

  • Set to true if you need an immediate response.
  • Set to false if you don't need to wait; you can later check the respondent's status using the Get Respondent Status endpoint.
Example:

true

​
respondentAttributes
object

Additional attributes for the respondent. Contains a list of key-value pairs that can be used to add additional metadata to the respondent, such as the panel source or the market of a respondent.

These values will be available in the ReDem App and in the result export. They can be used for further analysis of your data.

Example:
​
retentionDays
number

The number of days to retain the respondent's data.

Use this in case you have specific requirements for data retention. After the retention period is over the respondent will be deleted from ReDem. The data will be no longer available in our platform. The minimum value is 30 days.

Example:

30

Response

When a request is successfully processed, the API returns a 200 OK status code along with the expected data. The structure of the response depends on the synchronousResponse parameter provided in the request body, which determines whether the response is synchronous (results of the respondent evaluation are returned immediately) or asynchronous (a respondent is created and the results of the respondent evaluation are available later through a separate endpoint).

Synchronous Response

This response mode is triggered when synchronousResponse is set to true.

In this mode, the system generates a detailed response containing all quality parameters of the respondent. The request will wait (await) until the full response is ready before proceeding.

​
success
enum<boolean>

A variable indicating whether the operation was successful.

Available options:
true,
false
​
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.