Introduction
Welcome to TheoremReach's DIY Platform API.
Environments
To ease integration development, we have a sandbox environment that you can run tests against. You can use your production credentials to access the sandbox environment. Please note that after creating or updating credentials in production, there may be a short delay before they are available in sandbox.
Sandbox URL: https://surveys-sandbox.theoremreach.com/api/external/v1/
Production URL: https://surveys.theoremreach.com/api/external/v1/
Security
Authentication
# Header Authentication Example
curl https://surveys.theoremreach.com/api/external/v1/countries
-H 'X-Api-Key: NDAyMTVhOGQtZjFhMy00ZjI0LThiYmQtNzExZTdmMzcyMWE4'
# Query Parameter Authentication Example
curl https://surveys.theoremreach.com/api/external/v1/countries?api_key=50215a8d-a1a3-4f24-8xbd-721e763721a8
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI("https://surveys.theoremreach.com/api/external/v1/countries")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request["X-Api-Key"] = Base64.encode64("50215a8d-a1a3-4f24-8xbd-721e763721a8")
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :get,
url: "https://surveys.theoremreach.com/api/external/v1/countries",
content_type: "application/json",
headers: {
"X-Api-Key": Base64.encode64("50215a8d-a1a3-4f24-8xbd-721e763721a8")
}
)
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/countries",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
"Content-Type: application/json",
"X-Api-Key: " . base64_encode("50215a8d-a1a3-4f24-8xbd-721e763721a8")
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET"
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/countries"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("50215a8d-a1a3-4f24-8xbd-721e763721a8")
}
requests.get(url, headers=headers)
const https = require('https');
const options = {
"method": "GET",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/countries",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("50215a8d-a1a3-4f24-8xbd-721e763721a8").toString('base64')
}
};
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write();
request.end();
TheoremReach's DIY API uses and requires API key based authentication for all requests.
There are two primary methods for authenticating via your API key:
- Provide your base64 encoded API key in the
X-Api-KeyHTTP header. - Provide your API key in the
api_keyquery parameter.
HTTP Header Encoder for API Keys
Rate Limiting
There is currently a rate limit of 10 requests per second.
IP Whitelisting (Optional)
We provide the ability to specify a static list of whitelisted IP addresses. Only requests coming from these IP addresses will be successfully authorized.
To enable this feature go to your company's settings.
Request Hashing (Required)
The What?
Request hashing is used by TheoremReach to validate the authenticity of a given request. We do this through the use of hashing the full request along with your company’s secret key. The hashing algorithm used currently defaults to sha3-256, which is the recommended algorithm to be used with our system.
The Why?
Request hashing is a required feature of the DIY API that allows TheoremReach to validate the authenticity of API requests made on your company's behalf.
The How?
Request hashing is accomplished by creating a hash of your request url (including query parameters), your company’s secret key, and the request's raw body. The hashed value is then added to the end of your request url using the enc query parameter.
# Using rhash
echo "{{ request_url }}{{ json_body}}{{ secret_key }}" > /tmp/checksum_test
rhash --sha3-256 /tmp/checksum_test
require 'sha3'
request_url = 'https://surveys.theoremreach.com/api/external/v1/countries'
json_body = { :key => 'value' }
secret_key = 'abcd1234'
secret_url = request_url + json_body.to_json + secret_key
hash = SHA3::Digest.hexdigest :sha256, secret_url
hashed_url = request_url + '?enc=' + hash
<?php
$request_url = 'https://surveys.theoremreach.com/api/external/v1/countries';
$json_body = ['key' => 'value'];
$secret_key = 'abcd1234';
$secret_url = $request_url . json_encode($json_body) . $secret_key;
$hash = hash('sha3-256', $secret_url);
$hashed_url = $request_url . '?enc=' . $hash;
import json
import hashlib
request_url = 'https://surveys.theoremreach.com/api/external/v1/countries'
json_body = { 'key': 'value' }
secret_key = 'abcd1234'
secret_url = "{}{}{}".format(request_url, json.dumps(json_body), secret_key)
h = hashlib.sha3_256()
h.update(secret_url.encode('utf-8'))
hashed_url = "{}?enc={}".format(request_url, h.hexdigest())
const { SHA3 } = require('sha3');
const requestUrl = 'https://surveys.theoremreach.com/api/external/v1/countries';
const jsonBody = { 'key': 'value' };
const secretKey = 'abcd1234';
const secretUrl = requestUrl + JSON.encode(jsonBody) + secretKey;
const hash = new SHA3(256);
hash.update(secretUrl);
hashedUrl = `${requestUrl}?enc=${hash.digest('hash')}`;
GET/DELETE Requests
Given The Values
Request URL: https://surveys.theoremreach.com/api/endpoint?param_one=value_one
Company Secret Key: UbsXaKTGWNd3wD8y5ZeV
We Hash Them
{Request URL}+{Company Secret Key}
https://surveys.theoremreach.com/api/endpoint?param_one=value_oneUbsXaKTGWNd3wD8y5ZeV
Which Gives The Hash
11409fe7199b4c3856873e9b0553fd8e1920d1fba1cf59c5517ba2e4ee3b87fd
And Gets Added To The URL
https://surveys.theoremreach.com/api/endpoint?param_one=value_one&enc=85598cc6d64d6d2490d088b070f955258d97840506731129958ed70a29db396e
POST/PUT Requests
Given The Values
Request URL: https://surveys.theoremreach.com/api/endpoint
Company Secret Key: UbsXaKTGWNd3wD8y5ZeV
JSON Body: {“key”:“value”}
We Hash Them
{Request URL}+{JSON Body}+{Company Secret Key}
https://surveys.theoremreach.com/api/endpoint{“key”:“value”}UbsXaKTGWNd3wD8y5ZeV
Which Gives The Hash
58f191965859fc34fc2c96bba2fe8d633e74a9fea87ff4d362a202a68f4f26e8
And Gets Added To The URL Or JSON Body
https://surveys.theoremreach.com/api/endpoint?enc=b3ce2e72133a4d7eb69cf563249c969c9a7ea70331fee986f79df29cc387957d
Verifying External Completes
We currently offer two avenues for verifying a respondent's survey completion: User Redirection with URL Hashing for improved security, or a Server-to-Server Postback/Callback.
Redirection with URL Hashing
Request:
GET https://surveys.theoremreach.com/respondent_result/?result={{ result }}&transaction_id={{ transaction_id }}&enc={{ generated_request_hash }}
URL security hashing is a secure, realtime pattern for verifying a respondent's completion of a survey by use of HTTP redirections and a request-specific hash used to securely transmit untampered respondent information.
Using this method will require the use of the Request Hashing section described above. Namely, we will only be dealing with GET HTTP requests, making implementation straight forward.
To enable this endpoint your company will need to choose a hashing algorithm by going to your company's api settings page and selecting an algorithm for URL Encryption, under Routing URL Security. Currently, we offer SHA1, SHA2, and SHA3-256 encryption types.
Example HTTP Request Signature
GET https://surveys.theoremreach.com/respondent_result/
Query Parameters Provided
| Parameter | Required | Default | Description |
|---|---|---|---|
| transaction_id | Yes | None | The ID corresponding to the transaction we are processing. |
| result | Yes | None | Result ID corresponding to the respondent's result for the survey. 3 = overquota 4 = disqualified 5 = screenout 10 = success |
| reason | No | None | Supply an internal (to your company) reason identifier, or general additional information, regarding the reason for the result. |
| enc | Yes | None | Generated request hash |
Server-to-Server Postback
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/respondent_result/callbacks/?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {:transaction_id=>"c7754877-28ab-4c69-950c-80f34ad349ed", :result=>10, :reason=>"No Example Provided"}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :post,
url: 'https://surveys.theoremreach.com/respondent_result/callbacks/?enc={{ generated_request_hash }}',
payload: {:transaction_id=>"c7754877-28ab-4c69-950c-80f34ad349ed", :result=>10, :reason=>"No Example Provided"},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/respondent_result/callbacks/?enc={{ generated_request_hash }}"
-X POST
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
-H "Content-Type: application/json"
--data '{"transaction_id":"c7754877-28ab-4c69-950c-80f34ad349ed","result":10,"reason":"No Example Provided"}'
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/respondent_result/callbacks/?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => '{"transaction_id":"c7754877-28ab-4c69-950c-80f34ad349ed","result":10,"reason":"No Example Provided"}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/respondent_result/callbacks/?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {"transaction_id":"c7754877-28ab-4c69-950c-80f34ad349ed","result":10,"reason":"No Example Provided"}
requests.post(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "POST",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/respondent_result/callbacks/?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {"transaction_id":"c7754877-28ab-4c69-950c-80f34ad349ed","result":10,"reason":"No Example Provided"};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
204 No Content (success)
Postback verification is a secure server-to-server pattern used when Redirection with URL Hashing is not possible.
Using this method allows you and your team to make use of Request Hashing, described above. The hashing algorithm is the same one described within the Redirection with URL Hashing documentation above.
Example HTTP Request Signature
POST https://surveys.theoremreach.com/respondent_result/callbacks/
Query Parameters Provided
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
JSON Fields
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
| transaction_id | Yes | The ID corresponding to the transaction we are processing. | ||
| result | Yes | Result ID corresponding to the respondent's result for the survey. 3 = overquota 4 = disqualified 5 = screenout 10 = success |
||
| reason | No | Supply an internal (to your company) reason identifier, or general additional information, regarding the reason for the result. |
Resources
Countries
List Active Countries
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/countries?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :get,
url: 'https://surveys.theoremreach.com/api/external/v1/countries?enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/countries?enc={{ generated_request_hash }}"
-X GET
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/countries?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/countries?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
requests.get(url, headers=headers)
const https = require('https');
const options = {
"method": "GET",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/countries?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": [
{
"id": "5a8296a0-0ab0-4e75-be00-71a6371b519b",
"name": "United States"
},
{
"id": "1bb42394-b037-49c6-9053-5b326c62dee2",
"name": "Argentina"
},
{
"id": "6683bb57-1e3b-449e-8879-a2bfeaf29844",
"name": "Australia"
},
...
]
}
Retrieves a list of active countries.
HTTP Request
GET https://surveys.theoremreach.com/api/external/v1/countries
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
Mapping Partners
List Active Mapping Partners
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/mapping_partners?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :get,
url: 'https://surveys.theoremreach.com/api/external/v1/mapping_partners?enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/mapping_partners?enc={{ generated_request_hash }}"
-X GET
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/mapping_partners?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/mapping_partners?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
requests.get(url, headers=headers)
const https = require('https');
const options = {
"method": "GET",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/mapping_partners?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": [
{
"id": "ceed3b0f-650a-4e00-83b4-6987eb47b37b",
"name": "TheoremReach"
},
{
"id": "4a91e105-bd9d-44c9-89ae-65585fd6c29c",
"name": "Lucid"
},
...
],
"meta": {
"warnings": []
}
}
Retrieves a list of active mapping partners.
HTTP Request
GET https://surveys.theoremreach.com/api/external/v1/mapping_partners
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
Buyer
Sub-buyers represent sub-divisions or sub-accounts under your company, allowing surveys to be organized and tracked by business unit. Surveys can optionally be associated with a sub-buyer via the sub_buyer_id field.
Questions
List Questions
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/questions?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&page={{ page }}&per_page={{ per_page }}&enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :get,
url: 'https://surveys.theoremreach.com/api/external/v1/questions?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&page={{ page }}&per_page={{ per_page }}&enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/questions?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&page={{ page }}&per_page={{ per_page }}&enc={{ generated_request_hash }}"
-X GET
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/questions?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&page={{ page }}&per_page={{ per_page }}&enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/questions?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&page={{ page }}&per_page={{ per_page }}&enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
requests.get(url, headers=headers)
const https = require('https');
const options = {
"method": "GET",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/questions?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&page={{ page }}&per_page={{ per_page }}&enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": [
{
"id": "f2c062da-9f63-4602-88a8-e8525a4f1443",
"english_text": "What is your age?",
"localized_text": "What is your age?",
"name": "Age",
"question_type": "single_select"
},
{
"id": "dd8192cb-81da-42c7-946c-984010858efb",
"english_text": "What is your gender?",
"localized_text": "What is your gender?",
"name": "Gender",
"question_type": "single_select"
},
{
"id": "8c721cac-ebf2-4854-9935-e81e3944281e",
"english_text": "What is your zip code?",
"localized_text": "What is your zip code?",
"name": "Zip",
"question_type": "postal"
},
...
]
"meta": {
"page": 1,
"per_page": 50,
"total": 127,
"warnings": []
}
}
Retrieves a list of questions scoped to the mapping partner and country.
HTTP Request
GET https://surveys.theoremreach.com/api/external/v1/questions
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| country_id | Yes | None | Country ID |
| mapping_partner_id | No | TheoremReach | Mapping Partner ID |
| include_all | No | None | When true, returns questions from all available categories and provider partners, not just the standard set. Useful for finding niche targeting criteria beyond age, gender, and standard demographics. |
| page | No | 1 | Page number (1-indexed). |
| per_page | No | 50 | Results per page. Maximum: 200. |
| enc | Yes | None | Generated request hash |
Answers
List Answers
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/questions/{{ question_id }}/answers?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&question_id={{ question_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :get,
url: 'https://surveys.theoremreach.com/api/external/v1/questions/{{ question_id }}/answers?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&question_id={{ question_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/questions/{{ question_id }}/answers?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&question_id={{ question_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}"
-X GET
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/questions/{{ question_id }}/answers?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&question_id={{ question_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/questions/{{ question_id }}/answers?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&question_id={{ question_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
requests.get(url, headers=headers)
const https = require('https');
const options = {
"method": "GET",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/questions/{{ question_id }}/answers?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&question_id={{ question_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": [
{
"id": "325828",
"english_text": "Desktop",
"localized_text": "Desktop"
},
{
"id": "325829",
"english_text": "Phone",
"localized_text": "Phone"
},
{
"id": "325830",
"english_text": "Tablet",
"localized_text": "Tablet"
}
...
]
"meta": {
"warnings": []
}
}
Retrieves a list of answers scoped to the mapping partner, country, and question.
HTTP Request
GET https://surveys.theoremreach.com/api/external/v1/questions/{{ question_id }}/answers
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| country_id | Yes | None | Country ID |
| mapping_partner_id | No | TheoremReach | Mapping Partner ID |
| question_id | Yes | None | Question ID |
| include_all | No | None | When true, returns answers for non-standard questions that are only available via the include_all=true questions endpoint. Must match the include_all setting used when listing questions. |
| enc | Yes | None | Generated request hash |
Surveys
List Surveys
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/surveys?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :get,
url: 'https://surveys.theoremreach.com/api/external/v1/surveys?enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/surveys?enc={{ generated_request_hash }}"
-X GET
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/surveys?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/surveys?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
requests.get(url, headers=headers)
const https = require('https');
const options = {
"method": "GET",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/surveys?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": [
{
"id": "e6bad93a-fb3c-423e-bea1-b9746bcd9786",
"name": "New Survey",
"state": "draft",
"quota_mode": "nested",
"entry_url_prod": "https://surveyprovider.com/prod/?transaction_id={transaction_id}",
"entry_url_test": "https://surveyprovider.com/test/?transaction_id={transaction_id}",
"start_at": "2019-12-18T06:00:00Z",
"end_at": null,
"cpi": null,
"metrics": {
"target_completes": 25,
"remaining_completes": 25,
"completes_count": 0,
"effective_cpi": 0.0
},
"country": {
"id": "5a8296a0-0ab0-4e75-be00-71a6371b519b",
"name": "United States"
},
"sub_buyer": {
"id": "b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c",
"name": "West Coast Division"
}
},
...
],
"meta": {
"warnings": []
}
}
Retrieves a list of all surveys in your system.
HTTP Request
GET https://surveys.theoremreach.com/api/external/v1/surveys
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
Get Survey Details
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}?mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :get,
url: 'https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}?mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}?mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}"
-X GET
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}?mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}?mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
requests.get(url, headers=headers)
const https = require('https');
const options = {
"method": "GET",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/surveys/{{ survey_id }}?mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": {
"id": "e6bad93a-fb3c-423e-bea1-b9746bcd9786",
"name": "New Survey",
"state": "draft",
"quota_mode": "nested",
"entry_url_prod": "https://google.com/prod/?transaction_id={transaction_id}",
"entry_url_test": "https://google.com/test/?transaction_id={transaction_id}",
"start_at": "2019-12-18T06:00:00Z",
"end_at": null,
"cpi": null,
"metrics": {
"target_completes": 25,
"remaining_completes": 25,
"completes_count": 0,
"effective_cpi": 0.0,
"attempts_count": 0,
"attempts_in_dollars": 0.0,
"completes_in_dollars": 0.0,
"calculated_length_of_interview": null,
"conversion_rate": 0.0,
"trailing_50_day_conversion_rate": 0.0
},
"state_reason": null,
"state_updated_at": null,
"estimated_length_of_interview": 10,
"estimated_conversion_rate": 25,
"max_authorized_cpi": 1.25,
"country": {
"id": "5a8296a0-0ab0-4e75-be00-71a6371b519b",
"name": "United States"
},
"quotas": [
{
"id": "244a38a0-2992-461b-aeb0-c13bc0181fbb",
"name": null,
"state": "active",
"questions": [],
"metrics": {
"target_completes": 25,
"remaining_completes": 25,
"completes_count": 0,
"effective_cpi": 0.0,
"attempts_count": 0,
"attempts_in_dollars": 0.0,
"completes_in_dollars": 0.0,
"conversion_rate": 0.0
}
}
],
"survey_groups": [],
"sub_buyer": {
"id": "b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c",
"name": "West Coast Division"
}
},
"meta": {
"warnings": []
}
}
Retrieves a survey's full attributes, metrics, associated country, and partial quota data.
HTTP Request
GET https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| mapping_partner_id | No | None | Mapping Partner ID |
| enc | Yes | None | Generated request hash |
Create a New Survey
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/surveys?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {:name=>"My New Survey", :entry_url_prod=>"https://surveyprovider.com/prod/?transaction_id={transaction_id}", :entry_url_test=>"https://surveyprovider.com/test/?transaction_id={transaction_id}", :estimated_length_of_interview=>12, :estimated_conversion_rate=>54, :max_authorized_cpi=>1.25, :cpi=>1.25, :start_at=>"2019-12-18T06:00:00Z", :end_at=>"2019-12-20T06:00:00Z", :country_id=>"5a8296a0-0ab0-4e75-be00-71a6371b519b", :survey_groups=>["ef344409-fd95-4cf0-a8a7-52237fe96d48"], :sub_buyer_id=>"b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c", :quota_mode=>"nested"}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :post,
url: 'https://surveys.theoremreach.com/api/external/v1/surveys?enc={{ generated_request_hash }}',
payload: {:name=>"My New Survey", :entry_url_prod=>"https://surveyprovider.com/prod/?transaction_id={transaction_id}", :entry_url_test=>"https://surveyprovider.com/test/?transaction_id={transaction_id}", :estimated_length_of_interview=>12, :estimated_conversion_rate=>54, :max_authorized_cpi=>1.25, :cpi=>1.25, :start_at=>"2019-12-18T06:00:00Z", :end_at=>"2019-12-20T06:00:00Z", :country_id=>"5a8296a0-0ab0-4e75-be00-71a6371b519b", :survey_groups=>["ef344409-fd95-4cf0-a8a7-52237fe96d48"], :sub_buyer_id=>"b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c", :quota_mode=>"nested"},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/surveys?enc={{ generated_request_hash }}"
-X POST
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
-H "Content-Type: application/json"
--data '{"name":"My New Survey","entry_url_prod":"https://surveyprovider.com/prod/?transaction_id={transaction_id}","entry_url_test":"https://surveyprovider.com/test/?transaction_id={transaction_id}","estimated_length_of_interview":12,"estimated_conversion_rate":54,"max_authorized_cpi":1.25,"cpi":1.25,"start_at":"2019-12-18T06:00:00Z","end_at":"2019-12-20T06:00:00Z","country_id":"5a8296a0-0ab0-4e75-be00-71a6371b519b","survey_groups":["ef344409-fd95-4cf0-a8a7-52237fe96d48"],"sub_buyer_id":"b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c","quota_mode":"nested"}'
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/surveys?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => '{"name":"My New Survey","entry_url_prod":"https://surveyprovider.com/prod/?transaction_id={transaction_id}","entry_url_test":"https://surveyprovider.com/test/?transaction_id={transaction_id}","estimated_length_of_interview":12,"estimated_conversion_rate":54,"max_authorized_cpi":1.25,"cpi":1.25,"start_at":"2019-12-18T06:00:00Z","end_at":"2019-12-20T06:00:00Z","country_id":"5a8296a0-0ab0-4e75-be00-71a6371b519b","survey_groups":["ef344409-fd95-4cf0-a8a7-52237fe96d48"],"sub_buyer_id":"b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c","quota_mode":"nested"}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/surveys?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {"name":"My New Survey","entry_url_prod":"https://surveyprovider.com/prod/?transaction_id={transaction_id}","entry_url_test":"https://surveyprovider.com/test/?transaction_id={transaction_id}","estimated_length_of_interview":12,"estimated_conversion_rate":54,"max_authorized_cpi":1.25,"cpi":1.25,"start_at":"2019-12-18T06:00:00Z","end_at":"2019-12-20T06:00:00Z","country_id":"5a8296a0-0ab0-4e75-be00-71a6371b519b","survey_groups":["ef344409-fd95-4cf0-a8a7-52237fe96d48"],"sub_buyer_id":"b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c","quota_mode":"nested"}
requests.post(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "POST",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/surveys?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {"name":"My New Survey","entry_url_prod":"https://surveyprovider.com/prod/?transaction_id={transaction_id}","entry_url_test":"https://surveyprovider.com/test/?transaction_id={transaction_id}","estimated_length_of_interview":12,"estimated_conversion_rate":54,"max_authorized_cpi":1.25,"cpi":1.25,"start_at":"2019-12-18T06:00:00Z","end_at":"2019-12-20T06:00:00Z","country_id":"5a8296a0-0ab0-4e75-be00-71a6371b519b","survey_groups":["ef344409-fd95-4cf0-a8a7-52237fe96d48"],"sub_buyer_id":"b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c","quota_mode":"nested"};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": {
"id": "39584dfe-e64f-45b4-9f6a-50f88723af87",
"name": "My New Survey",
"state": "draft",
"quota_mode": "nested",
"entry_url_prod": "https://surveyprovider.com/prod/?transaction_id={transaction_id}",
"entry_url_test": "https://surveyprovider.com/test/?transaction_id={transaction_id}",
"start_at": "2019-12-18T06:00:00Z",
"end_at": "2019-12-20T06:00:00Z",
"metrics": {
"target_completes": 0,
"remaining_completes": 0,
"completes_count": 0,
"effective_cpi": 0.0,
"attempts_count": 0,
"attempts_in_dollars": 0.0,
"completes_in_dollars": 0.0,
"calculated_length_of_interview": null,
"conversion_rate": 0.0,
"trailing_50_day_conversion_rate": 0.0
},
"state_reason": null,
"state_updated_at": null,
"estimated_length_of_interview": 12,
"estimated_conversion_rate": 54,
"max_authorized_cpi": 1.25,
"cpi": 0.75,
"country": {
"id": "5a8296a0-0ab0-4e75-be00-71a6371b519b",
"name": "United States"
},
"quotas": [],
"survey_groups": [],
"sub_buyer": null
},
"meta": {
"warnings": []
}
}
Creates a new survey with the provided attributes.
Respondent demographics associated with the matched quota will be automatically appended to the entry URL with the following format: "&mapping_partner_question_id=comma_separated_answer_ids"
Respondent postal codes will be appended to the entry URL with the following format: "&postal_code=respondent_postal_code"
HTTP Request
POST https://surveys.theoremreach.com/api/external/v1/surveys
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
JSON Fields
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
| name | No | string | Name of the survey. | |
| entry_url_prod | No | string | SSL-enabled URL used to enter the live survey. Must contain ={transaction_id}. |
|
| entry_url_test | No | string | SSL-enabled URL used to enter the test survey. Must contain ={transaction_id}. |
|
| estimated_length_of_interview | No | integer | Estimated length to take the survey, in minutes. | |
| estimated_conversion_rate | No | integer | Estimated conversion rate. Range: 1 - 100 | |
| max_authorized_cpi | No | float | Maximum authorized CPI for the survey. This option may only be provided if your company has this feature enabled. | |
| cpi | No | float | Bid CPI for this survey -- (range: 0.75 - 20.00). This field is only enabled if your company has biddable cpi enabled. If you wish to have this feature enabled please contact an admin at TheoremReach. | |
| start_at | No | datetime | DateTime used to start the survey. ISO8601 format in UTC is expected. | |
| end_at | No | datetime | DateTime used to end the survey. ISO8601 format in UTC is expected. | |
| country_id | No | string | Country this survey should run in. | |
| survey_groups | No | array | List of survey IDs that, if already taken, should exclude the user from this survey. | |
| sub_buyer_id | No | string | The uid of a sub-buyer to associate with this survey. Must belong to the authenticated company. Pass null explicitly on update to disassociate. |
|
| quota_mode | No | string | nested | Quota mode for the survey. nested (traditional interlocked quotas) or independent (dimension-based quotas with auto-generated cells). Can only be changed in draft state. Warning: Switching modes deletes all existing quota configuration. |
Update a Survey
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Put.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {:name=>"My Updated Survey", :entry_url_prod=>"https://surveyprovider.com/prod/?transaction_id={transaction_id}", :entry_url_test=>"https://surveyprovider.com/test/?transaction_id={transaction_id}", :estimated_length_of_interview=>12, :estimated_conversion_rate=>54, :max_authorized_cpi=>1.25, :cpi=>1.25, :start_at=>"2019-12-18T06:00:00Z", :end_at=>"2019-12-20T06:00:00Z", :country_id=>"5a8296a0-0ab0-4e75-be00-71a6371b519b", :survey_groups=>["ef344409-fd95-4cf0-a8a7-52237fe96d48"], :sub_buyer_id=>"b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c", :quota_mode=>"nested"}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :put,
url: 'https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}?enc={{ generated_request_hash }}',
payload: {:name=>"My Updated Survey", :entry_url_prod=>"https://surveyprovider.com/prod/?transaction_id={transaction_id}", :entry_url_test=>"https://surveyprovider.com/test/?transaction_id={transaction_id}", :estimated_length_of_interview=>12, :estimated_conversion_rate=>54, :max_authorized_cpi=>1.25, :cpi=>1.25, :start_at=>"2019-12-18T06:00:00Z", :end_at=>"2019-12-20T06:00:00Z", :country_id=>"5a8296a0-0ab0-4e75-be00-71a6371b519b", :survey_groups=>["ef344409-fd95-4cf0-a8a7-52237fe96d48"], :sub_buyer_id=>"b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c", :quota_mode=>"nested"},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}?enc={{ generated_request_hash }}"
-X PUT
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
-H "Content-Type: application/json"
--data '{"name":"My Updated Survey","entry_url_prod":"https://surveyprovider.com/prod/?transaction_id={transaction_id}","entry_url_test":"https://surveyprovider.com/test/?transaction_id={transaction_id}","estimated_length_of_interview":12,"estimated_conversion_rate":54,"max_authorized_cpi":1.25,"cpi":1.25,"start_at":"2019-12-18T06:00:00Z","end_at":"2019-12-20T06:00:00Z","country_id":"5a8296a0-0ab0-4e75-be00-71a6371b519b","survey_groups":["ef344409-fd95-4cf0-a8a7-52237fe96d48"],"sub_buyer_id":"b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c","quota_mode":"nested"}'
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => '{"name":"My Updated Survey","entry_url_prod":"https://surveyprovider.com/prod/?transaction_id={transaction_id}","entry_url_test":"https://surveyprovider.com/test/?transaction_id={transaction_id}","estimated_length_of_interview":12,"estimated_conversion_rate":54,"max_authorized_cpi":1.25,"cpi":1.25,"start_at":"2019-12-18T06:00:00Z","end_at":"2019-12-20T06:00:00Z","country_id":"5a8296a0-0ab0-4e75-be00-71a6371b519b","survey_groups":["ef344409-fd95-4cf0-a8a7-52237fe96d48"],"sub_buyer_id":"b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c","quota_mode":"nested"}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {"name":"My Updated Survey","entry_url_prod":"https://surveyprovider.com/prod/?transaction_id={transaction_id}","entry_url_test":"https://surveyprovider.com/test/?transaction_id={transaction_id}","estimated_length_of_interview":12,"estimated_conversion_rate":54,"max_authorized_cpi":1.25,"cpi":1.25,"start_at":"2019-12-18T06:00:00Z","end_at":"2019-12-20T06:00:00Z","country_id":"5a8296a0-0ab0-4e75-be00-71a6371b519b","survey_groups":["ef344409-fd95-4cf0-a8a7-52237fe96d48"],"sub_buyer_id":"b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c","quota_mode":"nested"}
requests.put(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "PUT",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/surveys/{{ survey_id }}?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {"name":"My Updated Survey","entry_url_prod":"https://surveyprovider.com/prod/?transaction_id={transaction_id}","entry_url_test":"https://surveyprovider.com/test/?transaction_id={transaction_id}","estimated_length_of_interview":12,"estimated_conversion_rate":54,"max_authorized_cpi":1.25,"cpi":1.25,"start_at":"2019-12-18T06:00:00Z","end_at":"2019-12-20T06:00:00Z","country_id":"5a8296a0-0ab0-4e75-be00-71a6371b519b","survey_groups":["ef344409-fd95-4cf0-a8a7-52237fe96d48"],"sub_buyer_id":"b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c","quota_mode":"nested"};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": {
"id": "39584dfe-e64f-45b4-9f6a-50f88723af87",
"name": "My Updated Survey",
"state": "draft",
"quota_mode": "nested",
"entry_url_prod": "https://surveyprovider.com/prod/?transaction_id={transaction_id}",
"entry_url_test": "https://surveyprovider.com/test/?transaction_id={transaction_id}",
"start_at": "2019-12-18T06:00:00Z",
"end_at": "2019-12-20T06:00:00Z",
"metrics": {
"target_completes": 0,
"remaining_completes": 0,
"completes_count": 0,
"effective_cpi": 0.0,
"attempts_count": 0,
"attempts_in_dollars": 0.0,
"completes_in_dollars": 0.0,
"calculated_length_of_interview": null,
"conversion_rate": 0.0,
"trailing_50_day_conversion_rate": 0.0
},
"state_reason": null,
"state_updated_at": null,
"estimated_length_of_interview": 12,
"estimated_conversion_rate": 54,
"max_authorized_cpi": 1.25,
"cpi": 1.25,
"country": {
"id": "5a8296a0-0ab0-4e75-be00-71a6371b519b",
"name": "United States"
},
"quotas": [],
"survey_groups": [],
"sub_buyer": null
},
"meta": {
"warnings": []
}
}
Updates a survey with the provided attributes.
HTTP Request
PUT https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
JSON Fields
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
| name | No | string | Name of the survey. | |
| entry_url_prod | No | string | SSL-enabled URL used to enter the live survey. Must contain ={transaction_id}. |
|
| entry_url_test | No | string | SSL-enabled URL used to enter the test survey. Must contain ={transaction_id}. |
|
| estimated_length_of_interview | No | integer | Estimated length to take the survey, in minutes. | |
| estimated_conversion_rate | No | integer | Estimated conversion rate. Range: 1 - 100 | |
| max_authorized_cpi | No | float | Maximum authorized CPI for the survey. This option may only be provided if your company has this feature enabled. | |
| cpi | No | float | Bid CPI for this survey -- (range: 0.75 - 20.00). This field is only enabled if your company has biddable cpi enabled. If you wish to have this feature enabled please contact an admin at TheoremReach. | |
| start_at | No | datetime | DateTime used to start the survey. ISO8601 format in UTC is expected. | |
| end_at | No | datetime | DateTime used to end the survey. ISO8601 format in UTC is expected. | |
| country_id | No | string | Country this survey should run in. | |
| survey_groups | No | array | List of survey IDs that, if already taken, should exclude the user from this survey. | |
| sub_buyer_id | No | string | The uid of a sub-buyer to associate with this survey. Must belong to the authenticated company. Pass null explicitly on update to disassociate. |
|
| quota_mode | No | string | nested | Quota mode for the survey. nested (traditional interlocked quotas) or independent (dimension-based quotas with auto-generated cells). Can only be changed in draft state. Warning: Switching modes deletes all existing quota configuration. |
Delete a Survey
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :delete,
url: 'https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}?enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}?enc={{ generated_request_hash }}"
-X DELETE
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
requests.delete(url, headers=headers)
const https = require('https');
const options = {
"method": "DELETE",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/surveys/{{ survey_id }}?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": { "message": "Successfully deleted the survey." }
}
Soft-deletes a survey on your account.
HTTP Request
DELETE https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
Start a Survey
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/start?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :post,
url: 'https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/start?enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/start?enc={{ generated_request_hash }}"
-X POST
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/start?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => '{}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/start?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {}
requests.post(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "POST",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/surveys/{{ survey_id }}/start?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": { "message": "Successfully started the survey." }
}
Starts a survey on your account.
HTTP Request
POST https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/start
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
Stop a Survey
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/pause?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :post,
url: 'https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/pause?enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/pause?enc={{ generated_request_hash }}"
-X POST
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/pause?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => '{}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/pause?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {}
requests.post(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "POST",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/surveys/{{ survey_id }}/pause?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": { "message": "Successfully stopped the survey." }
}
Stops a survey on your account.
HTTP Request
POST https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/pause
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
Complete a Survey
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/complete?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :post,
url: 'https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/complete?enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/complete?enc={{ generated_request_hash }}"
-X POST
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/complete?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => '{}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/complete?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {}
requests.post(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "POST",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/surveys/{{ survey_id }}/complete?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": { "message": "Successfully completed the survey." }
}
Completes a survey on your account.
HTTP Request
POST https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/complete
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
Survey Transactions
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/transactions?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :post,
url: 'https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/transactions?enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/transactions?enc={{ generated_request_hash }}"
-X POST
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/transactions?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => '{}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/transactions?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {}
requests.post(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "POST",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/surveys/{{ survey_id }}/transactions?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": [
{
"id": "78ad7494-1d2d-4721-b683-bdbe0c791b8f",
"respondent_id": "f19583f7-9c47-4801-82d5-abe435043bf3",
"survey_id": "d8f68021-efda-4147-b259-c59f9f66784c",
"quota_id": "894585ad-fb9e-46f1-8750-b3cff041ed5d",
"invoice_id": 13,
"start_time": "2019-12-17T21:27:45Z",
"end_time": "2020-01-01T21:27:45Z",
"state": "attempted",
"attempt_cost": 0.0,
"complete_cost": 0.0,
"total_cost": 0.0,
"duration_in_seconds": 0,
"mode": "live"
},
...
],
"meta": {
"warnings": []
}
}
Lists a survey's transactions.
HTTP Request
POST https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/transactions
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
Screening Questions
List Screening Questions
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions?purpose={{ purpose }}&enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :get,
url: 'https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions?purpose={{ purpose }}&enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions?purpose={{ purpose }}&enc={{ generated_request_hash }}"
-X GET
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions?purpose={{ purpose }}&enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions?purpose={{ purpose }}&enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
requests.get(url, headers=headers)
const https = require('https');
const options = {
"method": "GET",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/surveys/{{ survey_id }}/screening_questions?purpose={{ purpose }}&enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": [
{
"id": "a1b9e78e-6bcb-46b8-9b91-d4e482b42458",
"sort_order": 1,
"question_type": "multi_select",
"display_text": "What is your occupation?",
"shuffle_type": "shuffle",
"purpose": "survey_targeting",
"locked": false,
"options": []
},
{
"id": "bca5d9d3-f110-4c9c-b8a3-4df3978744aa",
"sort_order": 1,
"question_type": "multi_select",
"display_text": "What is your occupation?",
"shuffle_type": "no_shuffle",
"purpose": "quota_targeting",
"locked": true,
"options": []
},
...
]
"meta": {
"warnings": []
}
}
Retrieves a list of all screening questions for the survey.
HTTP Request
GET https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| purpose | No | None | Filter by question purpose. Valid values: survey_targeting, quota_targeting. custom is also accepted as an alias for survey_targeting. When omitted, returns both. |
| enc | Yes | None | Generated request hash |
List Company Screening Questions
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/screening_questions?survey_id={{ survey_id }}&purpose={{ purpose }}&query={{ query }}&page={{ page }}&per_page={{ per_page }}&enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :get,
url: 'https://surveys.theoremreach.com/api/external/v1/screening_questions?survey_id={{ survey_id }}&purpose={{ purpose }}&query={{ query }}&page={{ page }}&per_page={{ per_page }}&enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/screening_questions?survey_id={{ survey_id }}&purpose={{ purpose }}&query={{ query }}&page={{ page }}&per_page={{ per_page }}&enc={{ generated_request_hash }}"
-X GET
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/screening_questions?survey_id={{ survey_id }}&purpose={{ purpose }}&query={{ query }}&page={{ page }}&per_page={{ per_page }}&enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/screening_questions?survey_id={{ survey_id }}&purpose={{ purpose }}&query={{ query }}&page={{ page }}&per_page={{ per_page }}&enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
requests.get(url, headers=headers)
const https = require('https');
const options = {
"method": "GET",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/screening_questions?survey_id={{ survey_id }}&purpose={{ purpose }}&query={{ query }}&page={{ page }}&per_page={{ per_page }}&enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": [
{
"id": "a1b9e78e-6bcb-46b8-9b91-d4e482b42458",
"sort_order": 1,
"question_type": "multi_select",
"display_text": "What is your occupation?",
"shuffle_type": "shuffle",
"purpose": "survey_targeting",
"locked": false,
"options": []
},
...
]
"meta": {
"page": 1,
"per_page": 25,
"total": 42,
"warnings": []
}
}
Returns screening questions across all surveys belonging to the authenticated company. Useful for discovering existing questions that can be reused on other surveys via the "Create from Question" endpoint.
HTTP Request
GET https://surveys.theoremreach.com/api/external/v1/screening_questions
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| survey_id | No | None | Filter to a specific survey's screening questions. The survey must belong to the authenticated company. |
| purpose | No | None | Filter by question purpose. Valid values: survey_targeting, quota_targeting. custom is also accepted. When omitted, returns both. |
| query | No | None | Search screening questions by display_text. Minimum 3 characters. Returns questions where display_text matches the query (case-insensitive substring match). |
| page | No | 1 | Page number (1-indexed). |
| per_page | No | 25 | Results per page. Maximum: 100. |
| enc | Yes | None | Generated request hash |
Create a New Screening Question
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {:question_type=>"single_select", :display_text=>"What is your occupation?", :sort_order=>1, :shuffle_type=>"no_shuffle", :purpose=>"survey_targeting"}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :post,
url: 'https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions?enc={{ generated_request_hash }}',
payload: {:question_type=>"single_select", :display_text=>"What is your occupation?", :sort_order=>1, :shuffle_type=>"no_shuffle", :purpose=>"survey_targeting"},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions?enc={{ generated_request_hash }}"
-X POST
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
-H "Content-Type: application/json"
--data '{"question_type":"single_select","display_text":"What is your occupation?","sort_order":1,"shuffle_type":"no_shuffle","purpose":"survey_targeting"}'
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => '{"question_type":"single_select","display_text":"What is your occupation?","sort_order":1,"shuffle_type":"no_shuffle","purpose":"survey_targeting"}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {"question_type":"single_select","display_text":"What is your occupation?","sort_order":1,"shuffle_type":"no_shuffle","purpose":"survey_targeting"}
requests.post(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "POST",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/surveys/{{ survey_id }}/screening_questions?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {"question_type":"single_select","display_text":"What is your occupation?","sort_order":1,"shuffle_type":"no_shuffle","purpose":"survey_targeting"};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": {
"id": "2c438d28-5a1e-45e3-825d-e1dc826ee50a",
"sort_order": 1,
"question_type": "single_select",
"display_text": "What is your occupation?",
"shuffle_type": "no_shuffle",
"purpose": "survey_targeting",
"locked": false,
"options": []
},
"meta": {
"warnings": []
}
}
Creates a new screening question for the survey.
HTTP Request
POST https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
JSON Fields
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
| question_type | Yes | string | Question's type. single_select or multi_select |
|
| display_text | No | string | Question's display label | |
| sort_order | No | integer | The order this screening question should be displayed in. | |
| shuffle_type | No | string | Shuffle type for this question's options. shuffle or no_shuffle |
|
| purpose | No | string | survey_targeting | The question purpose. survey_targeting for survey-level screening questions, quota_targeting for quota-level targeting questions. custom is also accepted as an alias for survey_targeting. |
Question Purpose
Screening questions have two purposes that determine how they are used:
Survey Targeting (purpose: "survey_targeting")
Survey targeting screening questions filter respondents at the survey level. Each option has a pass/fail state (pass_question on the option). Respondents whose answers match a "fail" option are screened out of the survey entirely.
Typical flow:
- Create a screening question with
purpose: "survey_targeting"(default) - Add options via the screening question options endpoint
- Set
pass_question: trueon acceptable options,pass_question: falseon others - The question is automatically active for survey-level screening once the survey has been launched
Quota-Level Targeting (purpose: "quota_targeting")
Quota targeting questions filter respondents into specific quotas without screening them out of the survey. All respondents pass the question at the survey level — the question is only used to determine which quota a respondent qualifies for.
Typical flow:
- Create a screening question with
purpose: "quota_targeting" - Add options via the screening question options endpoint
- Create or update a quota, referencing the question in the
questionsarray (see example below) - The selected options determine which respondents qualify for that quota
- The targeting assignment is "pending" until the survey has been launched (see
pending_screening_questionsin quota responses)
Example quota request with screening question targeting:
{
"questions": [
{
"screening_question_uid": "<question_uid>",
"screening_question_option_uids": ["<option_uid_1>", "<option_uid_2>"]
}
]
}
Key differences:
| Aspect | survey_targeting |
quota_targeting |
|---|---|---|
| Survey-level screening | Yes — pass_question: false options reject respondents |
No — all respondents pass |
| Quota-level targeting | Optional — can also be attached to quotas | Primary use case |
Default pass_question on new options |
true (accept) |
true (accept) |
| Managed via | Same CRUD endpoints | Same CRUD endpoints |
Create a Screening Question from a Targeting Question
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions/create_from_targeting_question?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {:question_id=>"f2c062da-9f63-4602-88a8-e8525a4f1443"}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :post,
url: 'https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions/create_from_targeting_question?enc={{ generated_request_hash }}',
payload: {:question_id=>"f2c062da-9f63-4602-88a8-e8525a4f1443"},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions/create_from_targeting_question?enc={{ generated_request_hash }}"
-X POST
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
-H "Content-Type: application/json"
--data '{"question_id":"f2c062da-9f63-4602-88a8-e8525a4f1443"}'
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions/create_from_targeting_question?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => '{"question_id":"f2c062da-9f63-4602-88a8-e8525a4f1443"}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions/create_from_targeting_question?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {"question_id":"f2c062da-9f63-4602-88a8-e8525a4f1443"}
requests.post(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "POST",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/surveys/{{ survey_id }}/screening_questions/create_from_targeting_question?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {"question_id":"f2c062da-9f63-4602-88a8-e8525a4f1443"};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": {
"id": "7d3f1a2b-4c5e-6f7a-8b9c-0d1e2f3a4b5c",
"sort_order": 1,
"question_type": "single_select",
"display_text": "What is your age?",
"shuffle_type": "no_shuffle",
"purpose": "survey_targeting",
"locked": true,
"options": [
{
"id": "e1f2a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
"value": "18-24",
"sort_order": 1,
"pass_question": true,
"locked": true
},
{
"id": "a2b3c4d5-e6f7-8a9b-0c1d-2e3f4a5b6c7d",
"value": "25-34",
"sort_order": 2,
"pass_question": true,
"locked": true
}
]
},
"meta": {
"warnings": []
}
}
Creates a screening question from an existing targeting question (from the Questions endpoint). The question text and answer options are inherited and cannot be modified — only the pass/fail state of each option can be edited. This is useful when you want to screen on a standard targeting attribute without manually recreating its text and options.
HTTP Request
POST https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions/create_from_targeting_question
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
JSON Fields
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
| question_id | Yes | string | The question ID from the Questions endpoint (the same ID used in quota targeting). |
Create a Screening Question from Another Survey's Question
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions/create_from_question?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {:screening_question_uid=>"a1b9e78e-6bcb-46b8-9b91-d4e482b42458", :purpose=>"survey_targeting"}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :post,
url: 'https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions/create_from_question?enc={{ generated_request_hash }}',
payload: {:screening_question_uid=>"a1b9e78e-6bcb-46b8-9b91-d4e482b42458", :purpose=>"survey_targeting"},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions/create_from_question?enc={{ generated_request_hash }}"
-X POST
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
-H "Content-Type: application/json"
--data '{"screening_question_uid":"a1b9e78e-6bcb-46b8-9b91-d4e482b42458","purpose":"survey_targeting"}'
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions/create_from_question?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => '{"screening_question_uid":"a1b9e78e-6bcb-46b8-9b91-d4e482b42458","purpose":"survey_targeting"}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions/create_from_question?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {"screening_question_uid":"a1b9e78e-6bcb-46b8-9b91-d4e482b42458","purpose":"survey_targeting"}
requests.post(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "POST",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/surveys/{{ survey_id }}/screening_questions/create_from_question?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {"screening_question_uid":"a1b9e78e-6bcb-46b8-9b91-d4e482b42458","purpose":"survey_targeting"};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": {
"id": "c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f",
"sort_order": 1,
"question_type": "multi_select",
"display_text": "What is your occupation?",
"shuffle_type": "shuffle",
"purpose": "survey_targeting",
"locked": true,
"options": [
{
"id": "f1a2b3c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c",
"value": "Account Executive",
"sort_order": 1,
"pass_question": true,
"locked": true
},
{
"id": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
"value": "Engineer",
"sort_order": 2,
"pass_question": true,
"locked": true
}
]
},
"meta": {
"warnings": []
}
}
Creates a screening question by cloning an existing screening question from another survey belonging to the same company. The question text, options, and pass/fail defaults are copied from the source question. The cloned question is locked — text and options cannot be modified. This is useful for reusing screening questions across surveys without recreating them from scratch.
HTTP Request
POST https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/screening_questions/create_from_question
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
JSON Fields
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
| screening_question_uid | Yes | string | The uid of a screening question from another survey. The source survey must belong to the same company as the target survey. | |
| purpose | No | string | survey_targeting | The question purpose for the clone. survey_targeting for survey-level screening, quota_targeting for quota-level targeting. custom is also accepted. When omitted, defaults to survey_targeting. This allows cross-purpose cloning (e.g., cloning a quota_targeting source as a survey_targeting question). |
Update a Screening Question
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Put.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {:question_type=>"single_select", :display_text=>"What is your household income range?", :sort_order=>1, :shuffle_type=>"no_shuffle"}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :put,
url: 'https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}?enc={{ generated_request_hash }}',
payload: {:question_type=>"single_select", :display_text=>"What is your household income range?", :sort_order=>1, :shuffle_type=>"no_shuffle"},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}?enc={{ generated_request_hash }}"
-X PUT
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
-H "Content-Type: application/json"
--data '{"question_type":"single_select","display_text":"What is your household income range?","sort_order":1,"shuffle_type":"no_shuffle"}'
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => '{"question_type":"single_select","display_text":"What is your household income range?","sort_order":1,"shuffle_type":"no_shuffle"}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {"question_type":"single_select","display_text":"What is your household income range?","sort_order":1,"shuffle_type":"no_shuffle"}
requests.put(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "PUT",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/screening_questions/{{ screening_question_id }}?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {"question_type":"single_select","display_text":"What is your household income range?","sort_order":1,"shuffle_type":"no_shuffle"};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": {
"id": "2c438d28-5a1e-45e3-825d-e1dc826ee50a",
"sort_order": 1,
"question_type": "single_select",
"display_text": "What is your household income range?",
"shuffle_type": "no_shuffle",
"purpose": "survey_targeting",
"locked": false,
"options": []
},
"meta": {
"warnings": []
}
}
Updates a screening question with the provided attributes.
HTTP Request
PUT https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
JSON Fields
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
| question_type | No | string | Question's type. single_select or multi_select |
|
| display_text | No | string | Question's display label | |
| sort_order | No | integer | The order this screening question should be displayed in. | |
| shuffle_type | No | string | Shuffle type for this question's options. shuffle or no_shuffle |
Delete a Screening Question
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :delete,
url: 'https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}?enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}?enc={{ generated_request_hash }}"
-X DELETE
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
requests.delete(url, headers=headers)
const https = require('https');
const options = {
"method": "DELETE",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/screening_questions/{{ screening_question_id }}?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": { "message": "Successfully deleted the question and its options." }
}
Deletes a screening question and its options.
HTTP Request
DELETE https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
Screening Question Response Fields
| Field | Type | Description |
|---|---|---|
| id | string | The screening question's uid. |
| sort_order | integer | Display order of the question. |
| question_type | string | single_select or multi_select. |
| display_text | string | The question's display label. |
| shuffle_type | string | shuffle or no_shuffle. |
| purpose | string | survey_targeting (survey-level screening) or quota_targeting (quota-level targeting). Legacy value custom is equivalent to survey_targeting. |
| locked | boolean | true if the question was created from a targeting question, shared with other surveys, or is a clone. Text and options cannot be modified on locked questions — only pass_question on options can be changed. |
| options | array | The question's options (see Screening Question Options). |
Screening Question Options
List Question Options
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :get,
url: 'https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options?enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options?enc={{ generated_request_hash }}"
-X GET
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
requests.get(url, headers=headers)
const https = require('https');
const options = {
"method": "GET",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": [
{
"id": "85abc6bf-5c93-4d95-b3a6-14b4866b0fff",
"value": "Account Executive",
"sort_order": 1,
"pass_question": true,
"locked": false
},
{
"id": "978755a8-71f9-4ffc-b96e-2645af9b3403",
"value": "Engineer",
"sort_order": 2,
"pass_question": true,
"locked": false
},
{
"id": "91913910-1419-471e-bcd2-dcc74df59f71",
"value": "Astronaut",
"sort_order": 3,
"pass_question": true,
"locked": false
}
],
"meta": {
"warnings": []
}
}
Retrieves a list of all options for the screening question.
HTTP Request
GET https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
Create a New Question Option
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {:value=>"Astronaut", :sort_order=>1, :pass_question=>true}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :post,
url: 'https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options?enc={{ generated_request_hash }}',
payload: {:value=>"Astronaut", :sort_order=>1, :pass_question=>true},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options?enc={{ generated_request_hash }}"
-X POST
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
-H "Content-Type: application/json"
--data '{"value":"Astronaut","sort_order":1,"pass_question":true}'
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => '{"value":"Astronaut","sort_order":1,"pass_question":true}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {"value":"Astronaut","sort_order":1,"pass_question":true}
requests.post(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "POST",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {"value":"Astronaut","sort_order":1,"pass_question":true};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": {
"id": "24fd724b-1724-4202-8124-4b7b987a6e7f",
"value": "Astronaut",
"sort_order": 1,
"pass_question": true,
"locked": false
},
"meta": {
"warnings": []
}
}
Creates a new option for the screening question.
HTTP Request
POST https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
JSON Fields
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
| value | No | string | The value for the question option. | |
| sort_order | No | integer | options length + 1 | The order this screening question option should be displayed in. |
| pass_question | No | boolean | false | Is this an acceptable answer to the screening question? |
Update a Question Option
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/screening_question_options/{{ screening_question_option_id }}?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Put.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {:value=>"Account Executive", :sort_order=>1, :pass_question=>"No Example Provided"}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :put,
url: 'https://surveys.theoremreach.com/api/external/v1/screening_question_options/{{ screening_question_option_id }}?enc={{ generated_request_hash }}',
payload: {:value=>"Account Executive", :sort_order=>1, :pass_question=>"No Example Provided"},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/screening_question_options/{{ screening_question_option_id }}?enc={{ generated_request_hash }}"
-X PUT
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
-H "Content-Type: application/json"
--data '{"value":"Account Executive","sort_order":1,"pass_question":"No Example Provided"}'
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/screening_question_options/{{ screening_question_option_id }}?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => '{"value":"Account Executive","sort_order":1,"pass_question":"No Example Provided"}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/screening_question_options/{{ screening_question_option_id }}?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {"value":"Account Executive","sort_order":1,"pass_question":"No Example Provided"}
requests.put(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "PUT",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/screening_question_options/{{ screening_question_option_id }}?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {"value":"Account Executive","sort_order":1,"pass_question":"No Example Provided"};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": {
"id": "24fd724b-1724-4202-8124-4b7b987a6e7f",
"value": "Account Executive",
"sort_order": 1,
"pass_question": false,
"locked": false
},
"meta": {
"warnings": []
}
}
Updates a screening question option with the provided attributes.
HTTP Request
PUT https://surveys.theoremreach.com/api/external/v1/screening_question_options/{{ screening_question_option_id }}
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
JSON Fields
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
| value | No | string | The value for the question option. | |
| sort_order | No | integer | options length + 1 | The order this screening question option should be displayed in. |
| pass_question | No | boolean | false | Is this an acceptable answer to the screening question? |
Delete a Question Option
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/screening_question_options/{{ screening_question_option_id }}?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :delete,
url: 'https://surveys.theoremreach.com/api/external/v1/screening_question_options/{{ screening_question_option_id }}?enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/screening_question_options/{{ screening_question_option_id }}?enc={{ generated_request_hash }}"
-X DELETE
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/screening_question_options/{{ screening_question_option_id }}?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/screening_question_options/{{ screening_question_option_id }}?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
requests.delete(url, headers=headers)
const https = require('https');
const options = {
"method": "DELETE",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/screening_question_options/{{ screening_question_option_id }}?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": { "message": "Successfully deleted the question option." }
}
Deletes a screening question option.
HTTP Request
DELETE https://surveys.theoremreach.com/api/external/v1/screening_question_options/{{ screening_question_option_id }}
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
Quotas
Quota behavior differs based on the survey's quota_mode. Surveys default to nested mode. See the Surveys section for setting quota_mode.
- Nested mode (default): Quotas are fully specified cells with questions/answers and per-cell metrics.
- Independent mode: Quotas are dimension-based with auto-generated cells. Each dimension has independent target/max completes.
List Quotas
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/quotas?mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :get,
url: 'https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/quotas?mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/quotas?mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}"
-X GET
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/quotas?mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/quotas?mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
requests.get(url, headers=headers)
const https = require('https');
const options = {
"method": "GET",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/surveys/{{ survey_id }}/quotas?mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Nested mode response:
{
"data": [
{
"id": "63d6dcf8-7372-4956-9c27-d060b879c848",
"name": "New Quotas",
"state": "active",
"questions": [
{
"question_id": "1",
"answer_ids": ["20", "21", "22", "23", "24", "25", "26", "27"]
},
{
"question_id": "2",
"answer_ids": ["100", "101"]
},
{
"question_id": "3",
"postal_codes": ["23185", "90210"]
}
],
"pending_screening_questions": [],
"metrics": {
"target_completes": 250,
"remaining_completes": 250,
"completes_count": 0,
"effective_cpi": 0.0,
"attempts_count": 0,
"attempts_in_dollars": 0.0,
"completes_in_dollars": 0.0,
"conversion_rate": 0.0
}
}
...
]
"meta": {
"warnings": []
}
}
Independent mode response:
{
"data": {
"quota_mode": "independent",
"quota_dimensions": [
{
"question_id": "q_age",
"values": [
{
"answer_ids": ["ans_18_24"],
"target_completes": 200,
"max_completes": 220,
"filled_completes": 85,
"remaining_completes": 135,
"state": "active"
},
{
"answer_ids": ["ans_25_30"],
"target_completes": 800,
"max_completes": 850,
"filled_completes": 312,
"remaining_completes": 538,
"state": "active"
}
]
},
{
"question_id": "q_gender",
"values": [
{
"answer_ids": ["ans_male"],
"target_completes": 500,
"max_completes": 535,
"filled_completes": 198,
"remaining_completes": 337,
"state": "active"
},
{
"answer_ids": ["ans_female"],
"target_completes": 500,
"max_completes": 535,
"filled_completes": 199,
"remaining_completes": 336,
"state": "active"
}
]
}
]
},
"meta": {
"warnings": []
}
}
Retrieves a list of all quotas for the survey. The response format depends on the survey's quota_mode.
HTTP Request
GET https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/quotas
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| mapping_partner_id | No | TheoremReach | Mapping Partner ID |
| enc | Yes | None | Generated request hash |
Nested Mode Response Fields
| Field | Type | Description |
|---|---|---|
| id | string | The quota's uid. |
| name | string | Name of the quota. |
| state | string | active or inactive. |
| questions | array | Targeting questions assigned to this quota. Each entry contains question_id and answer_ids (or postal_codes for postal-type questions). |
| pending_screening_questions | array | Screening question targeting assignments that are pending resolution. Empty array when all assignments are resolved. Each entry contains screening_question_uid and screening_question_option_uids. |
| metrics | object | Quota metrics (target_completes, remaining_completes, completes_count, etc.). |
Independent Mode Response Fields
| Field | Type | Description |
|---|---|---|
| quota_mode | string | Always "independent". |
| quota_dimensions | array | Array of dimension objects. |
| quota_dimensions[].question_id | string | The targeting question this dimension is based on. |
| quota_dimensions[].values | array | Array of dimension value objects. |
| quota_dimensions[].values[].answer_ids | array of strings | The answer IDs for this dimension value. |
| quota_dimensions[].values[].target_completes | integer | Target (minimum) number of completes for this value. |
| quota_dimensions[].values[].max_completes | integer | Maximum completes cap. Defaults to target_completes if not set. |
| quota_dimensions[].values[].filled_completes | integer | Current number of completes for this value. |
| quota_dimensions[].values[].remaining_completes | integer | Remaining completes until max is reached (max_completes - filled_completes). |
| quota_dimensions[].values[].state | string | active or inactive. |
Create a New Quota
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/quotas?mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {:name=>"New Quota", :target_completes=>250, :state=>"active", :questions=>[{:question_id=>"2", :answer_ids=>["100", "101"]}, {:question_id=>"3", :postal_codes=>["90210", "90211", "90212", "53719"]}]}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :post,
url: 'https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/quotas?mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}',
payload: {:name=>"New Quota", :target_completes=>250, :state=>"active", :questions=>[{:question_id=>"2", :answer_ids=>["100", "101"]}, {:question_id=>"3", :postal_codes=>["90210", "90211", "90212", "53719"]}]},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/quotas?mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}"
-X POST
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
-H "Content-Type: application/json"
--data '{"name":"New Quota","target_completes":250,"state":"active","questions":[{"question_id":"2","answer_ids":["100","101"]},{"question_id":"3","postal_codes":["90210","90211","90212","53719"]}]}'
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/quotas?mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => '{"name":"New Quota","target_completes":250,"state":"active","questions":[{"question_id":"2","answer_ids":["100","101"]},{"question_id":"3","postal_codes":["90210","90211","90212","53719"]}]}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/quotas?mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {"name":"New Quota","target_completes":250,"state":"active","questions":[{"question_id":"2","answer_ids":["100","101"]},{"question_id":"3","postal_codes":["90210","90211","90212","53719"]}]}
requests.post(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "POST",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/surveys/{{ survey_id }}/quotas?mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {"name":"New Quota","target_completes":250,"state":"active","questions":[{"question_id":"2","answer_ids":["100","101"]},{"question_id":"3","postal_codes":["90210","90211","90212","53719"]}]};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Nested mode response:
{
"data": {
"id": "6ed2848d-0f32-4fd6-847b-90e2da0c2cc8",
"name": "New Quota",
"state": "active",
"questions": [
{ "question_id": "2", "answer_ids": ["100", "101"] },
{ "question_id": "3", "postal_codes": ["90210", "90211", "90212", "53719"] }
],
"pending_screening_questions": [],
"metrics": {
"target_completes": 250,
"remaining_completes": 250,
"completes_count": 0,
"effective_cpi": 0.0,
"attempts_count": 0,
"attempts_in_dollars": 0.0,
"completes_in_dollars": 0.0,
"conversion_rate": 0.0
}
},
"meta": {
"warnings": []
}
}
Creates a new quota for the survey.
Question information will be automatically appended to the entry URL with the following format: "&mapping_partner_question_id=comma_separated_answer_ids"
HTTP Request
POST https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/quotas
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| mapping_partner_id | No | TheoremReach | Mapping Partner ID |
| include_all | No | None | When true, allows assigning non-standard targeting questions (from the include_all=true questions catalog) to quota targeting. Only applies to nested mode quotas. |
| enc | Yes | None | Generated request hash |
JSON Fields
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
| name | No | string | null | Name for the quota. |
| target_completes | No | integer | 25 | Target survey completes for the quota. |
| state | No | string | active | State the quota should be created in. active or inactive |
| questions | No | array | [] | Array of hashes containing a question_id and answer_ids or postal_codes, or a screening_question_uid and screening_question_option_uids. Question IDs can be queried for here, Answer IDs here. If the question's type is postal, provide postal codes as an array of strings via postal_codes. |
Screening Question Targeting (Nested Mode)
In addition to the standard { question_id, answer_ids } format, the questions array also accepts screening question references:
| Field | Required | Type | Description |
|---|---|---|---|
| screening_question_uid | Yes | string | The uid of a screening question on this survey. Cannot be combined with question_id in the same entry. |
| screening_question_option_uids | Yes | array of strings | The uids of screening question options to target. |
Example request with screening question targeting:
{
"questions": [
{ "question_id": "q_age", "answer_ids": ["ans_25_30"] },
{ "screening_question_uid": "question-uid-123", "screening_question_option_uids": ["option-uid-456", "option-uid-789"] }
]
}
Example read response with a pending screening question assignment:
{
"data": {
"id": "6ed2848d-0f32-4fd6-847b-90e2da0c2cc8",
"questions": [
{ "question_id": "q_age", "answer_ids": ["ans_25_30"] }
],
"pending_screening_questions": [
{
"screening_question_uid": "question-uid-123",
"screening_question_option_uids": ["option-uid-456", "option-uid-789"]
}
]
}
}
Independent Mode Request Format
When a survey has quota_mode: "independent", use the quota_dimensions format instead of individual quota cells:
Independent mode create/update request:
{
"quota_dimensions": [
{
"question_id": "q_age",
"values": [
{
"answer_ids": ["ans_18_24"],
"target_completes": 200,
"max_completes": 220
},
{
"answer_ids": ["ans_25_30"],
"target_completes": 800,
"max_completes": 850
}
]
},
{
"question_id": "q_gender",
"values": [
{
"answer_ids": ["ans_male"],
"target_completes": 500,
"max_completes": 535
},
{
"answer_ids": ["ans_female"],
"target_completes": 500,
"max_completes": 535
}
]
}
]
}
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
| quota_dimensions[].question_id | Yes | string | None | Targeting question for this dimension. |
| quota_dimensions[].values[].answer_ids | Yes | array of strings | None | Answer IDs for this value. |
| quota_dimensions[].values[].target_completes | Yes | integer | None | Target (minimum) completes. Must be > 0. |
| quota_dimensions[].values[].max_completes | No | integer | Same as target_completes |
Maximum completes cap. Must be >= target_completes. |
Update a Quota
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/quotas/{{ quota_id }}?mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Put.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {:name=>"Updated Quota Name", :target_completes=>"100", :state=>"inactive", :questions=>[{:question_id=>"2", :answer_ids=>["100", "101"]}, {:question_id=>"3", :postal_codes=>["10001", "10002", "10003", "10004"]}]}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :put,
url: 'https://surveys.theoremreach.com/api/external/v1/quotas/{{ quota_id }}?mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}',
payload: {:name=>"Updated Quota Name", :target_completes=>"100", :state=>"inactive", :questions=>[{:question_id=>"2", :answer_ids=>["100", "101"]}, {:question_id=>"3", :postal_codes=>["10001", "10002", "10003", "10004"]}]},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/quotas/{{ quota_id }}?mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}"
-X PUT
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
-H "Content-Type: application/json"
--data '{"name":"Updated Quota Name","target_completes":"100","state":"inactive","questions":[{"question_id":"2","answer_ids":["100","101"]},{"question_id":"3","postal_codes":["10001","10002","10003","10004"]}]}'
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/quotas/{{ quota_id }}?mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => '{"name":"Updated Quota Name","target_completes":"100","state":"inactive","questions":[{"question_id":"2","answer_ids":["100","101"]},{"question_id":"3","postal_codes":["10001","10002","10003","10004"]}]}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/quotas/{{ quota_id }}?mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {"name":"Updated Quota Name","target_completes":"100","state":"inactive","questions":[{"question_id":"2","answer_ids":["100","101"]},{"question_id":"3","postal_codes":["10001","10002","10003","10004"]}]}
requests.put(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "PUT",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/quotas/{{ quota_id }}?mapping_partner_id={{ mapping_partner_id }}&include_all={{ include_all }}&enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {"name":"Updated Quota Name","target_completes":"100","state":"inactive","questions":[{"question_id":"2","answer_ids":["100","101"]},{"question_id":"3","postal_codes":["10001","10002","10003","10004"]}]};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Nested mode response:
{
"data": {
"id": "6ed2848d-0f32-4fd6-847b-90e2da0c2cc8",
"name": "Updated Quota Name",
"state": "inactive",
"questions": [
{ "question_id": "2", "answer_ids": ["100", "101"] },
{ "question_id": "3", "postal_codes": ["10001", "10002", "10003", "10004"] }
],
"pending_screening_questions": [],
"metrics": {
"target_completes": 100,
"remaining_completes": 100,
"completes_count": 0,
"effective_cpi": 0.0,
"attempts_count": 0,
"attempts_in_dollars": 0.0,
"completes_in_dollars": 0.0,
"conversion_rate": 0.0
}
},
"meta": {
"warnings": []
}
}
Updates a quota with the provided attributes.
HTTP Request
PUT https://surveys.theoremreach.com/api/external/v1/quotas/{{ quota_id }}
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| mapping_partner_id | No | TheoremReach | Mapping Partner ID |
| include_all | No | None | When true, allows assigning non-standard targeting questions (from the include_all=true questions catalog) to quota targeting. Only applies to nested mode quotas. |
| enc | Yes | None | Generated request hash |
JSON Fields
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
| name | No | string | null | Name for the quota. |
| target_completes | No | integer | 25 | Target survey completes for the quota. |
| state | No | string | active | State the quota should be created in. active or inactive |
| questions | No | array | [] | Array of hashes containing a question_id and answer_ids or postal_codes, or a screening_question_uid and screening_question_option_uids. Question IDs can be queried for here, Answer IDs here. If the question's type is postal, provide postal codes as an array of strings via postal_codes. |
Delete a Quota
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/quotas/{{ quota_id }}?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :delete,
url: 'https://surveys.theoremreach.com/api/external/v1/quotas/{{ quota_id }}?enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/quotas/{{ quota_id }}?enc={{ generated_request_hash }}"
-X DELETE
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/quotas/{{ quota_id }}?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/quotas/{{ quota_id }}?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
requests.delete(url, headers=headers)
const https = require('https');
const options = {
"method": "DELETE",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/quotas/{{ quota_id }}?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": { "message": "Quota successfully deleted." }
}
Deletes a quota.
HTTP Request
DELETE https://surveys.theoremreach.com/api/external/v1/quotas/{{ quota_id }}
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
Quota Feasibility
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/quotas/feasibility?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {:target_completes=>250, :questions=>[{:question_id=>"2", :answer_ids=>["100", "101"]}, {:question_id=>"3", :postal_codes=>["90210", "90211", "90212", "53719"]}]}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :post,
url: 'https://surveys.theoremreach.com/api/external/v1/quotas/feasibility?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}',
payload: {:target_completes=>250, :questions=>[{:question_id=>"2", :answer_ids=>["100", "101"]}, {:question_id=>"3", :postal_codes=>["90210", "90211", "90212", "53719"]}]},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/quotas/feasibility?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}"
-X POST
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
-H "Content-Type: application/json"
--data '{"target_completes":250,"questions":[{"question_id":"2","answer_ids":["100","101"]},{"question_id":"3","postal_codes":["90210","90211","90212","53719"]}]}'
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/quotas/feasibility?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => '{"target_completes":250,"questions":[{"question_id":"2","answer_ids":["100","101"]},{"question_id":"3","postal_codes":["90210","90211","90212","53719"]}]}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/quotas/feasibility?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {"target_completes":250,"questions":[{"question_id":"2","answer_ids":["100","101"]},{"question_id":"3","postal_codes":["90210","90211","90212","53719"]}]}
requests.post(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "POST",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/quotas/feasibility?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {"target_completes":250,"questions":[{"question_id":"2","answer_ids":["100","101"]},{"question_id":"3","postal_codes":["90210","90211","90212","53719"]}]};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": {
"feasibility_in_days": 30
},
"meta": {
"warnings": []
}
}
Calculate the feasibility of a quota based on the requested target_completes, and the provided quota question/answer (questions field) constraints. Feasibility results are return in number of days.
HTTP Request
POST https://surveys.theoremreach.com/api/external/v1/quotas/feasibility
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| country_id | Yes | None | Country ID to check the feasibility against. |
| mapping_partner_id | No | TheoremReach | Mapping Partner ID |
| enc | Yes | None | Generated request hash |
JSON Fields
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
| target_completes | No | integer | 25 | Target survey completes for the quota. |
| questions | No | array | [] | Array of hashes containing a question_id and answer_ids or postal_codes. Question IDs can be queried for here, Answer IDs here. If the question's type is postal, provide postal codes as an array of strings via postal_codes. |
Sub-Buyers
List Sub-Buyers
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/sub_buyers?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :get,
url: 'https://surveys.theoremreach.com/api/external/v1/sub_buyers?enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/sub_buyers?enc={{ generated_request_hash }}"
-X GET
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/sub_buyers?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/sub_buyers?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
requests.get(url, headers=headers)
const https = require('https');
const options = {
"method": "GET",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/sub_buyers?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": [
{
"id": "b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c",
"name": "West Coast Division",
"survey_count": 42,
"created_at": "2026-02-27T12:00:00Z"
},
{
"id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
"name": "East Coast Division",
"survey_count": 18,
"created_at": "2026-01-15T09:30:00Z"
}
],
"meta": {
"warnings": []
}
}
Retrieves a list of all sub-buyers belonging to the authenticated company.
HTTP Request
GET https://surveys.theoremreach.com/api/external/v1/sub_buyers
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
Get Sub-Buyer Details
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/sub_buyers/{{ sub_buyer_id }}?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :get,
url: 'https://surveys.theoremreach.com/api/external/v1/sub_buyers/{{ sub_buyer_id }}?enc={{ generated_request_hash }}',
payload: {},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/sub_buyers/{{ sub_buyer_id }}?enc={{ generated_request_hash }}"
-X GET
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/sub_buyers/{{ sub_buyer_id }}?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/sub_buyers/{{ sub_buyer_id }}?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
requests.get(url, headers=headers)
const https = require('https');
const options = {
"method": "GET",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/sub_buyers/{{ sub_buyer_id }}?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": {
"id": "b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c",
"name": "West Coast Division",
"survey_count": 42,
"created_at": "2026-02-27T12:00:00Z"
},
"meta": {
"warnings": []
}
}
Retrieves details for a single sub-buyer by uid, including active survey count.
HTTP Request
GET https://surveys.theoremreach.com/api/external/v1/sub_buyers/{{ sub_buyer_id }}
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
Create a Sub-Buyer
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/sub_buyers?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {:name=>"West Coast Division"}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :post,
url: 'https://surveys.theoremreach.com/api/external/v1/sub_buyers?enc={{ generated_request_hash }}',
payload: {:name=>"West Coast Division"},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/sub_buyers?enc={{ generated_request_hash }}"
-X POST
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
-H "Content-Type: application/json"
--data '{"name":"West Coast Division"}'
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/sub_buyers?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => '{"name":"West Coast Division"}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/sub_buyers?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {"name":"West Coast Division"}
requests.post(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "POST",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/sub_buyers?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {"name":"West Coast Division"};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": {
"id": "b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c",
"name": "West Coast Division",
"survey_count": 0,
"created_at": "2026-02-27T12:00:00Z"
},
"meta": {
"warnings": []
}
}
Creates a new sub-buyer for the authenticated company.
HTTP Request
POST https://surveys.theoremreach.com/api/external/v1/sub_buyers
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
JSON Fields
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
| name | Yes | string | Name of the sub-buyer. Must be unique per company (case-insensitive). |
Update a Sub-Buyer
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/sub_buyers/{{ sub_buyer_id }}?enc={{ generated_request_hash }}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Put.new(uri, initheader: {'Content-Type' => 'application/json'})
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {:name=>"West Coast Div"}.to_json
http.request(request)
# Using the 'rest-client' gem
require 'rest-client'
require 'base64'
RestClient::Request.execute(
method: :put,
url: 'https://surveys.theoremreach.com/api/external/v1/sub_buyers/{{ sub_buyer_id }}?enc={{ generated_request_hash }}',
payload: {:name=>"West Coast Div"},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/sub_buyers/{{ sub_buyer_id }}?enc={{ generated_request_hash }}"
-X PUT
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
-H "Content-Type: application/json"
--data '{"name":"West Coast Div"}'
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/sub_buyers/{{ sub_buyer_id }}?enc={{ generated_request_hash }}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
),
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => '{"name":"West Coast Div"}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/sub_buyers/{{ sub_buyer_id }}?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {"name":"West Coast Div"}
requests.put(url, headers=headers, data=body)
const https = require('https');
const options = {
"method": "PUT",
"hostname": "surveys.theoremreach.com",
"port": 443,
"path": "/api/external/v1/sub_buyers/{{ sub_buyer_id }}?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {"name":"West Coast Div"};
const params = JSON.stringify(json);
const request = https.request(options, (response) => {
let chunks = [];
response.on("data", (chunk) => {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Response:
{
"data": {
"id": "b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c",
"name": "West Coast Div",
"survey_count": 42,
"created_at": "2026-02-27T12:00:00Z"
},
"meta": {
"warnings": []
}
}
Updates a sub-buyer with the provided attributes.
HTTP Request
PUT https://surveys.theoremreach.com/api/external/v1/sub_buyers/{{ sub_buyer_id }}
Query Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| enc | Yes | None | Generated request hash |
JSON Fields
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
| name | No | string | Name of the sub-buyer. Must be unique per company (case-insensitive). |
Sub-Buyer Response Fields
| Field | Type | Description |
|---|---|---|
| id | string | The sub-buyer's uid. |
| name | string | The sub-buyer's name. |
| survey_count | integer | Number of active surveys associated with this sub-buyer. |
| created_at | string (ISO 8601) | When the sub-buyer was created. |
Errors & Warnings
Request Hints
If your request is invalid, fails some security check, or another error occurs we will attempt to provide hints to help you fix the root cause. The hints can be found within the meta key at the root of the response JSON.
Example Data: { "meta": { "hints": ["This is an example of a hint."] } }
Request Warnings
All DIY API request responses contain a meta key at the root of the response JSON. Within meta key lies a warnings key which has a value of an array of strings. These strings can be beneficial in debugging why a request was successful, but perhaps not all expectations were met.
Scenario:
If you attempted to create a new quota with an unknown question ID, we will not halt the creation of the quota, but will rather return a warning stating that the question and/or answers could not be found.
Example Data: { "meta": { "warnings": ["This is a warning"] } }
Request Errors
Errors, unlike warnings, mean that a request failed to complete. Errors can be found at the root of the response JSON, under the errors key. This key is only present if error(s) were hit while we processed your request.
Example Data: { "errors": ["Error message", "Another error message"] }
Common Error Messages
The following are common error messages you may encounter when working with specific endpoints:
Screening Questions
| Error | Status | When |
|---|---|---|
| Cannot modify this question because it is shared with other surveys | 422 | Editing a locked screening question's display_text, question_type, or option values |
| Cannot modify a locked question. Delete it and create a new one from scratch to customize. | 422 | Editing display_text or question_type on a question created from a targeting question |
| Cannot add options to a locked question | 422 | Adding an option to a locked screening question |
| Cannot delete options on a locked question | 422 | Deleting an option from a locked screening question |
| Cannot modify the value of an option on a locked question. | 422 | Editing value on an option belonging to a targeting-question-sourced screening question |
| Cannot modify the value of an option on a question shared with other surveys. | 422 | Editing value on an option belonging to a clone-locked screening question |
| Cannot delete this question because it is used on: [survey names] | 409 | Deleting a screening question that has been cloned to other surveys |
| Cannot delete this question because it is used for quota targeting on: [survey names]. Remove it from quota targeting first. | 409 | Deleting a question referenced by deferred targeting assignments on other surveys' quotas |
| Cannot launch: custom questions from [survey names] have not been synced yet or have been deleted. Please launch and sync those surveys first, or remove the dependent targeting. | 400 | Launching a survey with unresolved screening question dependencies |
HTTP Status Codes & Reasons
| Error Code | Meaning | Description |
|---|---|---|
| 200 | Ok | Your request was successful. |
| 201 | Created | Your create request was successful, the resource was created. |
| 400 | Bad Request | Your request is invalid. Data provided is improperly formatted, or invalid. |
| 401 | Unauthorized | Your API key is invalid. |
| 403 | Forbidden | The security request hash provided is invalid, or the request is not in the whitelisted IP addresses. |
| 404 | Not Found | The specified resource could not be found. |
| 405 | Method Not Allowed | You tried to access a resource with an invalid HTTP method. |
| 422 | Unprocessable Entity | Your request was in a valid format, but there was a context or data issue. |
| 429 | Too Many Requests | Your request was rejected due to too many requests. |
| 500 | Internal Server Error | We had a problem with our server. Try again later. |
| 503 | Service Unavailable | We're temporarily offline for maintenance. Please try again later. |