Surveys

The Projects endpoint provides a list of survey projects for a user, each containing associated quotas, demographics, and additional data elements.

POST https://grabcherries.com/api/s/projects

Parameters

Functional parameters

📘

Good to know

The functional parameters below can be omitted, but may be important depending on your integration. As a best practice, we recommend using the default values for details and limit. The default values will give you the fastest response and smallest payload. You can override these values if you want more detailed information.

ParameterDescription
details

Can be 0, 1, or 2 (default is 0 if omitted)

0 = no qualifications or quotas
1 = return qualifications only
2 = return both qualifications and full quotas.

limitThe maximum number of projects to return. (default is 10 if omitted).
session_idThis a unique ID you should assign for each panelist entry to Cherries. This session ID will appear as the parameter "mid" in the entry and return URLs. If you include it in this API call, we'll return the full link including your hash security for you. If you don't, you can add the mid and the hash security yourself.

Parameters

📘

Good to know

Some parameters are required, whereas others are optional. It's important to send in accurate information or the panelists will be matched to the wrong surveys.

ParameterDescription
panelist_idrequiredA unique panelist id assigned by the supplier. This should be distinct for each user. Max characters: 100.
hashrequiredPlease see hashing article Hashing
identifiers

Dictionary with identifiers. Some are optional, others are required.

Example:

{ "ip_address": "24.24.24.24", "email": "[email protected]", "phone_hash": "6973979bda1b26fd0063...54aab85e1674", "user_device": "desktop" }

ip_addressrequiredThe IP address of the user (IPv4 or IPv6). IPv4 is the preferred parameter. The IP address is used for geographical checks, deduping and fingerprinting purposes.
email or email_hashrequired

Email address of the user. Should be a real, legitimate email address.

Alternatively, a hashed email can be sent instead. This should be sent in sha256 as hex format. See below for hashing examples.

Please note that passing email_hash instead of email limits our ability to detect fraud.

phone& phone_country_code or phone_hash

Used for fraud purpose and deduping. Either phone+country code can be provided, or a hash of the phone number (phone_hash). This should be sent in sha256 as hex format. See below for hasing examples.

Please note that passing phone_hash instead of phone limits our ability to detect fraud.

user_device and/or user_agent

user_device can be "desktop", "tablet", or "mobile". If you send in the user's full user_agent from the browser, we'll parse it on our end and use the other details in the user agent for better targeting.

Please note that passing user_device instead of user_agent limits our ability to detect fraud and efficiently target users to the best surveys.

profilers

Dictionary with profilers. Some are optional, others are required.

Example:

{ country_code: "US", "gender" : "m", "postal_code" : "10014", "race" : "1", "hispanic" : "1", "education" : "6", }

For acceptable values see list of profilers

country_coderequiredThe country of the user
date_of_birth or agerequired

date_of_birth is in YYYY-MM-DD format.

If no date_of_birth is available, age can be provided instead. Please note that passing age info is less precise than passing date_of_birth and may impact performance.

genderrequiredFor acceptable values see list of profilers
postal_codeWe recommend sending in a ZIP code or postal code to enhance the system's targeting ability (many studies are region-based and require a postal code )
additional profilers

For profiler questions with type Multiple Choice, the answers must be comma-separated value.

For a list of profilers you can send to Cherries, click here

Response

Projects Key

FieldDescription
project_idUnique id for the project
entry_linkThe entry link for the panelist
cpiPayout for the survey
loiMaximum LOI. After the user has spent this much time, they get a guaranteed complete. If the user completes a study with a lower LOI than this loi, they receive credit as well.
loi_secondsSame as LOI but in seconds
estimated_conversion_rateEstimated percentage of clicks which become completes according to Cherries systems
remaining_completesTotal available number of completes (allocation) still available for the project
survey_groups_idsIf a user has taken one of these projects, they are excluded
qualificationsDictionary with profiler names as keys and profiler answers are values. For a list of profilers Cherries may return, click here
quotas

List of objects. Each object in the list represents one quota the user might qualify for and contains the keys remaining and criteria.

remaining is the number of completes (allocation) still available for this quota.

criteria is a dictionary describing how a user qualifies for this quota. Each key in the dictionary is a profiler name and the corresponding value describes the acceptable profiler answers. For a list of profilers Cherries may return, click here

A user will qualify for the study if they match at least one quota AND the user does not match any quota with remaining = 0

buyer_irThe expected incidence rate for the survey, according to the buyer. Always > 0.
buyer_loiIn minutes, the estimated LOI for the survey if the user qualifies, according to the buyer

User Key

FieldDescription
accrued_effortThis is the time the user has earned before and will transfer between sessions. Users see this as earned "time credits".
is_blockedWhether the user is blocked
is_throttledWhether the user is throttled

Code example

curl -X POST https://grabcherries.com/api/s/projects \
-H "Supplier-ID: your_supplier_id" \
-H "Private-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
    "details": 0,
    "limit": 10,
    "session_id": "optional_unique_id_for_session",
    "panelist_id": "user123",
    "identifiers": {
        "ip_address": "8.8.8.8",
        "email": "[email protected]",
        "phone_country_code": "1",
        "phone": "2127654321",
        "user_device": "desktop",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"
    },
    "profilers": {
        "gender": "m",
        "date_of_birth": "1994-01-31",
        "country_code": "US",
        "postal_code": "10014",
        "race": "1",
        "hispanic": "1",
        "education": "6"
    }
}'
import requests

url = "https://grabcherries.com/api/s/projects"
headers = {
    "Supplier-ID": "your_supplier_id",
    "Private-Key": "your_api_key"
}
data = {
    "details": 0,
    "limit": 10,
    "session_id": "optional_unique_id_for_session",
    "panelist_id": "user123",
    "identifiers": {
        "ip_address": "8.8.8.8",
        "email": "[email protected]",
        "phone_country_code": "1",
        "phone": "2127654321",
        "user_device": "desktop",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"
    },
    "profilers": {
        "gender": "m",
        "date_of_birth": "1994-01-31",
        "country_code": "US",
        "postal_code": "10014",
        "race": "1",
        "hispanic": "1",
        "education": "6"
    }
}

response = requests.post(url, headers=headers, json=data)

print(response.status_code)
print(response.json())
<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$url = "https://grabcherries.com/api/s/projects";
$headers = [
    'Supplier-ID' => 'your_supplier_id',
    'Private-Key' => 'your_api_key',
    'Content-Type' => 'application/json'
];
$data = [
    'details' => 0,
    'limit' => 10,
    'session_id' => 'optional_unique_id_for_session',
    'panelist_id' => 'user123',
    'identifiers' => [
        'ip_address' => '8.8.8.8',
        'email' => '[email protected]',
        'phone_country_code' => '1',
        'phone' => '2127654321',
        'user_device' => 'desktop',
        'user_agent' => 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36'
    ],
    'profilers' => [
        'gender' => 'm',
        'date_of_birth' => '1994-01-31',
        'country_code' => 'US',
        'postal_code' => '10014',
        'race' => '1',
        'hispanic' => '1',
        'education' => '6'
    ]
];

try {
    $response = $client->post($url, [
        'headers' => $headers,
        'json' => $data
    ]);

    echo 'Response Code: ' . $response->getStatusCode() . PHP_EOL;
    echo 'Response Data: ' . $response->getBody() . PHP_EOL;
} catch (Exception $e) {
    echo 'Error: ' . $e->getMessage() . PHP_EOL;
}
?>

Hashing Examples

def get_email_hash(email_address: str):
    email_address = email_address.strip().lower() # email assumed to be all lower case, valid naked email (e.g. not `Peter Jackson <[email protected]>`, just `[email protected])`
    return hashlib.sha256(email_address.encode()).hexdigest()

def get_phone_hash(phone_country_code: str, phone: str):
    phone = phone_country_code + phone # phone and phone_country_code assumed to be all digits, no punctuation
    phone = ''.join(filter(str.isdigit, phone)) # (e.g. remove all characters that are not digits)
    return hashlib.sha256(phone.encode()).hexdigest()
function get_email_hash($email_address) {
    $email_address = trim(strtolower($email_address)); // email assumed to be all lower case, valid naked email
    return hash('sha256', $email_address);
}

function get_phone_hash($phone_country_code, $phone) {
    $phone = $phone_country_code . $phone; // phone and phone_country_code assumed to be all digits, no punctuation
    $phone = preg_replace('/\D/', '', $phone); // remove all characters that are not digits
    return hash('sha256', $phone);
}

Did this page help you?