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.

Parameter	Description
`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.
`limit`	The maximum number of projects to return. (default is 10 if omitted).
`session_id`	This 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.

Parameter

Description

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.

limit

The maximum number of projects to return. (default is 10 if omitted).

session_id

This 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.

Parameter	Description
`panelist_id` ❗required	A unique panelist id assigned by the supplier. This should be distinct for each user. Max characters: 100.
`hash` ❗required	Please 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_address`❗required	The 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_hash` ❗required	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_code`❗required	The country of the user
`date_of_birth` or `age` ❗required	`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.
`gender` ❗required	For acceptable values see list of profilers
`postal_code`	We 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

Field	Description
project_id	Unique id for the project
entry_link	The entry link for the panelist
cpi	Payout for the survey
loi	Maximum 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.
estimated_conversion_rate	Estimated percentage of clicks which become completes according to Cherries systems
remaining_completes	Total available number of completes (allocation) still available for the project
survey_groups_ids	If a user has taken one of these projects, they are excluded
qualifications	Dictionary 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_ir	The expected incidence rate for the survey, according to the buyer. Always > 0.
buyer_loi	In minutes, the estimated LOI for the survey if the user qualifies, according to the buyer

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);
}