NAV Navbar
shell ruby php python javascript

Introduction

Welcome to TheoremReach's DIY Platform API.

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.

Click the triple dots, then edit to open the edit modal.

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.

Click the Variables tab, then update the variables.

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:

  1. Provide your base64 encoded API key in the X-Api-Key HTTP header.
  2. 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
85598cc6d64d6d2490d088b070f955258d97840506731129958ed70a29db396e

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
b3ce2e72133a4d7eb69cf563249c969c9a7ea70331fee986f79df29cc387957d

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

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
        }
      }
    ]
  },
  "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"}.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"},
  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"}'

<?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"}'
));

$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"}
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"};
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": []
  },
  "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. If you wish to have this feature enabled please contact an admin at TheoremReach.
cpi No float Bid CPI for this survey -- (range: 0.75 - 2.00). This field is only enabled if your company has biddable cpi enabled. If you with 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.

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"}.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"},
  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"}'

<?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"}'
));

$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"}
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"};
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": []
  },
  "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. If you wish to have this feature enabled please contact an admin at TheoremReach.
cpi No float Bid CPI for this survey -- (range: 0.75 - 2.00). This field is only enabled if your company has biddable cpi enabled. If you with 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.

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.