Introduction
Welcome to TheoremReach's DIY Platform API.
Supplier: Providing respondents into TheoremReach surveys.
Buyer: Getting qualified respondents for your surveys.
Environments
To ease integration development, we have a sandbox
environment that you can run tests against.
Sandbox URL: https://surveys-sandbox.theoremreach.com/api/external/v1/
Production URL: https://surveys.theoremreach.com/api/external/v1/
Postman Collection (Sandbox)
We offer a complete postman collection for our API. Use our link below with your postman application's import feature to quickly dive in!
Postman Collection Link: https://www.getpostman.com/collections/e95452a2e0451a99c481
Once you've imported the collection you'll need to update a few variables. Click the triple dots on the collection, in the sidebar on the left of your postman window.
In the 'Edit Collection' modal window you will need to update two separate variables. Go to the 'Variables' tab near the top of the modal window. You'll need to update the secret_key
and api_key
variables. Specifically, update the CURRENT VALUE
column.
Your secret_key
and api_key
can be found here. When updating your api_key
, be sure to first base64 encode the key. Then, use that as the value for the variable.
Please do not edit or remove request_hash
or host
.
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-Key
HTTP header. - Provide your API key in the
api_key
query 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 |
Supplier
TheoremReach's APIs provide a simple and quick way to receive available survey inventory. With this, suppliers will be able to get an updated list of survey inventory, real time statistics for each survey, and targeting questions to match with user profiles.
Integration Guide
TheoremReach utilizes a push only methodology for survey changes. The moment something changes or we receive a new survey we push that data to you immediately. In order to properly set up and map questions and answers you can use any mapping provider you wish. It's highly recommended you use Lucid or our internal data / ids for mapping since they are the most comprehensive. A mapping provider is another company which we've already mapped to our internal questions and answers. You can get a list of supported mapping providers by looking at the resources->mapping providers API call.
Custom questions provide a survey level qualification limit. If they don't pass the custom question they cannot enter 'any' quota. On each quota you'll also have a questions array which gives you detailed targeting data about who should enter this particular quota. The ids you receive will be based on the mapping provider we have set up in our system.
Make sure to block any IP addresses you receive via the add_ips_to_survey_blocklist event.
We use SHA3 for URL security. It is required on all requests. Please make sure the hash verifies on your end to ensure the request came from us and wasn't tampered with.
Integration Process:
- Contact TheoremReach to become a respondent supplier.
- Give TheoremReach your return urls for your respondents and your callback url where you want us to send survey updates to. Also give us which mapping provider you prefer to use (Lucid or TheoremReach is recommended) We'll give you an api and secret key.
- Perform your integration and test
- Go live
User Flow:
- You match a user to a survey in TheoremReach
- You route the user to the appropriate entry url
- The user enters TheoremReach's survey you specified
- Regardless of outcome the user is routed back to your system with results of what happened
Definitions
Survey States
- running
- paused
- completed
Quota States
- active - Can send into
- inactive - Closed quota
- inactive_throttled - Temporarily closed, too many respondents in this quota
Logical Operators
- 1 = OR
- 2 = AND
- 3 = NOT
Custom Question Types
- single_select
- multi_select
Respondent Entry Url
Once you set up a survey, you need to append additional information to the survey entry link in order to gain entry to the survey. You must also include the attributes required to enter the quota. Make sure to limit your entry urls to 2000 characters.
Base URL Params
Parameter | Required | Default | Description |
---|---|---|---|
api_key | Yes | None | Your api key |
survey_id | Yes | None | ID of the survey you wish to gain access to |
quota_id | Yes | None | ID of the quota you wish to gain access to |
user_id | Yes | None | Your unique respondent ID |
transaction_id | Yes | None | Your unique transaction ID for entry into this survey |
enc | Yes | None | Generated request hash |
URL Attributes
You must also include all attributes required to enter the survey. This includes custom questions.
Standard Questions
You should append as much data as you can to the entry url, but the bare minimum will be all the required attributes to match. If you've set your mapping partner to Lucid then you will need to append those standard questions using the question and answer ids. For example:
To append a respondent who has an age of 25 you would do the following
&42=25
Custom Questions
You must also ask and append to the entry URL any of the custom questions. These are qualification level questions which the survey provider has created directly. When you receive the survey you'll receive these question and answer ids. You'll append it in a similar way to the standard questions however you must prepend tr_ to the question id. For example:
Given a question with id 1 and answer id of 34
&tr_1=34
Respondent Return Url
You will receive the respondent back to your given url with some additional parameters and status codes. You can configure your return url by using URL replacement. Anything within {} will be replaced with actual values.
Example:
https://google.com?my_transaction_id={source_transaction_id}&tr_transaction_id={tr_transaction_id}&result={result}&result_description={result_description}&disqualify_id={disqualify_id}
- disqualify_id = The ID of the question which causes a disqualification
Survey Model
Once we've turned on pushing surveys, your specified URL will get the following event_types
- add_ips_to_survey_blocklist
- update_survey
- update_quota
- create_or_update_survey
You'll need to process each event type in order to maximize your EPC and conversion rate.
create_or_update_survey
The most important event. Major changes are picked up in this event. Those types of creation or changes are captured here.
{ "survey":
{ "id": "58184905-6c85-410d-846b-5e75179a33eb",
"state": "draft",
"remaining_completes": 100,
"entry_url": "http://www.example.com/respondent_entry",
"loi": 1,
"cpi": 0.25,
"guaranteed_epc": 0.15,
"country_id": "cb6ccda-483d-461d-852c-13b2e637f6d7",
"custom_questions": [
{ "id": 2102,
"logical_operator": 1,
"text": "Favorite pet??",
"type": "multi_select",
"answers": [
{"id": 9331, "text": "Dogs", "accept": true},
{"id": 9332, "text": "Cats"}
]
}
],
"quotas": [
{ "id": "0ad6b44d-ac1b-4b68-a895-1bdffeda8fcc",
"state": "active",
"remaining_completes": 100,
"postal_codes": ["23185", "90210", "23669"],
"questions": {
"1": {"logical_operator": "or", "answers": [20, 21, 22, 23]}}
}],
"survey_groups" : []
}
}
Payload
Parameter | Required | Default | Description |
---|---|---|---|
id | Yes | None | ID of the survey |
state | Yes | None | State of the survey |
cpi | Yes | None | How much this survey will pay on completion |
guaranteed_epc | Yes | None | How much this survey will pay for a qualified entrant |
remaining_completes | Yes | None | The total number of completes remaining (all quotas) |
entry_url | Yes | None | Base entry URL for the survey |
loi | Yes | None | Length of survey in minutes |
country_id | Yes | None | Country that the survey is in |
custom_questions | Yes | None | Custom Questions are questions you need to ask on your end in order for the respondent to fully qualify for the survey |
quotas | Yes | None | All the quotas inside the survey |
survey_groups | Yes | None | Id of all blocked surveys (If a respondent has taken one of these surveys they cannot enter this one). Can be treated like a campaign group if you place every survey in its own ID survey group or a simple blacklist. |
enc | Yes | None | Generated request hash |
update_survey
This event type is also important and picks up on survey state changes and the number of respondents remaining. This allows you to throttle sending in when surveys and quotas start to get close to completion.
{ "survey":
{ "id": "58184905-6c85-410d-846b-5e75179a33eb",
"state": "completed",
"remaining_completes": 1,
"loi": 1
}
}
Payload
Parameter | Required | Default | Description |
---|---|---|---|
id | Yes | None | ID of the survey |
state | Yes | None | State of the survey |
remaining_completes | Yes | None | The total number of completes remaining (all quotas) |
loi | Yes | None | Length of survey in minutes |
enc | Yes | None | Generated request hash |
update_quota
This event allows you to get updates to quota state changes and number of respondents. We also do throttling at this level so you know when there are too many people inside a quota.
{ "survey":
{ "id": "58184905-6c85-410d-846b-5e75179a33eb"},
"quota":
{ "id": "41876ee7-00b4-4c1f-8487-7cf958d9f393"},
"state": "active",
"remaining_completes": 1
}
}
Payload
Parameter | Required | Default | Description |
---|---|---|---|
id | Yes | None | ID of the quota |
state | Yes | None | State of the quota |
remaining_completes | Yes | None | The total number of completes remaining |
enc | Yes | None | Generated request hash |
add_ips_to_survey_blocklist
We blacklist any IPs which have already entered the survey when they come in.
{ "survey": {
"id": "58184905-6c85-410d-846b-5e75179a33eb"},
"blocked_ips": ["143.198.182.26"]
}
}
Payload
Parameter | Required | Default | Description |
---|---|---|---|
id | Yes | None | ID of the quota |
blocked_ips | Yes | None | An array of IPs which are blacklisted for the survey |
enc | Yes | None | Generated request hash |
Start Sync
This end point allows you to request that we immediately send surveys to you. Helpful incase you want to get everything we have available or resync after making changes to the integration. We will send the create_or_update event type.
Request:
# Using net/http
require 'net/http'
require 'json'
require 'base64'
uri = URI('https://surveys.theoremreach.com/api/external/v1/start_sync?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 = {:count=>"1"}.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/start_sync?enc={{ generated_request_hash }}',
payload: {:count=>"1"},
content_type: 'application/json',
headers: {
'X-Api-Key': Base64.encode64('{{ your_company_api_key }}')
}
)
curl "https://surveys.theoremreach.com/api/external/v1/start_sync?enc={{ generated_request_hash }}"
-X POST
-H "X-Api-Key: {{ your_company_api_key_base64_encoded }}"
-H "Content-Type: application/json"
--data '{"count":"1"}'
<?php
/** Using cURL **/
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/start_sync?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 => '{"count":"1"}'
));
$response = curl_exec($curl);
curl_close($curl);
import requests
url = "https://surveys.theoremreach.com/api/external/v1/start_sync?enc={{ generated_request_hash }}"
headers = {
"Content-Type": "application/json",
"X-Api-Key": base64.b64encode("{{ your_company_api_key }}")
}
body = {"count":"1"}
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/start_sync?enc={{ generated_request_hash }}",
"headers": {
"Content-Type": "application/json",
"X-Api-Key": Buffer.from("{{ your_company_api_key }}").toString('base64')
}
};
const json = {"count":"1"};
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();
Buyer
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 }}&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 }}&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 }}&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 }}&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 }}&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 }}&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": {
"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 |
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 }}&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 }}&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 }}&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 }}&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 }}&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 }}&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 |
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",
"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"
}
},
...
],
"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",
"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": []
},
"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"]}.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"]},
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"]}'
<?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"]}'
));
$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"]}
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"]};
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",
"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": []
},
"meta": {
"warnings": []
}
}
Creates a new survey with the provided attributes.
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. |
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"]}.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"]},
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"]}'
<?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"]}'
));
$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"]}
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"]};
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",
"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": []
},
"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. |
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?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?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?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?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?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?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",
"options": []
},
{
"id": "bca5d9d3-f110-4c9c-b8a3-4df3978744aa",
"sort_order": 1,
"question_type": "multi_select",
"display_text": "What is your occupation?",
"shuffle_type": "no_shuffle",
"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 |
---|---|---|---|
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"}.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"},
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"}'
<?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"}'
));
$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"}
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"};
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",
"options": []
},
"meta": {
"warnings": []
}
}
Creates a new screening question for the survey. Up to a maximum of 3.
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. 1, 2, or 3 |
|
shuffle_type | No | string | Shuffle type for this question's options. shuffle or no_shuffle |
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",
"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. 1, 2, or 3 |
|
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 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
},
{
"id": "978755a8-71f9-4ffc-b96e-2645af9b3403",
"value": "Engineer",
"sort_order": 2,
"pass_question": true
},
{
"id": "91913910-1419-471e-bcd2-dcc74df59f71",
"value": "Astronaut",
"sort_order": 3,
"pass_question": true
}
],
"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
},
"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 should be displayed in. 1, 2, or 3. |
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
},
"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 should be displayed in. 1, 2, or 3. |
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
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();
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"]
}
],
"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": []
}
}
Retrieves a list of all quotas for the survey.
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 |
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 }}&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 }}&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 }}&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 }}&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 }}&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 }}&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();
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"] }
],
"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.
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 |
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 . 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 . |
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 }}&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 }}&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 }}&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 }}&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 }}&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 }}&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();
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"] }
],
"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 |
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 . 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 . |
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"] }
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. |