TheoremReach DIY Platform API

https://surveys-docs.theoremreach.com
Admin
TheoremReach DIY Platform API is a comprehensive REST API that enables developers to...
Tokens:56,519
Snippets:203
Trust Score:8.8
Update:7 months ago
Show doc for...
Tokens:
Raw
### Example GET Request Hashing

Source: https://surveys-docs.theoremreach.com/

Illustrates how to hash a GET request for TheoremReach. It combines the request URL and company secret key, generates a hash, and appends it to the URL with an 'enc' parameter.

```text
Request URL: `https://surveys.theoremreach.com/api/endpoint?param_one=value_one`
Company Secret Key: `UbsXaKTGWNd3wD8y5ZeV`

We Hash Them
`{Request URL}+{Company Secret Key}`
`https://surveys.theoremreach.com/api/endpoint?param_one=value_oneUbsXaKTGWNd3wD8y5ZeV`

Which Gives The Hash
`11409fe7199b4c3856873e9b0553fd8e1920d1fba1cf59c5517ba2e4ee3b87fd`

And Gets Added To The URL
`https://surveys.theoremreach.com/api/endpoint?param_one=value_one&enc=85598cc6d64d6d2490d088b070f955258d97840506731129958ed70a29db396e`
```

--------------------------------

### Retrieve Questions using Requests (Python)

Source: https://surveys-docs.theoremreach.com/

Provides a Python example using the 'requests' library to get questions from the TheoremReach API. It constructs the URL and headers, including a base64 encoded API key, and sends a GET request.

```python
import requests
import base64

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 }}").decode('utf-8')
}

requests.get(url, headers=headers)
```

--------------------------------

### List Sub-Buyers using Ruby

Source: https://surveys-docs.theoremreach.com/

Retrieves a list of sub-buyers from the TheoremReach API using a GET request. This Ruby example uses the 'net/http' library and requires an encrypted hash and API key for authentication.

```ruby
# Using net/http
require 'net/http'
require 'json'
require 'base64'

uri = URI('https://surveys.theoremreach.com/api/external/v1/sub_buyers?enc={{ generated_request_hash }}')

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json

http.request(request)
```

--------------------------------

### GET /api/external/v1/sub_buyers

Source: https://surveys-docs.theoremreach.com/

Retrieve a list of sub-buyers associated with the API key.

```APIDOC
## GET /api/external/v1/sub_buyers

### Description
List Sub-Buyers associated with your company's API key.

### Method
GET

### Endpoint
https://surveys.theoremreach.com/api/external/v1/sub_buyers

#### Query Parameters
- **enc** (string) - Required - Generated request hash.

### Request Example
```json
{
  "enc": "{{ generated_request_hash }}"
}
```

### Response
(Response structure for this endpoint is not provided in the input text.)
```

--------------------------------

### GET /api/external/v1/sub_buyers

Source: https://surveys-docs.theoremreach.com/

Retrieves a list of all sub-buyers belonging to the authenticated company.

```APIDOC
## GET /api/external/v1/sub_buyers

### Description
Retrieves a list of all sub-buyers belonging to the authenticated company.

### Method
GET

### Endpoint
https://surveys.theoremreach.com/api/external/v1/sub_buyers

### Parameters
#### Query Parameters
- **enc** (string) - Required - Generated request hash

### Request Example
GET /api/external/v1/sub_buyers?enc={{ generated_request_hash }}

### Response
#### Success Response (200)
- **data** (array) - List of sub-buyer objects
- **meta** (object) - Response metadata

#### Response Example
{
  "data": [
    {
      "id": "b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c",
      "name": "West Coast Division",
      "survey_count": 42,
      "created_at": "2026-02-27T12:00:00Z"
    }
  ],
  "meta": {
    "warnings": []
  }
}
```

--------------------------------

### Example POST/PUT Request Hashing

Source: https://surveys-docs.theoremreach.com/

Demonstrates hashing for POST/PUT requests to TheoremReach. It combines the request URL, JSON body (minified), and secret key, generates a hash, and appends it to the URL.

```text
Request URL: `https://surveys.theoremreach.com/api/endpoint`
Company Secret Key: `UbsXaKTGWNd3wD8y5ZeV`
JSON Body: `{“key”:“value”}`

We Hash Them
`{Request URL}+{JSON Body}+{Company Secret Key}`
`https://surveys.theoremreach.com/api/endpoint{“key”:“value”}UbsXaKTGWNd3wD8y5ZeV`

Which Gives The Hash
`58f191965859fc34fc2c96bba2fe8d633e74a9fea87ff4d362a202a68f4f26e8`

And Gets Added To The URL Or JSON Body
`https://surveys.theoremreach.com/api/endpoint?enc=b3ce2e72133a4d7eb69cf563249c969c9a7ea70331fee986f79df29cc387957d`
```

--------------------------------

### POST /api/external/v1/surveys/{survey_id}/start

Source: https://surveys-docs.theoremreach.com/

Starts a survey on your account. The survey must pass several validations, including having estimated conversion rate and LOI, an active payment method, and not being past its end date.

```APIDOC
## POST /api/external/v1/surveys/{survey_id}/start

### Description
Starts a survey on your account. There are a few validations that the survey must pass in order to successfully start: 
  * `user_estimated_conversion_rate` must be provided
  * `user_estimated_loi` must be provided
  * A active payment method must be set for your company
  * The survey must not be past the optionally provided `end_at` datetime

Survey starting may fail for reasons not listed above. If this is the case for you, take care to read the errors, warnings, and hints provided in the response body.

### Method
POST

### Endpoint
`https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/start`

### Parameters
#### Query Parameters
- **enc** (string) - Required - Generated request hash

#### Request Body
(Empty JSON object is expected)

### Request Example
```json
{
  "example": "{}"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains a message indicating success.
  - **message** (string) - "Successfully started the survey."

#### Response Example
```json
{
  "data": { "message": "Successfully started the survey." }
}
```
```

--------------------------------

### Start a Survey via REST API

Source: https://surveys-docs.theoremreach.com/

Initiates a survey session using a POST request. Requires a valid survey ID, a generated request hash, and a base64 encoded API key in the headers.

```Ruby
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 }}')
  }
)
```

```Shell
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
$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);
```

```Python
import requests
import base64

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 }}".encode()).decode()
}
body = {}
requests.post(url, headers=headers, json=body)
```

```JavaScript
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 request = https.request(options, (response) => {
  let chunks = [];
  response.on("data", (chunk) => chunks.push(chunk));
});
request.write('{}');
request.end();
```

--------------------------------

### GET /api/external/v1/surveys

Source: https://surveys-docs.theoremreach.com/

Retrieves a list of available surveys.

```APIDOC
## GET /api/external/v1/surveys

### Description
Retrieves a list of available surveys.

### Method
GET

### Endpoint
`https://surveys.theoremreach.com/api/external/v1/surveys`

### Query Parameters
- **enc** (string) - Required - A generated request hash for authentication and integrity.

### Request Example
```ruby
# 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)
```

### Response
#### Success Response (200)
*Details of the success response body are not provided in the input.*
```

--------------------------------

### GET /api/external/v1/countries

Source: https://surveys-docs.theoremreach.com/

Retrieves a list of all active countries supported by the platform.

```APIDOC
## GET /api/external/v1/countries

### Description
Retrieves a list of active countries available for survey targeting.

### Method
GET

### Endpoint
https://surveys.theoremreach.com/api/external/v1/countries

### Parameters
#### Query Parameters
- **enc** (string) - Required - The generated request hash for security verification.

### Request Example
GET https://surveys.theoremreach.com/api/external/v1/countries?enc={{ generated_request_hash }}

### Response
#### Success Response (200)
- **data** (array) - A list of country objects containing id and name.

#### Response Example
{
  "data": [
    {
      "id": "5a8296a0-0ab0-4e75-be00-71a6371b519b",
      "name": "United States"
    }
  ]
}
```

--------------------------------

### GET /api/external/v1/questions

Source: https://surveys-docs.theoremreach.com/

Retrieves a list of questions, filterable by country and mapping partner. Requires a generated request hash for authentication.

```APIDOC
## GET /api/external/v1/questions

### Description
Retrieves a list of questions, filterable by country and mapping partner.

### Method
GET

### Endpoint
https://surveys.theoremreach.com/api/external/v1/questions

### Parameters
#### Query Parameters
- **country_id** (string) - Required - The ID of the country to filter questions by.
- **mapping_partner_id** (string) - Required - The ID of the mapping partner to filter questions by.
- **enc** (string) - Required - Generated request hash

### Request Example
```
GET https://surveys.theoremreach.com/api/external/v1/questions?country_id={{ country_id }}&mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}
```

### Response
#### Success Response (200)
[Details about the success response structure for questions would go here, e.g., fields like question text, type, options, etc.]

#### Response Example
[Example response body for the questions endpoint would go here]
```

--------------------------------

### List Screening Question Options

Source: https://surveys-docs.theoremreach.com/

Retrieves a list of options for a specific screening question using a GET request. Requires authentication via a Base64 encoded API key in the request headers.

```ruby
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)
```

--------------------------------

### HTTP Status Codes

Source: https://surveys-docs.theoremreach.com/

A reference guide for interpreting HTTP status codes returned by the API.

```APIDOC
## HTTP Status Codes

### Description
This section details the standard HTTP status codes returned by the TheoremReach API to indicate the outcome of your requests.

### Status Code Reference
| 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. |
```

--------------------------------

### GET /api/external/v1/surveys

Source: https://surveys-docs.theoremreach.com/

Retrieves a list of all surveys available in the system.

```APIDOC
## GET /api/external/v1/surveys

### Description
Retrieves a list of all surveys in your system.

### Method
GET

### Endpoint
https://surveys.theoremreach.com/api/external/v1/surveys

### Parameters
#### Query Parameters
- **enc** (string) - Required - Generated request hash

### Request Example
GET /api/external/v1/surveys?enc={{ generated_request_hash }}

### Response
#### Success Response (200)
- **data** (array) - List of survey objects
- **meta** (object) - Metadata including warnings

#### Response Example
{
  "data": [
    {
      "id": "e6bad93a-fb3c-423e-bea1-b9746bcd9786",
      "name": "New Survey",
      "state": "draft",
      "entry_url_prod": "https://surveyprovider.com/prod/?transaction_id={transaction_id}"
    }
  ],
  "meta": {
    "warnings": []
  }
}
```

--------------------------------

### GET /api/external/v1/questions

Source: https://surveys-docs.theoremreach.com/

Retrieves a list of survey questions filtered by country and mapping partner.

```APIDOC
## GET /api/external/v1/questions

### Description
Retrieves a list of questions scoped to the mapping partner and country.

### Method
GET

### Endpoint
https://surveys.theoremreach.com/api/external/v1/questions

### Parameters
#### Query Parameters
- **country_id** (string) - Required - Country ID
- **mapping_partner_id** (string) - Optional - Mapping Partner ID (Default: TheoremReach)
- **enc** (string) - Required - Generated request hash

### Request Example
GET https://surveys.theoremreach.com/api/external/v1/questions?country_id=US&mapping_partner_id=1&enc=hash

### Response
#### Success Response (200)
- **data** (array) - List of question objects
- **meta** (object) - Response metadata

#### Response Example
{
  "data": [
    {
      "id": "f2c062da-9f63-4602-88a8-e8525a4f1443",
      "english_text": "What is your age?",
      "name": "Age",
      "question_type": "single_select"
    }
  ],
  "meta": {
    "warnings": []
  }
}
```

--------------------------------

### GET /api/external/v1/screening_questions/{screening_question_id}/screening_question_options

Source: https://surveys-docs.theoremreach.com/

Retrieves a list of all options for a specific screening question. Requires a generated request hash for authentication.

```APIDOC
## GET /api/external/v1/screening_questions/{screening_question_id}/screening_question_options

### Description
Retrieves a list of all options for the screening question.

### Method
GET

### Endpoint
`https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options`

### Query Parameters
- **enc** (string) - Required - Generated request hash

### Headers
- **X-Api-Key** (string) - Required - Base64 encoded API key

### Request Example
```
GET https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options?enc={{ generated_request_hash }}

# Headers
X-Api-Key: {{ your_company_api_key_base64_encoded }}
```

### Response
#### Success Response (200)
- **data** (array) - An array of screening question option objects.
  - **id** (string) - The unique identifier for the option.
  - **value** (string) - The text value of the option.
  - **sort_order** (integer) - The order in which the option should be displayed.
  - **pass_question** (boolean) - Indicates if selecting this option passes the question.
- **meta** (object) - Metadata about the response.
  - **warnings** (array) - An array of any warnings generated during the request.

#### Response Example
```json
{
  "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": []
  }
}
```
```

--------------------------------

### Start a survey via TheoremReach API

Source: https://surveys-docs.theoremreach.com/

Initiates a survey session using a POST request. Requires the survey ID and request hash in the URL, with authentication provided via the X-Api-Key header.

```ruby
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)
```

--------------------------------

### GET /countries

Source: https://surveys-docs.theoremreach.com/

Retrieves a list of available countries supported by the TheoremReach platform.

```APIDOC
## GET /countries

### Description
Retrieves a list of countries available for survey targeting.

### Method
GET

### Endpoint
/api/external/v1/countries

### Parameters
#### Query Parameters
- **api_key** (string) - Optional - The base64 encoded API key if not provided in the header.

### Request Example
curl https://surveys.theoremreach.com/api/external/v1/countries \
  -H 'X-Api-Key: [BASE64_ENCODED_KEY]'

### Response
#### Success Response (200)
- **countries** (array) - List of country objects.

#### Response Example
{
  "countries": [
    {
      "id": "US",
      "name": "United States"
    }
  ]
}
```

--------------------------------

### GET /api/external/v1/screening_questions/{screening_question_id}/screening_question_options

Source: https://surveys-docs.theoremreach.com/

Retrieves a list of all options for a given screening question. Requires an 'enc' query parameter for request verification.

```APIDOC
## GET /api/external/v1/screening_questions/{screening_question_id}/screening_question_options

### Description
Lists screening question options.

### Method
GET

### Endpoint
`https://surveys.theoremreach.com/api/external/v1/screening_questions/{{ screening_question_id }}/screening_question_options?enc={{ generated_request_hash }}`

### Headers
- **X-Api-Key** (string) - Required - Base64 encoded API key.

### Query Parameters
- **enc** (string) - Required - Generated request hash.

### Request Body
This endpoint does not require a request body.

### Response
(Response details not provided in the input text)
```

--------------------------------

### Get Sub-Buyer Details API Request

Source: https://surveys-docs.theoremreach.com/

Fetches specific details for a single sub-buyer using their unique ID. Requires the sub-buyer ID in the URL path and authentication via the X-Api-Key header.

```ruby
require 'net/http'
require 'json'
require 'base64'

uri = URI('https://surveys.theoremreach.com/api/external/v1/sub_buyers/{{ sub_buyer_id }}?enc={{ generated_request_hash }}')

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['X-Api-Key'] = Base64.encode64('{{ your_company_api_key }}')
request.body = {}.to_json

http.request(request)
```

--------------------------------

### Retrieve Screening Questions via GET Request

Source: https://surveys-docs.theoremreach.com/

Fetches a list of custom screening questions for a specific survey. Requires a generated request hash in the query parameters and a Base64 encoded API key in the headers.

```Ruby
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 }}')
  }
)
```

```Shell
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
$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);
```

```Python
import requests
import base64

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 }}".encode()).decode()
}

requests.get(url, headers=headers)
```

```JavaScript
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 request = https.request(options, (response) => {
  let chunks = [];
  response.on("data", (chunk) => { chunks.push(chunk); });
});
request.end();
```

--------------------------------

### List Survey Transactions using Ruby

Source: https://surveys-docs.theoremreach.com/

This Ruby snippet demonstrates how to list survey transactions using the 'net/http' library. It requires 'json' and 'base64' for encoding. The request is a GET to the screening_questions endpoint with an 'X-Api-Key' header.

```ruby
# 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)

```

--------------------------------

### Create Survey Transaction using Python

Source: https://surveys-docs.theoremreach.com/

This Python example uses the 'requests' library to create a survey transaction. It defines the URL, headers (including a base64 encoded API key), and an empty body for the POST request.

```python
import requests
import base64

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 }}").decode('utf-8')
}
body = {}
response = requests.post(url, headers=headers, data=body)

```

--------------------------------

### Retrieve Surveys using Node.js HTTPS

Source: https://surveys-docs.theoremreach.com/

Fetches a list of all surveys from the TheoremReach API using Node.js 'https' module. This example sets up the request options, including hostname, path, and headers with a base64 encoded API key, and makes the GET request.

```javascript
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 req = https.request(options, (res) => {
  let chunks = [];

  res.on("data", (chunk) => {
    chunks.push(chunk);
  });

  res.on("end", () => {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", (error) => {
    console.error(error);
  });
});

req.end();
```

--------------------------------

### POST /api/external/v1/sub_buyers

Source: https://surveys-docs.theoremreach.com/

Creates a new sub-buyer within the system.

```APIDOC
## POST /api/external/v1/sub_buyers

### Description
Creates a new sub-buyer record.

### Method
POST

### Endpoint
https://surveys.theoremreach.com/api/external/v1/sub_buyers

### Parameters
#### Query Parameters
- **enc** (string) - Required - Generated request hash.

#### Request Body
- **name** (string) - Required - The name of the sub-buyer.

### Request Example
{
  "name": "West Coast Division"
}

### Response
#### Success Response (200)
- **id** (string) - The ID of the newly created sub-buyer.
```

--------------------------------

### Authenticate API Requests

Source: https://surveys-docs.theoremreach.com/

Demonstrates how to authenticate API requests using the X-Api-Key header or query parameters. Requires the API key to be base64 encoded when passed in the header.

```shell
curl https://surveys.theoremreach.com/api/external/v1/countries -H 'X-Api-Key: NDAyMTVhOGQtZjFhMy00ZjI0LThiYmQtNzExZTdmMzcyMWE4'
curl https://surveys.theoremreach.com/api/external/v1/countries?api_key=50215a8d-a1a3-4f24-8xbd-721e763721a8
```

```ruby
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)

require 'rest-client'
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
$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);
```

```python
import requests
import base64

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)
```

```javascript
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();
```

--------------------------------

### Get Countries List using Python

Source: https://surveys-docs.theoremreach.com/

Retrieves a list of active countries using the 'requests' library in Python. It constructs the URL and headers, including a base64 encoded API key, and sends a GET request.

```python
import requests
import base64

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 }}").decode('utf-8')
}

requests.get(url, headers=headers)
```

--------------------------------

### Get Countries List using Ruby Net::HTTP

Source: https://surveys-docs.theoremreach.com/

Retrieves a list of active countries using Ruby's built-in 'net/http' library. It constructs a URI, sets up an HTTP connection with SSL, and sends a GET request with the necessary API key header.

```ruby
# 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)
```

--------------------------------

### Retrieve Questions using Ruby

Source: https://surveys-docs.theoremreach.com/

Fetches a list of questions based on country ID, mapping partner ID, and a generated request hash using Ruby's 'net/http' library. Requires an API key.

```ruby
# 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)
```

--------------------------------

### Create Survey Transaction using cURL

Source: https://surveys-docs.theoremreach.com/

This example shows how to create a survey transaction using the cURL command-line tool. It specifies the POST method, the target URL with query parameters, and includes the 'X-Api-Key' header with a base64 encoded API key.

```bash
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 }}"
```

--------------------------------

### POST /api/external/v1/surveys/{survey_id}/start

Source: https://surveys-docs.theoremreach.com/

Initiates a survey for a user. This endpoint requires the survey ID and a generated request hash.

```APIDOC
## POST /api/external/v1/surveys/{survey_id}/start

### Description
Starts a survey on your account.

### Method
POST

### Endpoint
`https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/start`

### Query Parameters
- **enc** (string) - Required - Description: Generated request hash

### Headers
- **X-Api-Key** (string) - Required - Description: Base64 encoded API key

### Request Body
(Empty JSON object is expected for this request)

### Request Example
```
# Ruby
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)
```
```

--------------------------------

### GET /api/external/v1/countries

Source: https://surveys-docs.theoremreach.com/

Retrieves a list of active countries available in the system.

```APIDOC
## GET /api/external/v1/countries

### Description
Retrieves a list of active countries available in the system.

### Method
GET

### Endpoint
https://surveys.theoremreach.com/api/external/v1/countries

### Parameters
#### Query Parameters
- **enc** (string) - Required - Generated request hash

#### Request Body
(Not applicable for GET requests)

### Request Example
(See provided Ruby example in the source text for a client-side implementation)

### Response
#### Success Response (200)
- **(Structure not detailed in source text)**

#### Response Example
(Not detailed in source text)
```

--------------------------------

### GET /api/external/v1/sub_buyers/{sub_buyer_id}

Source: https://surveys-docs.theoremreach.com/

Retrieves details for a specific sub-buyer by their unique identifier.

```APIDOC
## GET /api/external/v1/sub_buyers/{sub_buyer_id}

### Description
Retrieves details for a specific sub-buyer by their unique identifier.

### Method
GET

### Endpoint
https://surveys.theoremreach.com/api/external/v1/sub_buyers/{sub_buyer_id}

### Parameters
#### Path Parameters
- **sub_buyer_id** (string) - Required - The unique ID of the sub-buyer

#### Query Parameters
- **enc** (string) - Required - Generated request hash

### Request Example
GET /api/external/v1/sub_buyers/{{ sub_buyer_id }}?enc={{ generated_request_hash }}

### Response
#### Success Response (200)
- **id** (string) - Sub-buyer ID
- **name** (string) - Sub-buyer name

#### Response Example
{
  "id": "b7c1e2a0-3d4f-5e6a-7b8c-9d0e1f2a3b4c",
  "name": "West Coast Division"
}
```

--------------------------------

### GET /api/external/v1/surveys/:survey_id/quotas

Source: https://surveys-docs.theoremreach.com/

Retrieves a list of quotas associated with a specific survey.

```APIDOC
## GET /api/external/v1/surveys/:survey_id/quotas

### Description
Lists all quotas for a given survey.

### Method
GET

### Endpoint
`https://surveys.theoremreach.com/api/external/v1/surveys/{{ survey_id }}/quotas?mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}`

### Query Parameters
- **mapping_partner_id** (string) - Required - Identifier for the mapping partner.
- **enc** (string) - Required - Generated request hash.

### Request Body
This endpoint does not require a request body.

### Request Example
```ruby
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)
```

### Response
#### Success Response (200)
- **data** (array) - A list of quota objects.
  - **quota_id** (string) - The unique identifier for the quota.
  - **name** (string) - The name of the quota.
  - **target_completes** (integer) - The target number of completes for this quota.

#### Response Example
```json
{
  "data": [
    {
      "quota_id": "q123",
      "name": "US Adults",
      "target_completes": 100
    }
  ]
}
```
```

--------------------------------

### Create Sub-Buyer using PHP cURL

Source: https://surveys-docs.theoremreach.com/

Creates a new sub-buyer using cURL in PHP. This script initializes a cURL session, sets the appropriate options for the POST request, and executes it.

```php
<?php

/** Using cURL **/
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://surveys.theoremreach.com/api/external/v1/sub_buyers?enc={{ generated_request_hash }}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'X-Api-Key: ' . base64_encode('{{ your_company_api_key }}')
  ),
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => '{"name":"West Coast Division"}'
));

$response = curl_exec($curl);

curl_close($curl);

?>
```

--------------------------------

### Retrieve Questions using cURL

Source: https://surveys-docs.theoremreach.com/

Demonstrates how to retrieve questions from the TheoremReach API using the cURL command-line tool. It includes the necessary URL parameters and the base64 encoded API key in the 'X-Api-Key' header.

```bash
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 }}"
```

--------------------------------

### GET /api/external/v1/surveys/{survey_id}

Source: https://surveys-docs.theoremreach.com/

Retrieves detailed information for a specific survey by its ID.

```APIDOC
## GET /api/external/v1/surveys/{survey_id}

### Description
Retrieves detailed information for a specific survey.

### Method
GET

### Endpoint
https://surveys.theoremreach.com/api/external/v1/surveys/{survey_id}

### Parameters
#### Path Parameters
- **survey_id** (string) - Required - The unique identifier of the survey

#### Query Parameters
- **mapping_partner_id** (string) - Required - The ID of the mapping partner
- **enc** (string) - Required - Generated request hash

### Request Example
GET /api/external/v1/surveys/{{ survey_id }}?mapping_partner_id={{ mapping_partner_id }}&enc={{ generated_request_hash }}

### Response
#### Success Response (200)
- **data** (object) - Detailed survey information

#### Response Example
{
  "data": {
    "id": "e6bad93a-fb3c-423e-bea1-b9746bcd9786",
    "name": "New Survey",
    "state": "draft"
  }
}
```

--------------------------------

### Retrieve Screening Question Options

Source: https://surveys-docs.theoremreach.com/

Fetches a list of available options for a specific screening question. Requires a valid API key and a generated request hash as a query parameter.

```ruby
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 }}')
  }
)
```

```bash
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
$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);
```

```python
import requests
import base64

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 }}".encode()).decode()
}

requests.get(url, headers=headers)
```

```javascript
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 request = https.request(options, (response) => {
  let chunks = [];
  response.on("data", (chunk) => { chunks.push(chunk); });
});
request.end();
```
Tokens:
Raw