object	object
Query	string	Case insensitive substring matched against the client name. Empty returns all clients, ordered by name. maxLength: 50
StartRow	integer\|string	Zero based index of the first row to return. pattern: `^-?(?:0\|[1-9]\d*)$`
EndRow	integer\|string	Exclusive index of the last row to return. At most 1000 rows may be requested at a time. pattern: `^-?(?:0\|[1-9]\d*)$`

POST /client/@search

curl --request POST \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/client/@search' \

--header 'Authorization: Bearer {token}' \

--data '{

"Query": "{string}",

"StartRow": "{integer,string}",

"EndRow": "{integer,string}"

Copy

Responses

200

Matching clients for the requested page.

array	array[object]
Id	uuid	Unique identifier of the client.
Name	string	Display name of the client.

400

The row window is negative, inverted, or wider than 1000 rows.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

Response

[

{

"Id": "{uuid}",

"Name": "{string}"

}

]

Copy

Get a client

Returns a single client by identifier.

Auth

Path Params

string

Identifier of the client.

GET /client/{id}

curl --get \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/client/{id}' \

--header 'Authorization: Bearer {token}'

Copy

Responses

200

The requested client.

object	object
Id	uuid	Unique identifier of the client.
Name	string	Display name of the client.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

404

No client exists with this identifier.

Response

{

"Id": "{uuid}",

"Name": "{string}"

}

Copy

Incentives

Operations related to incentives

Search incentives

Returns incentives across all projects, most recently initiated first. Every filter is optional and filters combine, so sending an empty body returns the entire history. Results are paged with StartRow and EndRow, and at most 1000 rows may be requested at a time.

Auth

Request Body

Filters and row window.

object	object
AfterDate	string?	Only return incentives initiated on or after this instant.
BeforeDate	string?	Only return incentives initiated on or before this instant.
ProjectId	string?	Only return incentives issued from this project.
PanelId	string?	Only return incentives issued to this panelist.
RespondentId	string?	Only return incentives issued to this respondent.
StartRow	integer\|string	Zero based index of the first row to return. pattern: `^-?(?:0\|[1-9]\d*)$`
EndRow	integer\|string	Exclusive index of the last row to return. At most 1000 rows may be requested at a time. pattern: `^-?(?:0\|[1-9]\d*)$`

POST /incentive/@search

curl --request POST \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/incentive/@search' \

--header 'Authorization: Bearer {token}' \

--data '{

"AfterDate": "{null,string}",

"BeforeDate": "{null,string}",

"ProjectId": "{null,string}",

"PanelId": "{null,string}",

"RespondentId": "{null,string}",

"StartRow": "{integer,string}",

"EndRow": "{integer,string}"

Copy

Responses

200

Matching incentives for the requested page.

array	array[object]
Id	uuid	Unique identifier of the incentive.
RespondentId	uuid	Respondent the incentive was issued to.
ProjectId	uuid	Project the incentive was issued from.
PanelId	string?	The ID of the respondent's panel record.
Description	string	Description recorded against the incentive.
InitiatedOn	date-time	When the incentive was requested.
InitiatedBy	string	Email address of the user that requested the incentive.
Amount	integer\|string	The incentive value in whole units (e.g., '10' for 10 dollars). pattern: `^-?(?:0\|[1-9]\d*)$`
Currency	string	ISO 4217 currency code of the incentive value.
Status	string	Where the incentive is in the ordering and delivery process. Enum: `requested`,`ordered`,`delivered`,`cancelled`,`failed`,`problem`,`unknown`
Name	string?	Name of the recipient.
Email	string?	Email address the incentive was delivered to.
Phone	string?	Phone number of the respondent.

400

'date_range' when BeforeDate is later than AfterDate, 'end_row' when the row window is inverted or wider than 1000 rows.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

Response

[

{

"Id": "{uuid}",

"RespondentId": "{uuid}",

"ProjectId": "{uuid}",

"PanelId": "{null,string}",

"Description": "{string}",

"InitiatedOn": "{date-time}",

"InitiatedBy": "{string}",

"Amount": "{integer,string}",

"Currency": "{string}",

"Status": "{string}",

"Name": "{null,string}",

"Email": "{null,string}",

"Phone": "{null,string}"

}

]

Copy

Get an incentive

Returns a single incentive by identifier.

Auth

Path Params

string

Identifier of the incentive.

GET /incentive/{id}

curl --get \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/incentive/{id}' \

--header 'Authorization: Bearer {token}'

Copy

Responses

200

The requested incentive.

object	object
Id	uuid	Unique identifier of the incentive.
RespondentId	uuid	Respondent the incentive was issued to.
ProjectId	uuid	Project the incentive was issued from.
PanelId	string?	The ID of the respondent's panel record.
Description	string	Description recorded against the incentive.
InitiatedOn	date-time	When the incentive was requested.
InitiatedBy	string	Email address of the user that requested the incentive.
Amount	integer\|string	The incentive value in whole units (e.g., '10' for 10 dollars). pattern: `^-?(?:0\|[1-9]\d*)$`
Currency	string	ISO 4217 currency code of the incentive value.
Status	string	Where the incentive is in the ordering and delivery process. Enum: `requested`,`ordered`,`delivered`,`cancelled`,`failed`,`problem`,`unknown`
Name	string?	Name of the recipient.
Email	string?	Email address the incentive was delivered to.
Phone	string?	Phone number of the respondent.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

404

No incentive exists with this identifier.

Response

{

"Id": "{uuid}",

"RespondentId": "{uuid}",

"ProjectId": "{uuid}",

"PanelId": "{null,string}",

"Description": "{string}",

"InitiatedOn": "{date-time}",

"InitiatedBy": "{string}",

"Amount": "{integer,string}",

"Currency": "{string}",

"Status": "{string}",

"Name": "{null,string}",

"Email": "{null,string}",

"Phone": "{null,string}"

}

Copy

Panel

Operations related to panelists

/panel/export/{requestId}

List panel exports

Returns the 100 most recent panel export requests, newest first.

Auth

GET /panel/export

curl --get \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/panel/export' \

--header 'Authorization: Bearer {token}'

Copy

Responses

200

The most recent export requests.

array	array[object]
Id	uuid	Unique identifier of the export request. Use it to poll the request for completion.
Status	string	Where the export is in the queue. Enum: `created`,`in_progress`,`complete`,`failed`
Created	date-time	When the export was requested.
Started	string?	When the export started processing. Null while the request is queued.
Completed	string?	When the export finished. Null until the request completes or fails.
Key	string?	Password for the exported ZIP archive. Set once the export completes.
Url	string?	Time limited download link for the exported archive. Only returned when reading a single completed request, and valid for 30 minutes from the time it was issued.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

Response

[

{

"Id": "{uuid}",

"Status": "{string}",

"Created": "{date-time}",

"Started": "{null,string}",

"Completed": "{null,string}",

"Key": "{null,string}",

"Url": "{null,string}"

}

]

Copy

Request a panel export

Queues an export of the panelists matching the filters. An identical request made within the last five minutes is returned as-is instead of queueing a second export.

Auth

Request Body

Filters selecting the panelists to export.

object	object
Filters	object?	Filters selecting the panelists to export, keyed by column. Keys are either a panel question identifier prefixed with 'Data.' or one of the built in fields (Id, Email, FirstName, LastName, PhoneNumber, Status, Tags, Types, Created, LastUpdated, DateOfBirth, Location.Country, Location.City, Location.Province, Location.PostalCode, Quality.AggregateRating, Quality.Banned). Omit to export the whole panel.
*9 fields	object	A filter applied to a single column. Filters that do not match one of the supported shapes are ignored rather than rejected.
FilterType	string	Kind of filter: 'text', 'number', 'date' or 'set'.
Filter	string?	Value to compare against for text and number filters.
FilterTo	string?	Upper bound for a number 'inRange' comparison.
Type	string?	Comparison to apply. Text filters support equals, notEqual, contains, notContains, startsWith, endsWith, blank and notBlank. Number and date filters support equals, notEqual, lessThan, greaterThan, lessThanOrEqual, greaterThanOrEqual, inRange, blank and notBlank.
DateFrom	string?	Date to compare against for date filters. Compared at whole day precision in UTC.
DateTo	string?	Upper bound for a date 'inRange' comparison. The filter is ignored if this is missing.
Values	array[string]	Values to match for set filters. An empty list matches rows where the column is empty or missing.
string	string
Conditions	array[object]	Nested filters applied to the same column. When present the comparison fields on this filter are ignored.
FilterableQuery	object
Operator	string?	How to combine Conditions: 'AND' requires all of them, any other value combines them with OR.

POST /panel/export

curl --request POST \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/panel/export' \

--header 'Authorization: Bearer {token}' \

--data '{

"Filters": {}

Copy

Responses

200

The queued - or matching recent - export request.

object	object
Id	uuid	Unique identifier of the export request. Use it to poll the request for completion.
Status	string	Where the export is in the queue. Enum: `created`,`in_progress`,`complete`,`failed`
Created	date-time	When the export was requested.
Started	string?	When the export started processing. Null while the request is queued.
Completed	string?	When the export finished. Null until the request completes or fails.
Key	string?	Password for the exported ZIP archive. Set once the export completes.
Url	string?	Time limited download link for the exported archive. Only returned when reading a single completed request, and valid for 30 minutes from the time it was issued.

400

A filter references a column that is not part of the panel.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

Response

{

"Id": "{uuid}",

"Status": "{string}",

"Created": "{date-time}",

"Started": "{null,string}",

"Completed": "{null,string}",

"Key": "{null,string}",

"Url": "{null,string}"

}

Copy

Get a panel export

Returns the state of a panel export request.

Auth

Path Params

requestId

string

Identifier of the export request.

GET /panel/export/{requestId}

curl --get \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/panel/export/{requestId}' \

--header 'Authorization: Bearer {token}'

Copy

Responses

200

The export request, with a download link when complete.

object	object
Id	uuid	Unique identifier of the export request. Use it to poll the request for completion.
Status	string	Where the export is in the queue. Enum: `created`,`in_progress`,`complete`,`failed`
Created	date-time	When the export was requested.
Started	string?	When the export started processing. Null while the request is queued.
Completed	string?	When the export finished. Null until the request completes or fails.
Key	string?	Password for the exported ZIP archive. Set once the export completes.
Url	string?	Time limited download link for the exported archive. Only returned when reading a single completed request, and valid for 30 minutes from the time it was issued.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

404

No export request exists with this identifier.

Response

{

"Id": "{uuid}",

"Status": "{string}",

"Created": "{date-time}",

"Started": "{null,string}",

"Completed": "{null,string}",

"Key": "{null,string}",

"Url": "{null,string}"

}

Copy

Get the panel schema

Returns the columns that describe the panel.

Auth

GET /panel/schema

curl --get \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/panel/schema' \

--header 'Authorization: Bearer {token}'

Copy

Responses

200

The current panel schema.

object	object
Version	integer\|string	Version of the panel schema definition. pattern: `^-?(?:0\|[1-9]\d*)$`
Columns6 fields	array[object]	A list of panel columns.
Identifier	string	Identifier of the column. Use this as the key in panelist Data dictionaries and, prefixed with 'Data.', as a filter key when searching or exporting the panel.
Disabled	boolean	True when the question is disabled.
ShortText	string	Abbreviated question label used in grids and exports.
Text	string	Full question text as shown to respondents.
Type	string	Value type the question holds. Enum: `text`,`boolean`,`number`,`mc`,`name`,`email`,`datetime`,`date`,`time`,`scale`,`phone`,`location`,`postal_code`,`script`,`video`,`file`,`call_recording`,`rating`,`rating_context`,`opt_in`,`country`,`language`,`smart`,`signature`,`dob`
MultipleChoice
null	null

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

Response

{

"Version": "{integer,string}",

"Columns": [

{

"Identifier": "{string}",

"Disabled": "{boolean}",

"ShortText": "{string}",

"Text": "{string}",

"Type": "{string}",

"MultipleChoice": "{null}"

}

]

}

Copy

Get a panelist

Returns a single panelist by identifier.

Auth

Path Params

string

Identifier of the panelist.

GET /panel/{id}

curl --get \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/panel/{id}' \

--header 'Authorization: Bearer {token}'

Copy

Responses

200

The requested panelist.

object	object
Id	uuid	Unique identifier of the panelist.
FirstName	string	Given name of the panelist.
LastName	string	Family name of the panelist.
Email	string	Email address of the panelist.
PhoneNumber	string	Phone number of the panelist in E.164 format.
Created	date-time	When the panelist was added to the panel.
DateOfBirth	date-time	Date of birth of the panelist.
LastUpdated	date-time	When the panelist record was last modified.
Comments	string	Internal notes recorded against the panelist.
Location4 fields	object	Where the panelist lives.
Country	string	Two letter ISO 3166-1 country code.
Province	string	State or province, where known.
City	string	City, where known.
PostalCode	string	Postal or ZIP code.
Data	object	Answers to the panel columns, keyed by column identifier. See the panel schema endpoint for the identifiers and value types available.
Status	string	Mailing status of the panelist. Enum: `unsubscribed`,`subscribed`,`disabled`
Tags	array[string]	Tags applied to the panelist.
Quality	object	Quality signals collected from the panelist's participation history.
AggregateRating	number\|string	Average of the ratings the panelist has received. Zero when never rated. pattern: `^-?(?:0\|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$`
Banned	boolean	True when the panelist is blocked from further recruitment.
Utm
null	null

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

404

No panelist exists with this identifier.

Response

{

"Id": "{uuid}",

"FirstName": "{string}",

"LastName": "{string}",

"Email": "{string}",

"PhoneNumber": "{string}",

"Created": "{date-time}",

"DateOfBirth": "{date-time}",

"LastUpdated": "{date-time}",

"Comments": "{string}",

"Location": {

"Country": "{string}",

"Province": "{string}",

"City": "{string}",

"PostalCode": "{string}"

"Data": {},

"Status": "{string}",

"Tags": [

"{array[string]...}"

"Quality": {

"AggregateRating": "{number,string}",

"Banned": "{boolean}"

"Utm": "{null}"

}

Copy

Delete a panelist

Permanently removes a panelist. Only panelists with no attachment to an existing project may be deleted.

Auth

Path Params

string

Identifier of the panelist.

DELETE /panel/{id}

curl --request DELETE \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/panel/{id}' \

--header 'Authorization: Bearer {token}'

Copy

Responses

204

The panelist was deleted.

No response body

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

403

The panelist has project history and cannot be deleted.

404

No panelist exists with this identifier.

Response

No response

Copy

Update a panelist

Replaces the details of a single panelist. The request carries the complete record, so fields left empty are written as empty.

Auth

Path Params

string

Identifier of the panelist.

Request Body

Replacement details for the panelist. The Id field is ignored when updating a single record.

object	object
Id	string?	Panelist to update. Required by the bulk update endpoint and ignored everywhere else.
DateOfBirth	date-time	Date of birth of the panelist. Must be on or after 1 January 1900 and not in the future.
Status	string	Mailing status of the panelist. Enum: `unsubscribed`,`subscribed`,`disabled`
Data	object	Answers to the panel questions, keyed by question identifier. Identifiers must exist in the panel schema and values must match the question type: an array of strings for multiple choice, a number for numeric questions, a date for date, datetime and time questions, and a string otherwise. The name, last name, phone and email questions are written from the matching top level fields and do not need to be sent here.
Location	object	Where the panelist lives.
Country	string	Two letter ISO 3166-1 country code. Must be a country that has been enabled for the tenant. maxLength: 2 minLength: 2
PostalCode	string	Postal or ZIP code of the panelist. maxLength: 25
Comments	string	Internal notes to record against the panelist. maxLength: 1024
Tags	array[string]	Tags to apply. Each tag must already exist on the panel.
FirstName	string	Given name of the panelist. maxLength: 50
LastName	string	Family name of the panelist. maxLength: 50
Email	string	Email address of the panelist.
PhoneNumber	string	Phone number of the panelist, in any format parseable for the location country. Stored in E.164 format.

PUT /panel/{id}

curl --request PUT \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/panel/{id}' \

--header 'Authorization: Bearer {token}' \

--data '{

"Id": "{null,string}",

"DateOfBirth": "{date-time}",

"Status": "{string}",

"Data": {},

"Location": {

"Country": "{string}",

"PostalCode": "{string}"

"Comments": "{string}",

"Tags": [

"{array[string]...}"

"FirstName": "{string}",

"LastName": "{string}",

"Email": "{string}",

"PhoneNumber": "{string}"

Copy

Responses

200

The panelist as stored after the update.

object	object
Id	uuid	Unique identifier of the panelist.
FirstName	string	Given name of the panelist.
LastName	string	Family name of the panelist.
Email	string	Email address of the panelist.
PhoneNumber	string	Phone number of the panelist in E.164 format.
Created	date-time	When the panelist was added to the panel.
DateOfBirth	date-time	Date of birth of the panelist.
LastUpdated	date-time	When the panelist record was last modified.
Comments	string	Internal notes recorded against the panelist.
Location4 fields	object	Where the panelist lives.
Country	string	Two letter ISO 3166-1 country code.
Province	string	State or province, where known.
City	string	City, where known.
PostalCode	string	Postal or ZIP code.
Data	object	Answers to the panel columns, keyed by column identifier. See the panel schema endpoint for the identifiers and value types available.
Status	string	Mailing status of the panelist. Enum: `unsubscribed`,`subscribed`,`disabled`
Tags	array[string]	Tags applied to the panelist.
Quality	object	Quality signals collected from the panelist's participation history.
AggregateRating	number\|string	Average of the ratings the panelist has received. Zero when never rated. pattern: `^-?(?:0\|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$`
Banned	boolean	True when the panelist is blocked from further recruitment.
Utm
null	null

400

'update_failed' when the write did not apply, otherwise the field that failed validation: 'tags' when a tag does not exist on the panel, 'country' when the location country is missing or has not been enabled for your tenant, 'need_email_or_phone' when both contact fields are empty, 'invalid_phone' when the number cannot be parsed for that country, 'invalid_dob' when the date of birth is before 1900 or in the future, 'invalid_data' when a question identifier is unknown, 'invalid_data_format' when an answer does not match its question type.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

404

No panelist exists with this identifier.

Response

{

"Id": "{uuid}",

"FirstName": "{string}",

"LastName": "{string}",

"Email": "{string}",

"PhoneNumber": "{string}",

"Created": "{date-time}",

"DateOfBirth": "{date-time}",

"LastUpdated": "{date-time}",

"Comments": "{string}",

"Location": {

"Country": "{string}",

"Province": "{string}",

"City": "{string}",

"PostalCode": "{string}"

"Data": {},

"Status": "{string}",

"Tags": [

"{array[string]...}"

"Quality": {

"AggregateRating": "{number,string}",

"Banned": "{boolean}"

"Utm": "{null}"

}

Copy

Search panelists

Returns the panelists matching the filters. Filters are combined with AND and may target both built-in fields and panel questions. Results are paged with StartRow and EndRow, and at most 1000 rows may be requested at a time.

Auth

Request Body

Filters and row window.

object	object
Filters	object?	Filters to apply, keyed by column. Keys are either a panel question identifier prefixed with 'Data.' or one of the built in fields (Id, Email, FirstName, LastName, PhoneNumber, Status, Tags, Types, Created, LastUpdated, DateOfBirth, Location.Country, Location.City, Location.Province, Location.PostalCode, Quality.AggregateRating, Quality.Banned). Omit to search the whole panel.
*9 fields	object	A filter applied to a single column. Filters that do not match one of the supported shapes are ignored rather than rejected.
FilterType	string	Kind of filter: 'text', 'number', 'date' or 'set'.
Filter	string?	Value to compare against for text and number filters.
FilterTo	string?	Upper bound for a number 'inRange' comparison.
Type	string?	Comparison to apply. Text filters support equals, notEqual, contains, notContains, startsWith, endsWith, blank and notBlank. Number and date filters support equals, notEqual, lessThan, greaterThan, lessThanOrEqual, greaterThanOrEqual, inRange, blank and notBlank.
DateFrom	string?	Date to compare against for date filters. Compared at whole day precision in UTC.
DateTo	string?	Upper bound for a date 'inRange' comparison. The filter is ignored if this is missing.
Values	array[string]	Values to match for set filters. An empty list matches rows where the column is empty or missing.
string	string
Conditions	array[object]	Nested filters applied to the same column. When present the comparison fields on this filter are ignored.
FilterableQuery	object
Operator	string?	How to combine Conditions: 'AND' requires all of them, any other value combines them with OR.
StartRow	integer\|string	Zero based index of the first row to return. pattern: `^-?(?:0\|[1-9]\d*)$`
EndRow	integer\|string	Exclusive index of the last row to return. At most 1000 rows may be requested at a time. pattern: `^-?(?:0\|[1-9]\d*)$`

POST /panel/@search

curl --request POST \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/panel/@search' \

--header 'Authorization: Bearer {token}' \

--data '{

"Filters": {},

"StartRow": "{integer,string}",

"EndRow": "{integer,string}"

Copy

Responses

200

Matching panelists for the requested page.

array	array[object]
Id	uuid	Unique identifier of the panelist.
FirstName	string	Given name of the panelist.
LastName	string	Family name of the panelist.
Email	string	Email address of the panelist.
PhoneNumber	string	Phone number of the panelist in E.164 format.
Created	date-time	When the panelist was added to the panel.
DateOfBirth	date-time	Date of birth of the panelist.
LastUpdated	date-time	When the panelist record was last modified.
Comments	string	Internal notes recorded against the panelist.
Location4 fields	object	Where the panelist lives.
Country	string	Two letter ISO 3166-1 country code.
Province	string	State or province, where known.
City	string	City, where known.
PostalCode	string	Postal or ZIP code.
Data	object	Answers to the panel columns, keyed by column identifier. See the panel schema endpoint for the identifiers and value types available.
Status	string	Mailing status of the panelist. Enum: `unsubscribed`,`subscribed`,`disabled`
Tags	array[string]	Tags applied to the panelist.
Quality	object	Quality signals collected from the panelist's participation history.
AggregateRating	number\|string	Average of the ratings the panelist has received. Zero when never rated. pattern: `^-?(?:0\|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$`
Banned	boolean	True when the panelist is blocked from further recruitment.
Utm
null	null

400

The row window is negative, inverted or wider than 1000 rows, or a filter references a column that is not part of the panel.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

Response

[

{

"Id": "{uuid}",

"FirstName": "{string}",

"LastName": "{string}",

"Email": "{string}",

"PhoneNumber": "{string}",

"Created": "{date-time}",

"DateOfBirth": "{date-time}",

"LastUpdated": "{date-time}",

"Comments": "{string}",

"Location": {

"Country": "{string}",

"Province": "{string}",

"City": "{string}",

"PostalCode": "{string}"

"Data": {},

"Status": "{string}",

"Tags": [

"{array[string]...}"

"Quality": {

"AggregateRating": "{number,string}",

"Banned": "{boolean}"

"Utm": "{null}"

}

]

Copy

Create a panelist

Adds a single panelist to the panel. The email address must not already be in use.

Auth

Request Body

Panelist to create.

object	object	Panelist to create. Identical to an update request except that Id is ignored.
Id	string?	Panelist to update. Required by the bulk update endpoint and ignored everywhere else.
DateOfBirth	date-time	Date of birth of the panelist. Must be on or after 1 January 1900 and not in the future.
Status	string	Mailing status of the panelist. Enum: `unsubscribed`,`subscribed`,`disabled`
Data	object	Answers to the panel questions, keyed by question identifier. Identifiers must exist in the panel schema and values must match the question type: an array of strings for multiple choice, a number for numeric questions, a date for date, datetime and time questions, and a string otherwise. The name, last name, phone and email questions are written from the matching top level fields and do not need to be sent here.
Location	object	Where the panelist lives.
Country	string	Two letter ISO 3166-1 country code. Must be a country that has been enabled for the tenant. maxLength: 2 minLength: 2
PostalCode	string	Postal or ZIP code of the panelist. maxLength: 25
Comments	string	Internal notes to record against the panelist. maxLength: 1024
Tags	array[string]	Tags to apply. Each tag must already exist on the panel.
FirstName	string	Given name of the panelist. maxLength: 50
LastName	string	Family name of the panelist. maxLength: 50
Email	string	Email address of the panelist.
PhoneNumber	string	Phone number of the panelist, in any format parseable for the location country. Stored in E.164 format.

POST /panel

curl --request POST \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/panel' \

--header 'Authorization: Bearer {token}' \

--data '{

"Id": "{null,string}",

"DateOfBirth": "{date-time}",

"Status": "{string}",

"Data": {},

"Location": {

"Country": "{string}",

"PostalCode": "{string}"

"Comments": "{string}",

"Tags": [

"{array[string]...}"

"FirstName": "{string}",

"LastName": "{string}",

"Email": "{string}",

"PhoneNumber": "{string}"

Copy

Responses

200

The created panelist.

object	object
Id	uuid	Unique identifier of the panelist.
FirstName	string	Given name of the panelist.
LastName	string	Family name of the panelist.
Email	string	Email address of the panelist.
PhoneNumber	string	Phone number of the panelist in E.164 format.
Created	date-time	When the panelist was added to the panel.
DateOfBirth	date-time	Date of birth of the panelist.
LastUpdated	date-time	When the panelist record was last modified.
Comments	string	Internal notes recorded against the panelist.
Location4 fields	object	Where the panelist lives.
Country	string	Two letter ISO 3166-1 country code.
Province	string	State or province, where known.
City	string	City, where known.
PostalCode	string	Postal or ZIP code.
Data	object	Answers to the panel columns, keyed by column identifier. See the panel schema endpoint for the identifiers and value types available.
Status	string	Mailing status of the panelist. Enum: `unsubscribed`,`subscribed`,`disabled`
Tags	array[string]	Tags applied to the panelist.
Quality	object	Quality signals collected from the panelist's participation history.
AggregateRating	number\|string	Average of the ratings the panelist has received. Zero when never rated. pattern: `^-?(?:0\|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$`
Banned	boolean	True when the panelist is blocked from further recruitment.
Utm
null	null

400

The field that failed validation: 'tags' when a tag does not exist on the panel, 'country' when the location country is missing or has not been enabled for your tenant, 'need_email_or_phone' when both contact fields are empty, 'invalid_phone' when the number cannot be parsed for that country, 'invalid_dob' when the date of birth is before 1900 or in the future, 'invalid_data' when a question identifier is unknown, 'invalid_data_format' when an answer does not match its question type.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

409

Another panelist already uses this email address.

Response

{

"Id": "{uuid}",

"FirstName": "{string}",

"LastName": "{string}",

"Email": "{string}",

"PhoneNumber": "{string}",

"Created": "{date-time}",

"DateOfBirth": "{date-time}",

"LastUpdated": "{date-time}",

"Comments": "{string}",

"Location": {

"Country": "{string}",

"Province": "{string}",

"City": "{string}",

"PostalCode": "{string}"

"Data": {},

"Status": "{string}",

"Tags": [

"{array[string]...}"

"Quality": {

"AggregateRating": "{number,string}",

"Banned": "{boolean}"

"Utm": "{null}"

}

Copy

Import panelists in bulk

Adds up to 5000 panelists in a single transaction. Every panelist needs an email address, the addresses must be unique within the request, and none of them may already exist on the panel. Nothing is written unless the whole batch validates.

Auth

Request Body

Panelists to create. Maximum 5000 per call.

array	array[object]
Id	string?	Panelist to update. Required by the bulk update endpoint and ignored everywhere else.
DateOfBirth	date-time	Date of birth of the panelist. Must be on or after 1 January 1900 and not in the future.
Status	string	Mailing status of the panelist. Enum: `unsubscribed`,`subscribed`,`disabled`
Data	object	Answers to the panel questions, keyed by question identifier. Identifiers must exist in the panel schema and values must match the question type: an array of strings for multiple choice, a number for numeric questions, a date for date, datetime and time questions, and a string otherwise. The name, last name, phone and email questions are written from the matching top level fields and do not need to be sent here.
Location	object	Where the panelist lives.
Country	string	Two letter ISO 3166-1 country code. Must be a country that has been enabled for the tenant. maxLength: 2 minLength: 2
PostalCode	string	Postal or ZIP code of the panelist. maxLength: 25
Comments	string	Internal notes to record against the panelist. maxLength: 1024
Tags	array[string]	Tags to apply. Each tag must already exist on the panel.
FirstName	string	Given name of the panelist. maxLength: 50
LastName	string	Family name of the panelist. maxLength: 50
Email	string	Email address of the panelist.
PhoneNumber	string	Phone number of the panelist, in any format parseable for the location country. Stored in E.164 format.

POST /panel/@import

curl --request POST \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/panel/@import' \

--header 'Authorization: Bearer {token}' \

--data '[

{

"Id": "{null,string}",

"DateOfBirth": "{date-time}",

"Status": "{string}",

"Data": {},

"Location": {

"Country": "{string}",

"PostalCode": "{string}"

"Comments": "{string}",

"Tags": [

"{array[string]...}"

"FirstName": "{string}",

"LastName": "{string}",

"Email": "{string}",

"PhoneNumber": "{string}"

}

Copy

Responses

204

Every panelist in the batch was created.

No response body

400

'too_many_imports' for more than 5000 panelists, 'emails_required' when an email address is missing, 'duplicate_emails' when the batch repeats an address, 'import_failed' when an address is already on the panel or the write failed. Otherwise the first field that failed validation: 'tags' when a tag does not exist on the panel, 'country' when the location country is missing or has not been enabled for your tenant, 'need_email_or_phone' when both contact fields are empty, 'invalid_phone' when the number cannot be parsed for that country, 'invalid_dob' when the date of birth is before 1900 or in the future, 'invalid_data' when a question identifier is unknown, 'invalid_data_format' when an answer does not match its question type.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

Response

No response

Copy

Update panelists in bulk

Applies up to 5000 panelist updates in one call. Each entry must carry the Id of the panelist to update and a complete record - fields left empty are written as empty. Panelists that could not be updated are reported in the response rather than failing the call.

Auth

Request Body

Panelist updates. Maximum 5000 per call.

array	array[object]
Id	string?	Panelist to update. Required by the bulk update endpoint and ignored everywhere else.
DateOfBirth	date-time	Date of birth of the panelist. Must be on or after 1 January 1900 and not in the future.
Status	string	Mailing status of the panelist. Enum: `unsubscribed`,`subscribed`,`disabled`
Data	object	Answers to the panel questions, keyed by question identifier. Identifiers must exist in the panel schema and values must match the question type: an array of strings for multiple choice, a number for numeric questions, a date for date, datetime and time questions, and a string otherwise. The name, last name, phone and email questions are written from the matching top level fields and do not need to be sent here.
Location	object	Where the panelist lives.
Country	string	Two letter ISO 3166-1 country code. Must be a country that has been enabled for the tenant. maxLength: 2 minLength: 2
PostalCode	string	Postal or ZIP code of the panelist. maxLength: 25
Comments	string	Internal notes to record against the panelist. maxLength: 1024
Tags	array[string]	Tags to apply. Each tag must already exist on the panel.
FirstName	string	Given name of the panelist. maxLength: 50
LastName	string	Family name of the panelist. maxLength: 50
Email	string	Email address of the panelist.
PhoneNumber	string	Phone number of the panelist, in any format parseable for the location country. Stored in E.164 format.

POST /panel/@bulkUpdate

curl --request POST \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/panel/@bulkUpdate' \

--header 'Authorization: Bearer {token}' \

--data '[

{

"Id": "{null,string}",

"DateOfBirth": "{date-time}",

"Status": "{string}",

"Data": {},

"Location": {

"Country": "{string}",

"PostalCode": "{string}"

"Comments": "{string}",

"Tags": [

"{array[string]...}"

"FirstName": "{string}",

"LastName": "{string}",

"Email": "{string}",

"PhoneNumber": "{string}"

}

Copy

Responses

200

How many updates were applied, and the identifiers that failed.

object	object
FailedIds	array[string]	A list of panelists GUIDs that could not be updated.
SuccessCount	integer\|string	Number of panelists that were updated. pattern: `^-?(?:0\|[1-9]\d*)$`
RequestCount	integer\|string	Number of updates that were submitted. pattern: `^-?(?:0\|[1-9]\d*)$`

400

An empty list, 'too_many_updates' for more than 5000 entries, 'id_field_required' when an entry has no Id, 'duplicate_ids' when an Id is repeated, or 'bad_data: ' followed by the fields that failed validation: 'tags' when a tag does not exist on the panel, 'country' when the location country is missing or has no messaging numbers, 'need_email_or_phone' when both contact fields are empty, 'invalid_phone' when the number cannot be parsed for that country, 'invalid_dob' when the date of birth is before 1900 or in the future, 'invalid_data' when a question identifier is unknown, 'invalid_data_format' when an answer does not match its question type.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

Response

{

"FailedIds": [

"{array[string]...}"

"SuccessCount": "{integer,string}",

"RequestCount": "{integer,string}"

}

Copy

Projects

Operations related to projects

/project/{projectId}/schema

GET

/project/{projectId}/respondents

GET

/project/{projectId}/feed

GET

/project/{projectId}/validation

GET

/project/{projectId}/respondents/{respondentId}

POST

/project/{projectId}/respondents/@move

POST

/project/@search

Create a project

Creates an open project owned by the given user. Supplying DuplicateProjectId copies the schema and settings of an existing project. Requires the Write Access API to be enabled for your tenant.

Auth

Request Body

Details of the project to create.

object	object
PublicName	string	Name shown to respondents in invitations and surveys.
InternalName	string	Name shown to platform users.
DefaultTimeZone	string	Time zone sessions in the project default to in TZ Database format (e.g., 'US/Eastern'). Must be one of the time zones configured for the tenant.
DefaultLocale	string	Language and country respondents are contacted in, formatted as 'language-country' (for example 'EN-US'). Locale must be an enabled locale for the tenant.
InitialOwner	string	Email address of an existing user who will be set as the owner of the project.
Properties	object?	Custom property values to set, keyed by property identifier. Values must match the type of the property as returned by the project properties endpoint; dates may be sent as ISO 8601 strings. Unknown identifiers are rejected.
Tags	array[string]	Tags to apply. Each tag must already exist on the tenant.
string	string
DisableSms	boolean	Set to true to block all SMS messaging for the project. Cannot be changed once set.
Type	string	Project methodology: 'qual' for qualitative, 'quant' for quantitative. Quantitative projects are only accepted when the tenant has the quantitative feature enabled. Enum: `qual`,`quant`
DuplicateProjectId	string?	Existing project to copy the schema, surveys, and templates from.
ClientId	string?	Client to associate the project with.

POST /project

curl --request POST \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/project' \

--header 'Authorization: Bearer {token}' \

--data '{

"PublicName": "{string}",

"InternalName": "{string}",

"DefaultTimeZone": "{string}",

"DefaultLocale": "{string}",

"InitialOwner": "{string}",

"Properties": {},

"Tags": [

"{array[string]...}"

"DisableSms": "{boolean}",

"Type": "{string}",

"DuplicateProjectId": "{null,string}",

"ClientId": "{null,string}"

Copy

Responses

200

The created project.

object	object
Id	uuid	Unique identifier of the project.
Name	string	The internal name of the project as displayed to platform users.
ClientId	string?	Client the project belongs to, if one is set.
ClientName	string?	Name of the client the project belongs to, if one is set.
Created	date-time	When the project was created.
LastUpdated	string?	When the project was last modified.
Tags	array[string]	Tags applied to the project.
Counts3 fields	object	Recruitment progress across all groups in the project.
Required	integer\|string	Number of respondents the project needs across all groups. pattern: `^-?(?:0\|[1-9]\d*)$`
Count	integer\|string	Number of respondents currently recruited. pattern: `^-?(?:0\|[1-9]\d*)$`
Held	integer\|string	Number of recruited respondents that are flagged as being on hold. pattern: `^-?(?:0\|[1-9]\d*)$`
Properties	object	Custom project properties, keyed by property identifier. See the project properties endpoint for the identifiers and value types configured for this tenant.
State	string	Lifecycle state of the project. Enum: `open`,`pending_close`,`closed`

400

'invalid_property_or_format' for an unknown property identifier or a value of the wrong type, 'invalid_tag' for a tag that does not exist, 'quant_disabled' when a quantitative project is requested without the feature, 'invalid_locale' or 'invalid_time_zone' when those are not configured for the tenant, 'invalid_owner' when the initial owner is not a user, 'duplicate_project_not_found' when the project to duplicate does not exist.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

403

The write API is disabled for this tenant.

Response

{

"Id": "{uuid}",

"Name": "{string}",

"ClientId": "{null,string}",

"ClientName": "{null,string}",

"Created": "{date-time}",

"LastUpdated": "{null,string}",

"Tags": [

"{array[string]...}"

"Counts": {

"Required": "{integer,string}",

"Count": "{integer,string}",

"Held": "{integer,string}"

"Properties": {},

"State": "{string}"

}

Copy

Get a project

Returns a single project by identifier, including its tags, custom properties and recruitment counts.

Auth

Path Params

string

Identifier of the project.

GET /project/{id}

curl --get \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/project/{id}' \

--header 'Authorization: Bearer {token}'

Copy

Responses

200

The requested project.

object	object
Id	uuid	Unique identifier of the project.
Name	string	The internal name of the project as displayed to platform users.
ClientId	string?	Client the project belongs to, if one is set.
ClientName	string?	Name of the client the project belongs to, if one is set.
Created	date-time	When the project was created.
LastUpdated	string?	When the project was last modified.
Tags	array[string]	Tags applied to the project.
Counts3 fields	object	Recruitment progress across all groups in the project.
Required	integer\|string	Number of respondents the project needs across all groups. pattern: `^-?(?:0\|[1-9]\d*)$`
Count	integer\|string	Number of respondents currently recruited. pattern: `^-?(?:0\|[1-9]\d*)$`
Held	integer\|string	Number of recruited respondents that are flagged as being on hold. pattern: `^-?(?:0\|[1-9]\d*)$`
Properties	object	Custom project properties, keyed by property identifier. See the project properties endpoint for the identifiers and value types configured for this tenant.
State	string	Lifecycle state of the project. Enum: `open`,`pending_close`,`closed`

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

404

No project exists with this identifier.

Response

{

"Id": "{uuid}",

"Name": "{string}",

"ClientId": "{null,string}",

"ClientName": "{null,string}",

"Created": "{date-time}",

"LastUpdated": "{null,string}",

"Tags": [

"{array[string]...}"

"Counts": {

"Required": "{integer,string}",

"Count": "{integer,string}",

"Held": "{integer,string}"

"Properties": {},

"State": "{string}"

}

Copy

List custom project properties

Returns the custom project properties configured for the tenant. Their identifiers are the keys of the Properties dictionary when creating, reading or searching projects.

Auth

GET /project/@properties

curl --get \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/project/@properties' \

--header 'Authorization: Bearer {token}'

Copy

Responses

200

The properties configured for this tenant, ordered by name.

array	array[object]
Id	string	Identifier of the property. Use this as the key when defining project properties.
Name	string	Display name of the property.
Type	string	Value type accepted for this property. Enum: `user`,`text`,`number`,`date`,`unknown`

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

Response

[

{

"Id": "{string}",

"Name": "{string}",

"Type": "{string}"

}

]

Copy

Get a project schema

Returns the tabs and columns that make up the project grid.

Auth

Path Params

projectId

string

Identifier of the project.

GET /project/{projectId}/schema

curl --get \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/project/{projectId}/schema' \

--header 'Authorization: Bearer {token}'

Copy

Responses

200

The current schema for the project.

object	object
Id	uuid	Unique identifier of the project.
Groups8 fields	array[object]	Groups (tabs) defined for the project.
Name	string	Identifier of the group (tab). Use this when reading or moving respondents by group.
Label	string	Display label of the group.
Incentive	string	Incentive description for the tab.
FieldDate	object	Scheduled start and end of the group's fieldwork. Either date may be null when unscheduled.
StartDate	string?	When sessions begin for the tab. Null when it has not been defined.
EndDate	string?	When sessions end for the tab. Null when it has not been scheduled.
RespondentsRequired	integer\|string	Number of respondents that need to be recruited into the tab. pattern: `^-?(?:0\|[1-9]\d*)$`
Private	boolean	True when the tab is not visible to clients.
TimeZone	string	IANA time zone the group's sessions are scheduled in.
Variables	object	Template variables available to messages sent to this group, keyed by variable name.
*	string
Columns7 fields	array[object]	Columns defined on the project.
Identifier	string	Identifier of the column. Use this as the key in respondent Data dictionaries.
Groups	array[string]	Groups (tabs) this column is visible in. When an empty array, the column is visible to all groups.
Text	string	Full question text as normally shown to respondents.
ShortText	string	Abbreviated column label used in grids and exports.
Private	boolean	True if the column is not visible to clients.
Type	string	Value type the question holds. Enum: `text`,`boolean`,`number`,`mc`,`name`,`email`,`datetime`,`date`,`time`,`scale`,`phone`,`location`,`postal_code`,`script`,`video`,`file`,`call_recording`,`rating`,`rating_context`,`opt_in`,`country`,`language`,`smart`,`signature`,`dob`
MultipleChoice
null	null
Version	integer\|string	Version of the schema definition. pattern: `^-?(?:0\|[1-9]\d*)$`

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

404

No project exists with this identifier.

Response

{

"Id": "{uuid}",

"Groups": [

{

"Name": "{string}",

"Label": "{string}",

"Incentive": "{string}",

"FieldDate": {

"StartDate": "{null,string}",

"EndDate": "{null,string}"

"RespondentsRequired": "{integer,string}",

"Private": "{boolean}",

"TimeZone": "{string}",

"Variables": {}

}

"Columns": [

{

"Identifier": "{string}",

"Groups": [

"{array[string]...}"

"Text": "{string}",

"ShortText": "{string}",

"Private": "{boolean}",

"Type": "{string}",

"MultipleChoice": "{null}"

}

"Version": "{integer,string}"

}

Copy

List respondents in a project

Returns the respondents recruited into a project, oldest first, with their answers to the project questions.

Auth

Path Params

projectId

string

Identifier of the project.

Query String

all

boolean

Set to true to also return staged respondents that are not published.

Default: false

group

string

Only return respondents in this group (tab). Omit to return every group.

GET /project/{projectId}/respondents

curl --get \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/project/{projectId}/respondents' \

--header 'Authorization: Bearer {token}' \

--data all={all} \

--data group={group}

Copy

Responses

200

The respondents matching the request.

array	array[object]
Id	uuid	Unique identifier of the respondent.
Group	string	Group (grid tab) the respondent belongs to.
Name	string	Name of the respondent.
Email	string	Email address of the respondent.
PhoneNumber	string	Phone number of the respondent in E.164 format.
Country	string	Two letter ISO 3166-1 country code of the respondent.
Language	string	Language of the respondent.
PanelId	string?	The unique identifier of the respondent's panel record.
LastUpdated	date-time	When the respondent record was last modified.
Created	date-time	When the respondent was added to the project.
Data	object	Answers given by the respondent, keyed by question identifier. Multiple choice answers are returned as an array of the selected options and numeric answers as numbers; see the project schema endpoint for the type of each question.
Status6 fields	object	Recruitment state of the respondent.
Disqualified	boolean	True when the respondent has been marked as disqualified.
Held	boolean	True when the respondent has been marked as a hold.
Overridden	boolean	True if the respondent is ignoring qualification errors.
Presence	string	Attendance recorded for the respondent - one of 'unset', 'absent' or 'present'.
Staged	boolean	True when the respondent is staged and not published.
Planned	boolean	True when the respondent has been planned but not yet published.

400

'invalid_group' when the group is not part of the project schema.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

404

No project exists with this identifier, or it has no schema.

Response

[

{

"Id": "{uuid}",

"Group": "{string}",

"Name": "{string}",

"Email": "{string}",

"PhoneNumber": "{string}",

"Country": "{string}",

"Language": "{string}",

"PanelId": "{null,string}",

"LastUpdated": "{date-time}",

"Created": "{date-time}",

"Data": {},

"Status": {

"Disqualified": "{boolean}",

"Held": "{boolean}",

"Overridden": "{boolean}",

"Presence": "{string}",

"Staged": "{boolean}",

"Planned": "{boolean}"

}

]

Copy

List the survey feed for a group

Returns survey sessions targeting a group that have not yet been attached to a respondent. Identifiers are survey session identifiers rather than respondent identifiers, contact fields are empty and every entry is marked as staged.

Auth

Path Params

projectId

string

Identifier of the project.

Query String

group

string

Group (tab) targeted by the survey links.

GET /project/{projectId}/feed

curl --get \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/project/{projectId}/feed' \

--header 'Authorization: Bearer {token}' \

--data group={group}

Copy

Responses

200

The feed entries for the group.

array	array[object]
Id	uuid	Unique identifier of the respondent.
Group	string	Group (grid tab) the respondent belongs to.
Name	string	Name of the respondent.
Email	string	Email address of the respondent.
PhoneNumber	string	Phone number of the respondent in E.164 format.
Country	string	Two letter ISO 3166-1 country code of the respondent.
Language	string	Language of the respondent.
PanelId	string?	The unique identifier of the respondent's panel record.
LastUpdated	date-time	When the respondent record was last modified.
Created	date-time	When the respondent was added to the project.
Data	object	Answers given by the respondent, keyed by question identifier. Multiple choice answers are returned as an array of the selected options and numeric answers as numbers; see the project schema endpoint for the type of each question.
Status6 fields	object	Recruitment state of the respondent.
Disqualified	boolean	True when the respondent has been marked as disqualified.
Held	boolean	True when the respondent has been marked as a hold.
Overridden	boolean	True if the respondent is ignoring qualification errors.
Presence	string	Attendance recorded for the respondent - one of 'unset', 'absent' or 'present'.
Staged	boolean	True when the respondent is staged and not published.
Planned	boolean	True when the respondent has been planned but not yet published.

400

'invalid_group' when the group is not part of the project schema.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

404

No project exists with this identifier, or it has no schema.

Response

[

{

"Id": "{uuid}",

"Group": "{string}",

"Name": "{string}",

"Email": "{string}",

"PhoneNumber": "{string}",

"Country": "{string}",

"Language": "{string}",

"PanelId": "{null,string}",

"LastUpdated": "{date-time}",

"Created": "{date-time}",

"Data": {},

"Status": {

"Disqualified": "{boolean}",

"Held": "{boolean}",

"Overridden": "{boolean}",

"Presence": "{string}",

"Staged": "{boolean}",

"Planned": "{boolean}"

}

]

Copy

Get validation results for a group

Validates a group (tab) against the project schema and returns qualification and quota errors and quota counts.

Auth

Path Params

projectId

string

Identifier of the project.

Query String

group

string

Group (tab) to validate.

all

boolean

Set to true to also retrieve validation information for staged respondents that are not published.

Default: false

GET /project/{projectId}/validation

curl --get \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/project/{projectId}/validation' \

--header 'Authorization: Bearer {token}' \

--data group={group} \

--data all={all}

Copy

Responses

200

The validation results for the group.

object	object
Respondents2 fields	array[object]	Respondents evaluated by the validator, with any qualification errors found for each.
Id	uuid	Unique identifier of the respondent.
Errors3 fields	array[object]	Qualification errors for the respondent.
Column	string	Identifier of the question the error applies to.
Type	string	Severity of the error. Enum: `error`,`warning`,`notice`,`staged_error`,`staged_warning`,`staged_notice`,`planned_error`,`planned_warning`,`planned_notice`,`required`,`unknown`
Message	string	Description of the error.
QuotaErrors3 fields	array[object]	Quotas in the group that are broken or close to being broken.
Column	string	Identifier of the question the error applies to.
Type	string	Severity of the error. Enum: `error`,`warning`,`notice`,`staged_error`,`staged_warning`,`staged_notice`,`planned_error`,`planned_warning`,`planned_notice`,`required`,`unknown`
Message	string	Description of the error.
QuotaCounts6 fields	array[object]	Current count of respondents in each quota of the group.
Id	integer\|string	Identifier of the quota item. pattern: `^-?(?:0\|[1-9]\d*)$`
Column	string	Identifier of the question the quota belongs to.
Description	string	Description of the quota, or its custom error message.
Target	integer\|string	The quota requirement. pattern: `^-?(?:0\|[1-9]\d*)$`
Type	string	The type of quota being applied Enum: `min`,`max`
Count	integer\|string	Number of respondents currently counted towards the quota. pattern: `^-?(?:0\|[1-9]\d*)$`

400

'invalid_group' when the group is not part of the project schema.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

404

No project exists with this identifier, or it has no schema.

Response

{

"Respondents": [

{

"Id": "{uuid}",

"Errors": [

{

"Column": "{string}",

"Type": "{string}",

"Message": "{string}"

}

]

}

"QuotaErrors": [

{

"Column": "{string}",

"Type": "{string}",

"Message": "{string}"

}

"QuotaCounts": [

{

"Id": "{integer,string}",

"Column": "{string}",

"Description": "{string}",

"Target": "{integer,string}",

"Type": "{string}",

"Count": "{integer,string}"

}

]

}

Copy

Get a respondent

Returns a single respondent record in a project.

Auth

Path Params

projectId	string	Identifier of the project.
respondentId	string	Identifier of the respondent.

GET /project/{projectId}/respondents/{respondentId}

curl --get \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/project/{projectId}/respondents/{respondentId}' \

--header 'Authorization: Bearer {token}'

Copy

Responses

200

The requested respondent.

object	object
Id	uuid	Unique identifier of the respondent.
Group	string	Group (grid tab) the respondent belongs to.
Name	string	Name of the respondent.
Email	string	Email address of the respondent.
PhoneNumber	string	Phone number of the respondent in E.164 format.
Country	string	Two letter ISO 3166-1 country code of the respondent.
Language	string	Language of the respondent.
PanelId	string?	The unique identifier of the respondent's panel record.
LastUpdated	date-time	When the respondent record was last modified.
Created	date-time	When the respondent was added to the project.
Data	object	Answers given by the respondent, keyed by question identifier. Multiple choice answers are returned as an array of the selected options and numeric answers as numbers; see the project schema endpoint for the type of each question.
Status6 fields	object	Recruitment state of the respondent.
Disqualified	boolean	True when the respondent has been marked as disqualified.
Held	boolean	True when the respondent has been marked as a hold.
Overridden	boolean	True if the respondent is ignoring qualification errors.
Presence	string	Attendance recorded for the respondent - one of 'unset', 'absent' or 'present'.
Staged	boolean	True when the respondent is staged and not published.
Planned	boolean	True when the respondent has been planned but not yet published.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

404

The project or the respondent does not exist, or the project has no schema.

Response

{

"Id": "{uuid}",

"Group": "{string}",

"Name": "{string}",

"Email": "{string}",

"PhoneNumber": "{string}",

"Country": "{string}",

"Language": "{string}",

"PanelId": "{null,string}",

"LastUpdated": "{date-time}",

"Created": "{date-time}",

"Data": {},

"Status": {

"Disqualified": "{boolean}",

"Held": "{boolean}",

"Overridden": "{boolean}",

"Presence": "{string}",

"Staged": "{boolean}",

"Planned": "{boolean}"

}

Copy

Move respondents to another tab

Moves the given respondents into another tab within the project. Requires the write API to be enabled for the tenant.

Auth

Path Params

projectId

string

Identifier of the project.

Request Body

Respondents to move and the group to move them into.

object	object
RespondentIds	array[string]	GUID identifiers of respondents to move.
TargetGroup	string	Name of the target group, as returned by the project schema endpoint.

POST /project/{projectId}/respondents/@move

curl --request POST \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/project/{projectId}/respondents/@move' \

--header 'Authorization: Bearer {token}' \

--data '{

"RespondentIds": [

"{array[string]...}"

"TargetGroup": "{string}"

Copy

Responses

204

The respondents were moved.

No response body

400

An empty respondent list, or 'invalid_target_group' when the group is not part of the project schema.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

403

The write API is disabled for this tenant.

404

No project exists with this identifier, or it has no schema.

Response

No response

Copy

Search projects

Returns the projects matching the filters. Every filter is optional and filters combine, so an empty body returns all open projects. Results are paged with StartRow and EndRow, and at most 1000 rows may be requested at a time.

Auth

Request Body

Filters and row window.

object	object
Tags	array[string]	Only return projects carrying at least one of these tags.
UpdatedBeforeDate	string?	Only return projects last modified before this instant.
UpdatedAfterDate	string?	Only return projects last modified after this instant.
ClientId	string?	Only return projects belonging to this client.
State	string	Which project states to include. Defaults to open projects only. Enum: `open`,`closed`,`both`
Properties	object	Custom property values to match, keyed by property identifier. Values must match the type of the property as returned by the project properties endpoint; dates may be sent as ISO 8601 strings. Unknown identifiers are rejected.
PropertiesFilter	object	Comparison to use for each entry in Properties, keyed by the same property identifier. Properties without an entry here are matched for equality.
*	string	Enum: `eq`,`gt`,`gte`,`lt`,`lte`,`ne`
StartRow	integer\|string	Zero based index of the first row to return. pattern: `^-?(?:0\|[1-9]\d*)$`
EndRow	integer\|string	Exclusive index of the last row to return. At most 1000 rows may be requested at a time. pattern: `^-?(?:0\|[1-9]\d*)$`

POST /project/@search

curl --request POST \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/project/@search' \

--header 'Authorization: Bearer {token}' \

--data '{

"Tags": [

"{array[string]...}"

"UpdatedBeforeDate": "{null,string}",

"UpdatedAfterDate": "{null,string}",

"ClientId": "{null,string}",

"State": "{string}",

"Properties": {},

"PropertiesFilter": {},

"StartRow": "{integer,string}",

"EndRow": "{integer,string}"

Copy

Responses

200

Matching projects for the requested page.

array	array[object]
Id	uuid	Unique identifier of the project.
Name	string	The internal name of the project as displayed to platform users.
ClientId	string?	Client the project belongs to, if one is set.
ClientName	string?	Name of the client the project belongs to, if one is set.
Created	date-time	When the project was created.
LastUpdated	string?	When the project was last modified.
Tags	array[string]	Tags applied to the project.
Counts3 fields	object	Recruitment progress across all groups in the project.
Required	integer\|string	Number of respondents the project needs across all groups. pattern: `^-?(?:0\|[1-9]\d*)$`
Count	integer\|string	Number of respondents currently recruited. pattern: `^-?(?:0\|[1-9]\d*)$`
Held	integer\|string	Number of recruited respondents that are flagged as being on hold. pattern: `^-?(?:0\|[1-9]\d*)$`
Properties	object	Custom project properties, keyed by property identifier. See the project properties endpoint for the identifiers and value types configured for this tenant.
State	string	Lifecycle state of the project. Enum: `open`,`pending_close`,`closed`

400

The row window is inverted or wider than 1000 rows, or a property filter uses an unknown identifier or a value of the wrong type.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

Response

[

{

"Id": "{uuid}",

"Name": "{string}",

"ClientId": "{null,string}",

"ClientName": "{null,string}",

"Created": "{date-time}",

"LastUpdated": "{null,string}",

"Tags": [

"{array[string]...}"

"Counts": {

"Required": "{integer,string}",

"Count": "{integer,string}",

"Held": "{integer,string}"

"Properties": {},

"State": "{string}"

}

]

Copy

Schedule

Operations related to calendar invitations

GET

/schedule/{projectId}

POST

/schedule/@search

List scheduled sessions for a project

Returns every active session booked with a respondent in the project. Cancelled invitations are not included.

Auth

Path Params

projectId

string

Identifier of the project.

GET /schedule/{projectId}

curl --get \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/schedule/{projectId}' \

--header 'Authorization: Bearer {token}'

Copy

Responses

200

Active sessions booked in the project.

array	array[object]
Id	uuid	Unique identifier of the invitation.
RespondentName	string	Name of the respondent.
RespondentGroup	string	The identifier of the group (tab) the respondent is in.
RespondentId	uuid	The unique identifier of the respondent.
Subject	string	Subject line of the calendar invitation.
AllDay	boolean	True when the calendar invitation is an all day event.
SessionStart	date-time	Start time of the session.
SessionEnd	date-time	End time of the session.
Location	string	The location of the session as defined in the calendar invitation template.
TimeZone	string	IANA time zone of the invitation.
Confirmed	string?	When the respondent confirmed attendance. Null if the invitation is unconfirmed.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

404

No project exists with this identifier.

Response

[

{

"Id": "{uuid}",

"RespondentName": "{string}",

"RespondentGroup": "{string}",

"RespondentId": "{uuid}",

"Subject": "{string}",

"AllDay": "{boolean}",

"SessionStart": "{date-time}",

"SessionEnd": "{date-time}",

"Location": "{string}",

"TimeZone": "{string}",

"Confirmed": "{null,string}"

}

]

Copy

Search scheduled sessions across projects

Returns active sessions booked with respondents across all open projects, ordered by start time. Every filter is optional and filters combine, so an empty body returns sessions from the start of today onwards. Results are paged with StartRow and EndRow, and at most 1000 rows may be requested at a time.

Auth

Request Body

Filters and row window.

object	object
StartDate	string?	Only return sessions starting at or after this instant. Defaults to the start of today.
EndDate	string?	Only return sessions starting at or before this instant.
ClientId	string?	Only return sessions in projects belonging to this client.
Confirmed	boolean?	Set to true to only return confirmed sessions, or false to only return unconfirmed sessions. Omit to return both.
StartRow	integer\|string	Zero based index of the first row to return. pattern: `^-?(?:0\|[1-9]\d*)$`
EndRow	integer\|string	Exclusive index of the last row to return. At most 1000 rows may be requested at a time. pattern: `^-?(?:0\|[1-9]\d*)$`

POST /schedule/@search

curl --request POST \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/schedule/@search' \

--header 'Authorization: Bearer {token}' \

--data '{

"StartDate": "{null,string}",

"EndDate": "{null,string}",

"ClientId": "{null,string}",

"Confirmed": "{null,boolean}",

"StartRow": "{integer,string}",

"EndRow": "{integer,string}"

Copy

Responses

200

Matching sessions for the requested page.

array	array[object]
Id	uuid	Unique identifier of the invitation.
ProjectId	uuid	The unique identifier of the project the session belongs to.
ProjectName	string	Internal name of the project the session belongs to.
RespondentName	string	Name of the respondent.
RespondentEmail	string	Email address of the respondent.
RespondentPhone	string	Phone number of the respondent in E.164 format.
RespondentCountry	string	Two letter ISO 3166-1 country code of the respondent.
RespondentLanguage	string	Language of the respondent.
RespondentGroup	string	The identifier of the group (tab) the respondent is in.
RespondentId	uuid	The unique identifier of the respondent.
Subject	string	Subject line of the calendar invitation.
AllDay	boolean	True when the calendar invitation is an all day event.
SessionStart	date-time	Start time of the session.
SessionEnd	date-time	End time of the session.
Location	string	The location of the session as defined in the calendar invitation template.
TimeZone	string	IANA time zone of the invitation.
Confirmed	string?	When the respondent confirmed attendance. Null if the invitation is unconfirmed.

400

The row window is negative, inverted, or wider than 1000 rows, or StartDate is after EndDate.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

Response

[

{

"Id": "{uuid}",

"ProjectId": "{uuid}",

"ProjectName": "{string}",

"RespondentName": "{string}",

"RespondentEmail": "{string}",

"RespondentPhone": "{string}",

"RespondentCountry": "{string}",

"RespondentLanguage": "{string}",

"RespondentGroup": "{string}",

"RespondentId": "{uuid}",

"Subject": "{string}",

"AllDay": "{boolean}",

"SessionStart": "{date-time}",

"SessionEnd": "{date-time}",

"Location": "{string}",

"TimeZone": "{string}",

"Confirmed": "{null,string}"

}

]

Copy

System

Operations related to general system services

POST

/system/suppressionList/@search

POST

/system/suppressionList/@remove

POST

/system/suppressionList

Search the mail suppression list

Returns the email addresses that are on the global email suppression list. Every filter is optional and filters combine. Results are paged with StartRow and EndRow, and at most 1000 rows may be requested at a time.

Auth

Request Body

Filters and row window.

object	object
AddedDateBefore	string?	Only return entries added before this instant.
AddedDateAfter	string?	Only return entries added after this instant.
Email	string?	Only return the entry for this exact email address.
Type	string	Only return entries suppressed for this reason. Defaults to all reasons. Enum: `all`,`unsub`,`bounce`,`complaint`
StartRow	integer\|string	Zero based index of the first row to return. pattern: `^-?(?:0\|[1-9]\d*)$`
EndRow	integer\|string	Exclusive index of the last row to return. At most 1000 rows may be requested at a time. pattern: `^-?(?:0\|[1-9]\d*)$`

POST /system/suppressionList/@search

curl --request POST \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/system/suppressionList/@search' \

--header 'Authorization: Bearer {token}' \

--data '{

"AddedDateBefore": "{null,string}",

"AddedDateAfter": "{null,string}",

"Email": "{null,string}",

"Type": "{string}",

"StartRow": "{integer,string}",

"EndRow": "{integer,string}"

Copy

Responses

200

Matching suppression entries for the requested page.

array	array[object]
Email	string	The suppressed email address.
Reason	string	Why the address was suppressed - one of 'unsub', 'bounce' or 'complaint'.
Added	date-time	When the address was added to the suppression list.

400

'start_row' when the row window is negative or inverted, 'end_row' when it is wider than 1000 rows.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

Response

[

{

"Email": "{string}",

"Reason": "{string}",

"Added": "{date-time}"

}

]

Copy

Remove addresses from the mail suppression list

Removes the given email addresses from the global suppression list. Requires the write API to be enabled for the tenant.

Auth

Request Body

Addresses to release.

object	object
Emails	array[string]	Email addresses to remove from the global suppression list. Maximum 1000 per call.

POST /system/suppressionList/@remove

curl --request POST \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/system/suppressionList/@remove' \

--header 'Authorization: Bearer {token}' \

--data '{

"Emails": [

"{array[string]...}"

]

Copy

Responses

204

The addresses are no longer suppressed.

No response body

400

'email_count' when more than 1000 addresses are sent, 'email_format' when an entry is not a bare email address.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

403

The write API is disabled for this tenant.

Response

No response

Copy

Add addresses to the mail suppression list

Adds an email address to the global suppression list. Addresses that are already on the list are not affected.

Auth

Request Body

Addresses to suppress.

object	object
Emails	array[string]	Email addresses to suppress. Maximum 1000 per call.

POST /system/suppressionList

curl --request POST \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/system/suppressionList' \

--header 'Authorization: Bearer {token}' \

--data '{

"Emails": [

"{array[string]...}"

]

Copy

Responses

204

The addresses are now suppressed.

No response body

400

'email_count' when more than 1000 addresses are sent, 'email_format' when an entry is not a bare email address.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

Response

No response

Copy

Voice

Operations related to voice calls

GET

/voice/callLog/{projectId}

List calls for a project

Returns the completed (including missed) calls placed to or received from respondents in a project, ordered by most recent first. Results are returned 100 calls at a time.

Auth

Path Params

projectId

string

Identifier of the project.

Query String

page

integer|string

Zero based page number. Each page holds 100 calls.

pattern: ^-?(?:0|[1-9]\d*)$

GET /voice/callLog/{projectId}

curl --get \

--url 'https://{tenant_id}.service.respondentlink.app/-/api/v1/voice/callLog/{projectId}' \

--header 'Authorization: Bearer {token}' \

--data page={page}

Copy

Responses

200

The requested page of calls.

array	array[object]
Id	uuid	Unique identifier of the call.
Description	string	Free text description recorded against the call.
Direction	string	Whether the call was placed to ('out') or received from ('in') the respondent. Enum: `in`,`out`
StartTime	date-time	When the call started.
EndedTime	string?	When the call ended. Null while the call is still in progress.
RespondentId	uuid	Identifier of the respondent that was called.
Initiator	string?	Email address of the user that placed or answered the call. Null for missed or unanswered calls.
Status	string	Outcome of the call. Enum: `initiated`,`active`,`complete`,`failed`,`missed`,`unknown`
Name	string	Name of the respondent at the time the log was read.
Group	string	Grid tab the respondent currently belongs to.

401

The token is missing, unknown, disabled or expired, or the API is not enabled for the tenant.

404

No project exists with this identifier.

Response

[

{

"Id": "{uuid}",

"Description": "{string}",

"Direction": "{string}",

"StartTime": "{date-time}",

"EndedTime": "{null,string}",

"RespondentId": "{uuid}",

"Initiator": "{null,string}",

"Status": "{string}",

"Name": "{string}",

"Group": "{string}"

}

]

Copy

QualRecruit Platform API v1Proprietary

Authentication

Clients

Search clients

Get a client

Incentives

Search incentives

Get an incentive

Panel

List panel exports

Request a panel export

Get a panel export

Get the panel schema

Get a panelist

Delete a panelist

Update a panelist

Search panelists

Create a panelist

Import panelists in bulk

Update panelists in bulk

Projects

Create a project

Get a project

List custom project properties

Get a project schema

List respondents in a project

List the survey feed for a group

Get validation results for a group

Get a respondent

Move respondents to another tab

Search projects

Schedule

List scheduled sessions for a project

Search scheduled sessions across projects

System

Search the mail suppression list

Remove addresses from the mail suppression list

Add addresses to the mail suppression list

Voice

List calls for a project

QualRecruit Platform API v1 Proprietary