Hey Data API
Hey Data lets you ask people for their own platform records, pay each person who agrees, and download exactly the records they approved. The API does everything the campaign studio does for one campaign: write it, check who matches, submit it, start the payment, follow its progress, prepare the file, download it and close it. Every request runs as the person who created the key, with that person’s current role, so a key can never do more than its creator can in the studio.
Before you start
- Create an organization. Sign in at /data/campaigns and create your organization. That is where you accept the Hey Data buyer licence (version 2026-11-16). It is done once, by a person, in the studio; the API cannot do it.
- Create a key. In the studio open Team & settings → API access, name the key, choose its permissions and how long it lasts, and copy it. It is shown once. Only the organization’s owner and administrators can create keys, and a payment can only be started with a key the owner created.
- Keep it secret. Store the key in your server’s environment or secret manager. Never put it in a URL, a web page, a mobile app or a shared notebook.
Every path below is relative to https://hey.ai/api/data/v1. Requests and responses are JSON, and every request that sends a body, even an empty {}, needs Content-Type: application/json.
Quickstart
Set the address and your key once in your shell:
export HEY_DATA_URL=https://hey.ai
export HEY_DATA_KEY='paste the key from Team & settings here'
API="$HEY_DATA_URL/api/data/v1"1. Read the catalog
curl --fail-with-body -H "X-Hey-Data-Key: $HEY_DATA_KEY" "$API/catalog"It lists every dataset with its fields, typed filters and limitations (the same list as Datasets below), the demographic answers you can filter on, min_reward_cents, your organization’s id and exact name, and the permissions this key has.
2. Create a draft
Save a specification as campaign.json. This example asks 20 adults for a year of Amazon purchases and Google searches and pays each $10.00. With Hey’s fee it costs you $14.29 a participant, $285.80 in all (Paying and being refunded). organization must be your organization’s name exactly as the catalog states it. The terms are the standard terms, so the campaign is approved without a manual review.
{
"schema_version": 2,
"title": "Search and purchase recommendations",
"organization": "Your organization name",
"request": "Amazon purchases and Google searches from the same adults, to evaluate a recommendation model.",
"goal": "recommendations",
"purpose": "evaluation",
"sources": ["amazon", "google"],
"source_mode": "all",
"fields": {"amazon": ["product_name", "quantity", "currency"], "google": ["title", "type"]},
"filters": {
"amazon": {"include": [], "exclude": [], "conditions": []},
"google": {"include": [], "exclude": [], "conditions": [{"field": "type", "op": "eq", "value": "searched"}]}
},
"since": "2025-11-18",
"until": "2026-11-18",
"freshness_days": 60,
"min_records": 5,
"min_days": 0,
"cohort": {"age_min": 18, "age_max": 120, "regions": []},
"countries": [],
"languages": [],
"target_participants": 20,
"reward_cents": 1000,
"budget_cents": 20000,
"retention_days": 30,
"deadline": "2026-12-18",
"privacy": "pseudonymous",
"format": "parquet",
"terms": "Use the delivered records only for the purpose stated in this campaign. Do not sell, share or sublicense the records to another party. Do not attempt to identify or contact participants, or link their records to an identified person. Delete the records by the end of the stated retention period, which must not exceed 90 days. Pay the stated USD reward once per participant when their records are first delivered. Participants can stop future deliveries; copies already delivered cannot be recalled by Hey."
}curl --fail-with-body -X POST "$API/campaigns" \
-H "X-Hey-Data-Key: $HEY_DATA_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: search-purchases-001" \
--data @campaign.jsonThe reply (201) is the campaign. Keep its id: export CAMPAIGN_ID=…. If the request times out, send the same JSON with the same Idempotency-Key again; you get the same campaign, never a second one.
3. Check who matches (optional, before you pay)
curl --fail-with-body -X POST "$API/campaigns/$CAMPAIGN_ID/availability" \
-H "X-Hey-Data-Key: $HEY_DATA_KEY" -H "Content-Type: application/json" --data '{}'An estimate, never records: see Checking availability.
4. Submit
curl --fail-with-body -X POST "$API/campaigns/$CAMPAIGN_ID/submit" \
-H "X-Hey-Data-Key: $HEY_DATA_KEY" -H "Content-Type: application/json" --data '{}'On the standard terms the campaign is approved at once, with no manual review, and its status becomes awaiting_funding. Custom terms or a sensitive topic wait in submitted for a manual review by Hey; poll GET /campaigns/$CAMPAIGN_ID until the status changes.
5. Fund it
curl --fail-with-body -X POST "$API/campaigns/$CAMPAIGN_ID/funding/checkout" \
-H "X-Hey-Data-Key: $HEY_DATA_KEY" -H "Content-Type: application/json" --data '{}'The reply carries url, a Stripe Checkout page. Payment itself happens in a browser: a person opens that page and pays by card; no key can pay. Asking again while the page is open returns the same page. Then follow the funding until funded_cents equals total_cents, at which point the campaign’s status is active:
curl --fail-with-body -H "X-Hey-Data-Key: $HEY_DATA_KEY" "$API/campaigns/$CAMPAIGN_ID/funding"POST /campaigns/$CAMPAIGN_ID/funding/refresh (body {}) asks Stripe straight away instead of waiting for its notice.
If Hey is reviewing the payment when it arrives, the campaign stays awaiting_funding and carries payment_review: true meanwhile. When the review clears it, the campaign becomes active, or closed with the whole payment refunded if its closing date has passed by then.
6. Follow progress
curl --fail-with-body -H "X-Hey-Data-Key: $HEY_DATA_KEY" "$API/campaigns/$CAMPAIGN_ID"approvals is how many people’s approvals are current and approvals_expire_at when the first of them lapses. recruitment, when present, is the matching progress; its matched stays null until at least 5 people match.
7. Prepare an export
curl --fail-with-body -X POST "$API/campaigns/$CAMPAIGN_ID/exports" \
-H "X-Hey-Data-Key: $HEY_DATA_KEY" -H "Content-Type: application/json" --data '{}'The reply (202) is an export job. Keep its id: export EXPORT_ID=….
8. Wait until it is ready
curl --fail-with-body -H "X-Hey-Data-Key: $HEY_DATA_KEY" "$API/campaigns/$CAMPAIGN_ID/exports/$EXPORT_ID"Poll every few seconds, then less often, until status is ready. A ready job states the file’s size and sha256.
9. Download it and check it
curl --fail -o dataset.zip -H "X-Hey-Data-Key: $HEY_DATA_KEY" \
"$API/campaigns/$CAMPAIGN_ID/exports/$EXPORT_ID/download"
shasum -a 256 dataset.zipThe printed SHA-256 must equal the job’s sha256; if it does not, download again. An interrupted download can be resumed: see Downloading and checking a file.
The whole journey in Python
The same steps as one script, using the requests package (pip install requests). It waits out rate limits, stops on any error with the API’s own sentence, and checks the file before it trusts it.
import hashlib
import os
import time
from datetime import date, timedelta
import requests
API = os.environ['HEY_DATA_URL'].rstrip('/') + '/api/data/v1'
STANDARD_TERMS = "Use the delivered records only for the purpose stated in this campaign. Do not sell, share or sublicense the records to another party. Do not attempt to identify or contact participants, or link their records to an identified person. Delete the records by the end of the stated retention period, which must not exceed 90 days. Pay the stated USD reward once per participant when their records are first delivered. Participants can stop future deliveries; copies already delivered cannot be recalled by Hey."
session = requests.Session()
session.headers['X-Hey-Data-Key'] = os.environ['HEY_DATA_KEY']
def call(method, path, body=None, headers=None):
while True:
response = session.request(method, API + path, json=body, headers=headers, timeout=60)
if response.status_code == 429:
time.sleep(int(response.headers.get('Retry-After', '60')))
continue
if response.status_code >= 400:
raise SystemExit(f"{response.status_code}: {response.json().get('error')}")
return response.json()
def wait(path, done, every):
while not done(result := call('GET', path)):
time.sleep(every)
return result
catalog = call('GET', '/catalog')
today = date.today()
spec = {
'schema_version': 2,
'title': 'Search and purchase recommendations',
'organization': catalog['organization']['name'],
'request': 'Amazon purchases and Google searches from the same adults, to evaluate a recommendation model.',
'goal': 'recommendations', 'purpose': 'evaluation',
'sources': ['amazon', 'google'], 'source_mode': 'all',
'fields': {'amazon': ['product_name', 'quantity', 'currency'], 'google': ['title', 'type']},
'filters': {
'amazon': {'include': [], 'exclude': [], 'conditions': []},
'google': {'include': [], 'exclude': [], 'conditions': [{'field': 'type', 'op': 'eq', 'value': 'searched'}]},
},
'since': (today - timedelta(days=365)).isoformat(), 'until': today.isoformat(),
'freshness_days': 60, 'min_records': 5, 'min_days': 0,
'cohort': {'age_min': 18, 'age_max': 120, 'regions': []},
'countries': [], 'languages': [],
'target_participants': 20, 'reward_cents': 1000, 'budget_cents': 20000,
'retention_days': 30, 'deadline': (today + timedelta(days=30)).isoformat(),
'privacy': 'pseudonymous', 'format': 'parquet',
'terms': STANDARD_TERMS,
}
# One value per purchase. Retrying with it returns this campaign; it can never create a second one.
campaign = call('POST', '/campaigns', spec, headers={'Idempotency-Key': 'search-purchases-001'})
cid = campaign['id']
estimate = call('POST', f'/campaigns/{cid}/availability', {})
print('People who match so far:', 'fewer than five' if estimate['suppressed'] else estimate['participants'])
call('POST', f'/campaigns/{cid}/submit', {})
campaign = wait(f'/campaigns/{cid}', lambda c: c['status'] != 'submitted', every=300)
if campaign['status'] == 'declined':
raise SystemExit(campaign['review_note'])
if campaign['status'] == 'awaiting_funding':
checkout = call('POST', f'/campaigns/{cid}/funding/checkout', {})
print('Open this page in a browser and pay:', checkout['url'])
wait(f'/campaigns/{cid}/funding', lambda f: f['funded_cents'] == f['total_cents'], every=30)
wait(f'/campaigns/{cid}', lambda c: c['approvals'] > 0, every=900)
job = call('POST', f'/campaigns/{cid}/exports', {})
job = wait(f"/campaigns/{cid}/exports/{job['id']}", lambda j: j['status'] not in ('queued', 'running'), every=15)
if job['status'] != 'ready':
raise SystemExit(job['error'])
digest = hashlib.sha256()
with session.get(f"{API}/campaigns/{cid}/exports/{job['id']}/download", stream=True, timeout=300) as response:
response.raise_for_status()
with open('dataset.zip', 'wb') as out:
for chunk in response.iter_content(1024 * 1024):
digest.update(chunk)
out.write(chunk)
if digest.hexdigest() != job['sha256']:
raise SystemExit('The file did not arrive whole. Download it again.')
print('dataset.zip is complete:', job['sha256'])Authentication
Send your key in the X-Hey-Data-Key header on every request. Nothing else authenticates these routes: browser cookies are ignored, and there is no other header or query parameter for a key. Keys begin with hey_data_, which secret scanners can look for. Hey stores only a fingerprint of each key, so a lost key cannot be shown again; revoke it and create another.
Permissions
A key carries up to three permissions, chosen when it is created. Each request needs one of them and a role, held by the key’s creator right now, that allows the same thing in the studio.
| Permission | What it allows |
|---|---|
read | The catalog, this organization’s campaigns and their progress, funding status, a payment check, and download history. |
campaigns | Create and edit drafts, check availability, submit, start a payment, set the public page, and close a campaign. |
exports | Prepare, follow, retry and cancel exports, and download them. |
| Creator’s role | read | campaigns | exports | Start a payment | Create keys |
|---|---|---|---|---|---|
| Owner | Yes | Yes | Yes | Yes | Yes |
| Administrator | Yes | Yes | Yes | No | Yes |
| Campaign manager | Yes | Yes | Yes | No | No |
| Download only | Yes | No | Yes | No | No |
Roles are managed in the studio. A change of role applies from the key’s next request: a creator moved to Download only keeps read and exports and loses campaigns, and an owner who hands over ownership can no longer start payments with their keys.
How long a key works
- A key lasts the time chosen when it was created, from 1 day to 1 year (the studio offers 30 days, 90 days and 1 year).
- It stops working when it expires, when someone revokes it, when its creator leaves or is removed from the organization, when its creator deletes their Hey account, or when the organization closes. Rejoining does not bring an old key back.
- An organization can have 20 active keys at a time.
- The studio lists each key with who created it, when it expires, and the day it was last used.
- A request already being answered when a key is revoked may finish; every new request checks the key again.
Rate limits
- Each key: 60 requests a minute.
- Each network address, counted before the key is checked: 120 requests a minute.
- Availability checks: five an hour for each person, counted together with the studio, so a key’s checks use its creator’s own hourly allowance.
- Request bodies: 32 KiB at most.
A request over a limit answers 429 with Retry-After: 60. Wait at least that long; an availability check refused for its hourly limit works again once the hour turns over (UTC). Treat these as a ceiling to stay well under, not an allowance to spend.
Errors
Every error is JSON with one field, error, a sentence you can show a person: {"error": "Only a draft can be submitted."}. Success is 200, 201 when a campaign is created, 202 when an export is queued and 206 for part of a file.
| Status | Meaning |
|---|---|
400 | Something in the request is invalid: a missing or unexpected field, a value out of range, a body that is not JSON (or lacks Content-Type: application/json), or a missing Idempotency-Key. |
401 | No key, or a key that is unknown, expired or revoked, or whose creator no longer has access to the organization. |
403 | The key lacks the permission, or its creator’s role does not allow the action. |
404 | No such campaign or export in this key’s organization. A campaign that belongs to another organization answers 404 too. |
409 | The request conflicts with the campaign’s state: editing a campaign that is no longer a draft, an Idempotency-Key reused for different terms, a campaign that is not open, approvals that changed since an export was prepared, or nothing approved yet. |
410 | A prepared file expired. Prepare a new export. |
413 | The body is larger than 32 KiB. |
416 | The Range header is not one valid range inside the file. |
429 | Too many requests. Honor Retry-After. |
503 | Something is temporarily unavailable, or a part of the marketplace is not open yet; the sentence says which. Retry later with the same request and the same Idempotency-Key. |
Retrying safely
- Creating a campaign needs an
Idempotency-Keyheader of 8 to 128 letters, digits, dots, colons, underscores or hyphens, unique to that purchase within your organization. Sending the same JSON with the same key again returns the existing campaign (still201); the same key with different JSON is refused with409. - Submitting works once: a repeat answers
409. After a timeout, read the campaign to see whether it was submitted. - Preparing an export again while nothing has changed returns the job already under way or ready.
- Starting a payment again while the Checkout page is open returns the same page, and an expired page is replaced by a new one. Once the person has paid it answers with no
urland astatusofconfirmedorprocessing, orawaiting_transferwhile a bank transfer is on its way; a transfer that ended without arriving lets a new page start. It answers409once the campaign is funded. - Closing again leaves the campaign closed.
Endpoints
Paths are relative to /api/data/v1. {id} is a campaign’s id, {export} an export job’s id and {notice} a deletion notice’s id. Requests that send no fields take the body {}.
| Request | Permission | Creator’s role | What it does |
|---|---|---|---|
GET /catalog | read | Any role | Datasets, fields, typed filters, limitations, demographic answers, the minimum reward, Hey’s fee, your organization with its limits and how they rise, and this key’s permissions. |
GET /campaigns | read | Any role | This organization’s campaigns, newest first. |
POST /campaigns | campaigns | Owner, Administrator, Campaign manager | Create a draft from a schema-version-2 specification. Needs an Idempotency-Key. Answers 201. |
GET /campaigns/{id} | read | Any role | Status, specification, what you pay, current approvals, matching progress and the first page of download history. |
PUT /campaigns/{id} | campaigns | Owner, Administrator, Campaign manager | Replace a draft’s specification. |
POST /campaigns/{id}/availability | campaigns | Owner, Administrator, Campaign manager | Estimate who matches before you pay. Five an hour per person, counted with the studio. |
POST /campaigns/{id}/submit | campaigns | Owner, Administrator, Campaign manager | Submit a draft. |
PUT /campaigns/{id}/listing | campaigns | Owner, Administrator, Campaign manager | Turn the campaign’s public page on or off, and choose whether it names your organization. |
POST /campaigns/{id}/deadline | campaigns | Owner, Administrator, Campaign manager | Move the closing date later, up to 90 days past the date the campaign was submitted with. Approvals already given are not affected. |
GET /campaigns/{id}/funding | read | Any role | Funding status and amounts. |
POST /campaigns/{id}/funding/checkout | campaigns | Owner | A Stripe Checkout page for a person to open and pay. |
POST /campaigns/{id}/funding/refresh | read | Any role | Ask Stripe about the payment now and answer with the funding status. |
POST /campaigns/{id}/close | campaigns | Owner, Administrator, Campaign manager | Close the campaign for good. Rewards not yet earned, and Hey’s fee on them, are refunded. |
POST /campaigns/{id}/exports | exports | Any role | Prepare a file of the current approvals. Answers 202 with an export job. |
GET /campaigns/{id}/exports | exports | Any role | Export jobs this key’s creator started for the campaign, newest first. Page with ?cursor=. |
GET /campaigns/{id}/exports/{export} | exports | Any role | One export job: its progress, and once ready its size and SHA-256. |
POST /campaigns/{id}/exports/{export}/retry | exports | Any role | Try a failed preparation again. |
POST /campaigns/{id}/exports/{export}/cancel | exports | Any role | Cancel a preparation. |
GET /campaigns/{id}/exports/{export}/download | exports | Any role | Download the ZIP. Accepts one byte range. |
HEAD /campaigns/{id}/exports/{export}/download | exports | Any role | The download’s headers only. Never counts as a delivery. |
GET /campaigns/{id}/deliveries | read | Any role | Every authorized download of the campaign, newest first. Page with ?cursor=. |
GET /campaigns/{id}/notices | read | Any role | What you must delete and by when: participants who withdrew after you downloaded their records, and datasets whose licence to keep them has ended or will end. |
POST /campaigns/{id}/notices/{notice}/acknowledge | exports | Any role | Confirm you deleted what a notice names. Records that this key confirmed, and when. |
GET /campaigns/{id}/reports | read | Any role | Your reports on delivered participants’ records, how each was decided, and how many more the campaign may make. |
POST /campaigns/{id}/reports | exports | Any role | Report a problem with one delivered participant’s records before they are paid. Answers 201. |
Export jobs belong to the person who started them. A key acts as its creator, so it sees and downloads the jobs its creator started, from the studio or the API, and not a teammate’s.
Checking availability
POST /campaigns/{id}/availability estimates, before you pay, how many people who have enrolled to sell match the campaign as written. It reads at most 100 of them, so complete: false means the true number may be higher. It states participants, records per dataset and coverage only when at least 5 people match; below that they are null and suppressed is true. It also states reward_budget_cents, the rewards alone, and for a card-funded campaign total_cents, the amount Checkout will charge: the rewards plus Hey’s fee. It never returns records or says who matched, and it does not offer the campaign to anyone.
The public page
PUT /campaigns/{id}/listing with {"public": true, "show_buyer": false} gives the campaign a page anyone can open at /data/c/<public_id>, listed at /data/c. It shows the title, the uploads asked for, the pay, the closing date and roughly how full the campaign is, and your organization’s name only if show_buyer is true. It never shows the audience, the filters or a count, and it answers only while the campaign is active, funded and before its deadline. Every campaign you read carries its listing state.
Moving the closing date
POST /campaigns/{id}/deadline with {"deadline": "YYYY-MM-DD"} moves the closing date of an approved campaign, waiting for payment or open, later: up to 90 days past the date in the specification in all, never earlier, and not once joining has closed. It needs the owner or a campaign manager (manage). The new date is kept beside the specification, which keeps its own deadline and spec_hash, so no approval is affected and no participant is asked again; each approval still ends when its retention_days run out. Joining, the download window, the public page, the offer participants see and the reminders all follow the new date. Every campaign you read carries deadline, the closing date in force, and deadline_extension: original, latest (the latest date it can move to) and extensions, each move with from, to, at and by (the member’s label).
Deletion notices
GET /campaigns/{id}/notices lists what you must delete for the campaign, open notices first. There are two kinds:
withdrawal: a participant whose records you downloaded withdrew their approval or deleted their Hey account (reasoniswithdreworaccount_deleted, orreport_upheldwhen Hey upheld your report on them;occurred_atsays when). With connected records,participant_idis the id their records carry in your files; with separate records it isnull, because nothing in the files tells their records apart, and you delete each file indeliveries. Stop using their records and delete them within 30 days of the notice:delete_by.licence_ended: the licence to keep one delivered file endsretention_daysafter the day it was delivered. Until then the notice isscheduled; ondelete_byit opens and your team is emailed. Delete the file named indeliveries(its id, delivery time and SHA-256).
Every notice has id, kind, status (scheduled, open or confirmed), delete_by, deliveries, review_from, overdue, created_at, confirmed_at and confirmed_by (kind member, api_key or dataset, when the file holding the records was already confirmed deleted, and a label). When a notice opens, every member who can download is emailed, and a withdrawal gets one reminder on its deadline. Once you have deleted what it names, confirm it with POST /campaigns/{id}/notices/{notice}/acknowledge and the body {}, or with the campaign’s button in the studio; the key, or the member, is recorded with the time. Confirming again changes nothing. A notice still open 7 days after its deadline (from review_from; overdue is then true) means each campaign your organization submits is reviewed by a person at Hey instead of being approved automatically, until you confirm.
Reporting a problem with a participant’s records
If a participant’s records are wrong, report that participant before they are paid, which is 7 days after the delivery that earned it: POST /campaigns/{id}/reports with {"participant_id": "…", "reason": "…", "note": "…"}. participant_id is the id their records carry in your files, so only a campaign with connected records can be reported. reason is one of copied (the records are a copy of another participant’s), not_genuine (the records are not a real export of a person’s activity), not_requested (the records are not what the campaign asked for), and note says what you saw, in at least 20 characters. Nothing else is sent. Once the participant has been paid, the answer is a 409 that says so; email support@hey.ai.
Reports that are open or were turned down count against the campaign: up to 10% of its delivered participants, rounded up, and never fewer than 2; upheld reports do not count. GET /campaigns/{id}/reports lists the campaign’s reports with their status (open, upheld, turned_down, lapsed, or cancelled when Hey cancelled the sale for another reason) and cap, counted and remaining, how many more it may make. While a report is open the participant is not paid, and a person at Hey decides within 14 days. Upheld: the sale is cancelled, its reward and Hey’s fee go back to the campaign, and you get a deletion notice with reason report_upheld for that participant, because you are not paying for their records. Turned down, or not decided within 14 days (lapsed): the participant is paid. Every member who can download is emailed when a report is turned down or lapses.
The campaign specification
A campaign is one JSON object with exactly these fields; an unknown field is refused. Participants who are offered your campaign can read all of it, including request and terms, before they decide.
| Field | Type and limits | Meaning |
|---|---|---|
schema_version | The number 2 | The current specification. The API creates only version 2. |
title | Text, up to 120 characters | The campaign’s name. |
organization | Text, up to 160 characters | Your organization’s name exactly as GET /catalog states it. It cannot change after the draft is created. |
request | Text, up to 2,000 characters | What you are asking for and why, in plain words. |
goal | One of custom_model, personalization, memory, recommendations, forecasting | What you are building: Custom model development, personalization, memory, recommendations, research and forecasting. |
purpose | One of evaluation, training, research | What the records will be used for. Each participant chooses which uses they allow; only those who allow yours are offered it. |
sources | A list of distinct dataset ids, at least one | The datasets you want. |
source_mode | all or any | all: a person qualifies only with enough records in every dataset. any: in at least one. |
fields | An object: each dataset id to a list of its field names, at least one each | The fields delivered. Only fields listed in the catalog are accepted. |
filters | An object: each dataset id to {"include", "exclude", "conditions"} | Which records count; see Filters. Use empty lists for none. |
since, until | Dates, YYYY-MM-DD, since no later than until | Only records dated in this window are delivered. |
freshness_days | 30 or 60; optional, 60 when left out | A person’s uploads must be this recent. |
min_records | Whole number, 1 or more | Records a person needs in a dataset to qualify in it. |
min_days | Whole number, 0 to 36,500 | Days that must lie between a person’s first and last record in a dataset. |
cohort | {"age_min", "age_max", "regions"}, plus demographics if you narrow by it | Who may take part; see Audience. |
audience_rule | Optional object | A history a person must have to qualify, which is not itself delivered; see Audience. |
countries | Up to 20 two-letter codes such as US; empty for any | A participant’s country must be listed. |
languages | Up to 20 two-letter codes such as en; empty for any | A participant’s language must be listed. |
target_participants | Whole number from 1 up to your workspace’s limit, 250 participants per campaign by default (organization.limits.participants in GET /catalog) | How many people you will pay. At least 5 when you filter by demographics. Ask Hey to raise the limit. |
reward_cents | Whole number of US cents, at least min_reward_cents ($5.00 today) and at most 1,000,000 ($10,000) | What each participant earns, once, when their records are first delivered: the whole reward, since Hey’s fee is charged to you on top. Hey sends it to the participant 7 days later, unless your payment is disputed or reversed in that time. |
budget_cents | Whole number of US cents, at least reward_cents × target_participants, up to your workspace’s limit (organization.limits.budget_cents in GET /catalog, with tier and a note on how it rises): $2,500 per campaign for a new workspace, which pays for one campaign at a time; $25,000 per campaign 30 days after one of its campaigns is paid for and has delivered data, if that payment has had no dispute or other hold. A test-mode payment does not count. | Must cover every participant’s reward. The limit is on rewards; Hey’s fee comes on top. Checkout charges the rewards plus Hey’s fee, total_cents, whatever the budget. Ask Hey to raise the limit. |
retention_days | Whole number, 1 to 365 | How long each approval lasts and how long you may keep the records. The standard terms allow at most 90. |
deadline | Date, today or later | The last day people can join. You can download for 7 more days. Once the campaign is approved you can move it later; the specification keeps this date. |
privacy | pseudonymous or unlinked | Connected or separate records; see below. |
format | csv, jsonl or parquet | The format of the delivered files. All three hold the same records. |
terms | Text, up to 4,000 characters | What participants agree to. The standard terms are approved automatically. |
A draft can be replaced whole with PUT /campaigns/{id}; a submitted specification is locked, and changing it means a new campaign. An organization can hold 50 campaigns.
Filters and audience
Filters on records
includeandexclude: up to 10 words or phrases each, of up to 80 characters, matched without regard to case anywhere in the dataset’s main text (named for each dataset below). A record is kept when it contains at least oneincludeterm (or the list is empty) and noexcludeterm. Words a participant chose to keep out are removed the same way.conditions: up to 8, each{"field": …, "op": …, "value": …}, all of which a record must meet. Each dataset lists which fields take which comparisons:eqfor text and numbers,gteandltefor numbers. Numbers run from 0 to 1 trillion. Text is up to 200 characters and compared without regard to case or surrounding spaces. Some fields accept only the values the dataset lists.- Website
domainconditions take a hostname such asexample.com, compared in lowercase, without a leadingwww., and with international names in theirxn--form. Full URLs, paths, logins, IP addresses and local hosts are refused. Delivered domains carry no path, query or login either. - Filtering on a field does not deliver it; only
fieldsare delivered.
Audience
cohort.age_minandage_max: whole numbers from 18 to 120. Every participant is an adult.cohort.regions: up to 20 country-region codes such asUS-CAorCA-ON; empty for any.cohort.demographics(optional): for each fact you narrow by, the answers a participant may have, for example{"gender": ["woman"], "income_band": ["75k_100k", "100k_150k"]}. Answers are self-reported by participants and locked once they enroll; a person who has not answered a fact you filter on does not match. A campaign that filters by demographics needstarget_participantsof at least 5, and releases nothing, no export and no download, until 5 participants have approved. Delivered records never carry demographics. The facts and answers:Fact Answers gender(Gender)womanWoman;manMan;nonbinaryNon-binaryethnicity(Race or ethnicity)asianAsian;blackBlack or African American;hispanicHispanic or Latino;middle_easternMiddle Eastern or North African;nativeIndigenous or Native American;pacific_islanderPacific Islander;whiteWhite;multiracialTwo or morerelationship(Relationship)singleSingle;partneredIn a relationship;marriedMarried;divorcedDivorced or separated;widowedWidowedhousehold_size(People in your household)1Just me;22;33;44;5_plus5 or moreincome_band(Household income)under_25kUnder $25k;25k_50k$25k–$50k;50k_75k$50k–$75k;75k_100k$75k–$100k;100k_150k$100k–$150k;150k_200k$150k–$200k;over_200kOver $200keducation(Education)no_diplomaNo diploma;high_schoolHigh school;some_collegeSome college;associateAssociate degree;bachelorBachelor’s degree;masterMaster’s degree;doctorateDoctorate or professional degreeemployment(Work)full_timeEmployed full-time;part_timeEmployed part-time;self_employedSelf-employed;studentStudent;homemakerHomemaker;unemployedNot working;retiredRetiredaudience_rule(optional):{"source", "min_records", "since", "until", "filters"}. A person qualifies only if that dataset holds at leastmin_recordsof their records betweensinceanduntilthat passfilters(the same shape as above). Those matching records are not delivered; taking part only shows that the person meets the rule.
Connected or separate records
- Connected records (
"privacy": "pseudonymous"): every record carries aparticipant_id, so you can join one person’s records across the datasets of this campaign. The id is made for this campaign alone and means nothing outside it. The manifest adds a receipt per participant and counts of people by the combination of datasets they contributed. - Separate records (
"privacy": "unlinked"): noparticipant_id, no receipts and no combination counts. Everyone’s records come in one fixed sort order, so the order of a file says nothing about who contributed what.
Participants choose which of the two they accept. Someone who accepts only separate records is never offered a connected-records campaign, so a connected campaign can reach fewer people. In either mode, text, titles and the combination of a person’s records can still point to who they are.
Datasets
These are read from the same catalog GET /catalog returns, so they always match the API. One upload can hold several datasets: a Facebook upload holds 3 (facebook, facebook_page_likes, facebook_posts); a Google & Chrome upload holds 4 (google, google_chrome, google_ads, google_ad_preferences). A participant shares each dataset separately and each arrives as its own file. A dataset marked sensitive says why in one sentence, and a participant shares it only after confirming that sentence. Participants in Washington review every sale of a sensitive dataset themselves, because Washington’s health-data law asks for an authorization for each sale of data that can reveal health. A dataset whose available is false in GET /catalog cannot be asked for yet: Hey has not yet proved it can read it for a sale. Every dataset can also be narrowed by the campaign’s date window and by include and exclude terms on its main text.
Amazon purchases amazon
Items, quantities and purchase dates. Comes from the participant’s Amazon upload. Main text: product_name.
| Field | Type | Conditions |
|---|---|---|
product_name | string | None |
asin | string | eq |
quantity | number | eq gte lte |
unit_price | number | eq gte lte. Participants can keep amounts spent out; asking for or filtering on this field reaches only those who allow it. |
total_owed | number | None. Participants can keep amounts spent out; asking for or filtering on this field reaches only those who allow it. |
currency | string | eq |
order_status | string | eq |
Text. In product_name only an email address and the participant’s own name, email addresses and usernames are masked. Everything else is delivered as recorded.
Sample, not real data
{
"asin": "B0EXAMPLE1",
"currency": "USD",
"day": "2026-03-14",
"order_status": "Shipped",
"participant_id": "3f9c2a7e5b1d4c8a9e0f6b2d",
"product_name": "Insulated steel water bottle, 24 oz",
"quantity": 2,
"source": "amazon",
"total_owed": 37.98,
"unit_price": 18.99
}Netflix viewing netflix
Titles, watch dates and viewing duration. Comes from the participant’s Netflix upload. Main text: title.
| Field | Type | Conditions |
|---|---|---|
title | string | None |
series_title | string | eq |
content_type | string | eq |
duration_seconds | number | eq gte lte |
Text. Delivered exactly as recorded.
Sample, not real data
{
"content_type": "episode",
"day": "2026-03-14",
"duration_seconds": 2580,
"participant_id": "3f9c2a7e5b1d4c8a9e0f6b2d",
"series_title": "The Lighthouse Keeper",
"source": "netflix",
"title": "The Lighthouse Keeper: Season 1: Episode 3"
}Facebook ad interactions facebook
Advertiser names and interaction dates. Comes from the participant’s Facebook upload. Main text: advertiser (Advertiser).
| Field | Type | Conditions |
|---|---|---|
advertiser | string | eq |
Limitation. Facebook records show advertiser interactions, not necessarily ad clicks.
Text. Text is masked before matching and approval, as described under What is masked (text treatment version 2).
Sample, not real data
{
"advertiser": "Northwind Outdoor Supply",
"day": "2026-03-14",
"participant_id": "3f9c2a7e5b1d4c8a9e0f6b2d",
"source": "facebook"
}Facebook pages liked facebook_page_likes
Names of liked pages and the day of each like. Comes from the participant’s Facebook upload. Main text: name (Page name).
| Field | Type | Conditions |
|---|---|---|
name | string | eq |
Sensitive. Can point to health, beliefs, politics or other private matters.
Limitation. Facebook records list the pages the person liked, by the name the export gives them, and the day. Page links and page categories are not included. A page can be named after a person.
Text. Text is masked before matching and approval, as described under What is masked (text treatment version 2).
Sample, not real data
{
"day": "2026-03-14",
"name": "Riverside Trail Runners",
"participant_id": "3f9c2a7e5b1d4c8a9e0f6b2d",
"source": "facebook_page_likes"
}Facebook posts facebook_posts
The person’s own post text and posting dates. Comes from the participant’s Facebook upload. Main text: content (Post text).
| Field | Type | Conditions |
|---|---|---|
content | string | eq |
Limitation. Facebook records contain the text of posts the person wrote. A post is kept only when Facebook gave it no title, or a title that is the person’s own name followed by one of the English titles Facebook gives their own posts: an updated status; a shared link, post, memory, photo, video, album, event, reel or note; new photos or videos; or a feeling in one word, such as “is feeling grateful”. Posts on someone else’s timeline or in a group, posts whose title names a place or other people (such as “was at”, “was with” or “checked in at”, so posts that tag a friend too), posts whose title gives someone else’s name, posts with a title in another language or one Hey does not recognise, posts without text of their own and posts the export cut short are left out, so an export in another language has few or no posts to sell. When Hey cannot read the person’s own name from their Hey account or the profiles in their imports, only posts with no title are kept. Photos, links, tags, places and comments are not included. Text may still name other people.
Text. Text is masked before matching and approval, as described under What is masked (text treatment version 2).
Sample, not real data
{
"content": "Finished my first half marathon today with my sister [name]. Legs are done.",
"day": "2026-03-14",
"participant_id": "3f9c2a7e5b1d4c8a9e0f6b2d",
"source": "facebook_posts"
}Google searches & visits google
Search text, visited-page titles and dates. Comes from the participant’s Google & Chrome upload. Main text: title (Search or page title).
| Field | Type | Conditions |
|---|---|---|
title | string | None |
type | string | eq; one of searched, visited |
Limitation. Google records are searched/visited activity from My Activity/Search, not Google Ads or Chrome.
Text. Text is masked before matching and approval, as described under What is masked (text treatment version 2).
Sample, not real data
{
"day": "2026-03-14",
"participant_id": "3f9c2a7e5b1d4c8a9e0f6b2d",
"source": "google",
"title": "trail running shoes for wide feet",
"type": "searched"
}Google Chrome browsing google_chrome
Visited-page titles, website domains and dates. Comes from the participant’s Google & Chrome upload. Main text: title (Page title).
| Field | Type | Conditions |
|---|---|---|
title | string | None |
domain | string | eq |
Limitation. Chrome records are imported visits. Domains omit full URLs, paths, query strings and login details. No dwell time, devices, bookmarks or complete browsing coverage is claimed.
Text. Text is masked before matching and approval, as described under What is masked (text treatment version 2).
Sample, not real data
{
"day": "2026-03-14",
"domain": "example.com",
"participant_id": "3f9c2a7e5b1d4c8a9e0f6b2d",
"source": "google_chrome",
"title": "Trail running shoes | Example Outfitters"
}Google ad activity google_ads
Recorded ad views, visits or clicks and website domains. Comes from the participant’s Google & Chrome upload. Main text: title (Ad or page title).
| Field | Type | Conditions |
|---|---|---|
title | string | None |
type | string | eq; one of viewed, visited, clicked |
domain | string | eq |
Limitation. Actions come from the Ads activity export; views and visits are not relabeled as clicks. Coverage varies. These records do not prove conversions or advertising causation.
Text. Text is masked before matching and approval, as described under What is masked (text treatment version 2).
Sample, not real data
{
"day": "2026-03-14",
"domain": "example.net",
"participant_id": "3f9c2a7e5b1d4c8a9e0f6b2d",
"source": "google_ads",
"title": "Example Outfitters spring sale",
"type": "viewed"
}Google ad preferences google_ad_preferences
Liked or blocked ads and requests to see more or less. Comes from the participant’s Google & Chrome upload. Main text: title (Brand or topic).
| Field | Type | Conditions |
|---|---|---|
title | string | None |
action | string | eq; one of liked, blocked, more, less |
Limitation. Only explicitly recorded My Ad Center choices are included. The parser recognizes documented English action labels; unknown or localized labels are omitted.
Text. Text is masked before matching and approval, as described under What is masked (text treatment version 2).
Sample, not real data
{
"action": "more",
"day": "2026-03-14",
"participant_id": "3f9c2a7e5b1d4c8a9e0f6b2d",
"source": "google_ad_preferences",
"title": "Running shoes"
}Instagram post captions instagram
Imported post captions and dates; text only. Comes from the participant’s Instagram upload. Main text: caption (Post caption).
| Field | Type | Conditions |
|---|---|---|
caption | string | eq |
Limitation. Instagram records contain available post captions, not complete posts, images, videos, stories, comments or private messages.
Text. Text is masked before matching and approval, as described under What is masked (text treatment version 2).
Sample, not real data
{
"caption": "Sunrise hike with my sister [name] before work.",
"day": "2026-03-14",
"participant_id": "3f9c2a7e5b1d4c8a9e0f6b2d",
"source": "instagram"
}YouTube watches & searches youtube
Imported video titles, searches, activity types and dates. Comes from the participant’s YouTube upload. Main text: title (Video title or search).
| Field | Type | Conditions |
|---|---|---|
title | string | eq |
type | string | eq; one of watched, searched |
Limitation. YouTube records show watch/search history, not viewing duration, completion, enjoyment or video files. Older imports may contain titles enriched after the activity date.
Text. Text is masked before matching and approval, as described under What is masked (text treatment version 2).
Sample, not real data
{
"day": "2026-03-14",
"participant_id": "3f9c2a7e5b1d4c8a9e0f6b2d",
"source": "youtube",
"title": "how to fix a squeaky bike brake",
"type": "searched"
}LinkedIn shared posts linkedin
The person’s own shared-post text and dates. Comes from the participant’s LinkedIn upload. Main text: content (Post text).
| Field | Type | Conditions |
|---|---|---|
content | string | eq |
Limitation. LinkedIn records contain imported shared-post text, not private messages, contact lists or verified employment history.
Text. Text is masked before matching and approval, as described under What is masked (text treatment version 2).
Sample, not real data
{
"content": "Wrapped up a quarter of model evaluations with the team. Proud of what we shipped.",
"day": "2026-03-14",
"participant_id": "3f9c2a7e5b1d4c8a9e0f6b2d",
"source": "linkedin"
}Reddit comments reddit
Comment text, subreddit and posting dates. Comes from the participant’s Reddit upload. Main text: body (Comment text).
| Field | Type | Conditions |
|---|---|---|
body | string | eq |
subreddit | string | eq |
Limitation. Reddit records contain imported comments and subreddit names, not private messages, account names or comment links. Text may still identify its author.
Text. Text is masked before matching and approval, as described under What is masked (text treatment version 2).
Sample, not real data
{
"body": "Tried the ridge loop on Saturday. Message [handle] if you want the map.",
"day": "2026-03-14",
"participant_id": "3f9c2a7e5b1d4c8a9e0f6b2d",
"source": "reddit",
"subreddit": "hiking"
}Uber trips uber
City, ride type, status, distance and duration. Comes from the participant’s Uber upload. Main text: product_type (Ride type).
| Field | Type | Conditions |
|---|---|---|
city | string | eq |
product_type | string | eq |
status | string | eq |
distance_miles | number | eq gte lte |
duration_seconds | number | eq gte lte |
Limitation. Uber records describe requested trips; use status to select completed rides. Dates follow the imported request time. Exact locations, addresses and fares are excluded; fare currency is not consistently available.
Text. Text is masked before matching and approval, as described under What is masked (text treatment version 2).
Sample, not real data
{
"city": "Portland",
"day": "2026-03-14",
"distance_miles": 4.2,
"duration_seconds": 960,
"participant_id": "3f9c2a7e5b1d4c8a9e0f6b2d",
"product_type": "UberX",
"source": "uber",
"status": "completed"
}DoorDash items doordash
Merchant, item, category, quantity and dates. Comes from the participant’s DoorDash upload. Main text: item_name (Item name).
| Field | Type | Conditions |
|---|---|---|
store_name | string | eq |
item_name | string | eq |
category | string | eq |
quantity | number | eq gte lte |
Limitation. DoorDash records are item lines, not distinct orders. Categories are supplied by the export. Delivery addresses and prices are excluded; currency is not available in the current import.
Text. Text is masked before matching and approval, as described under What is masked (text treatment version 2).
Sample, not real data
{
"category": "Noodles",
"day": "2026-03-14",
"item_name": "Spicy peanut noodles",
"participant_id": "3f9c2a7e5b1d4c8a9e0f6b2d",
"quantity": 1,
"source": "doordash",
"store_name": "Corner Noodle House"
}Each sample is made up for this page from the dataset’s own field names, shown as one connected-records line; with separate records the participant_id is absent.
What a delivery contains
Each download is one ZIP file holding:
- One file per dataset, named
<dataset id>.<format>, for exampleamazon.parquet. Its columns areparticipant_id(connected records only),source,day(the record’s date,YYYY-MM-DD) and then the fields you asked for, in your order. A missing value isnull(empty in CSV). CSV files have a header row, and a text value that begins with=,+,-,@or a tab or line break gets a leading'so spreadsheets do not run it as a formula. JSONL has one record per line with its keys in alphabetical order. In Parquet,dayis a date column and numbers are 64-bit floating point. schema.json: for each dataset, each column and its type.manifest.json:schema_version,format,campaign_id,spec_hash,created_at,participants,requested_participants,records(per dataset),missing_values(per dataset and field),quality,privacy,purpose,terms,retention_days,access_expires_at(when the first approval in the file lapses),coverage(your date window),provenance,limitations,checksums(the SHA-256 of each dataset file), and where they applyparticipant_receipts,transformations,upload_freshness_daysandaudience_rule.
quality counts records per dataset and per upload, the first and last record dates, and for each field how many values are present and missing; with connected records it also counts participants by the combination of datasets and uploads they contributed. These counts describe the delivered rows, not how complete or accurate anyone’s original history is. Phone verification of participants does not prove where an uploaded file came from.
A participant receipt (connected records only) holds the campaign’s participant_id, the import versions used, the coverage dates per dataset, approved_at, access_expires_at, and snapshot_hash with snapshot_hash_version: 3. That hash proves which approved snapshot of records you received, and it is keyed to this campaign: the same person selling the same records into two campaigns produces two unrelated hashes. Nothing in a file you receive joins one participant across campaigns.
The same records cannot be contributed to one campaign from two accounts: an approval whose exact records are already in the campaign from another account is refused. Contributions of fewer than 20 records are exempt, since two people can honestly share a few identical rows.
Sample files
Test your pipeline before you pay. Every dataset has a small sample archive in each delivery format, built by the same code that builds a delivery, so it holds what a connected-records delivery holds: the dataset file, schema.json and manifest.json with its checksums and a receipt per participant. Every record and participant ID in it is made up, for 3 made-up participants with 2 records each, and nothing in it comes from anyone’s upload. Each says it is a sample: the manifest carries sample and a provenance that says so, and every record’s main text begins with the same words. One record leaves a field empty, so missing_values has something to count. A delivered archive never carries sample.
| Dataset | Sample files |
|---|---|
Amazon purchases amazon | CSV · JSONL · Parquet |
Netflix viewing netflix | CSV · JSONL · Parquet |
Facebook ad interactions facebook | CSV · JSONL · Parquet |
Facebook pages liked facebook_page_likes | CSV · JSONL · Parquet |
Facebook posts facebook_posts | CSV · JSONL · Parquet |
Google searches & visits google | CSV · JSONL · Parquet |
Google Chrome browsing google_chrome | CSV · JSONL · Parquet |
Google ad activity google_ads | CSV · JSONL · Parquet |
Google ad preferences google_ad_preferences | CSV · JSONL · Parquet |
Instagram post captions instagram | CSV · JSONL · Parquet |
YouTube watches & searches youtube | CSV · JSONL · Parquet |
LinkedIn shared posts linkedin | CSV · JSONL · Parquet |
Reddit comments reddit | CSV · JSONL · Parquet |
Uber trips uber | CSV · JSONL · Parquet |
DoorDash items doordash | CSV · JSONL · Parquet |
To check a file, delivered or sample: every file checksums lists is in the ZIP, nothing else is, and each matches its SHA-256; each dataset file holds the number of records records states, with the columns schema.json lists and days inside coverage; missing_values counts its empty values; and with connected records every participant_id has a receipt in participant_receipts. The sample files are public and need no key.
What is masked
Before a participant reviews their records, and so before you receive them, the text of every transformed dataset is treated as follows. This is the same statement the catalog and the manifest carry:
Recognizable email addresses, phone numbers, handles, web links, street addresses and long account, card or order numbers are masked before matching and approval. In posts, captions and comments the participant wrote, a name that follows a title, an introduction, a greeting, a sign-off or a relationship ("my sister …") is masked too. Their own full name, email addresses and most usernames, where their account or imports state them, are masked in every text field and website domain, and their own first or last name alone in text they wrote, searched or visited. Names in searches, page titles and catalog entries are otherwise kept. Other names and identifying context may remain. This is not anonymization; review every record.
A masked span is replaced by its kind in square brackets: [email], [link], [phone], [handle], [address], [number], [name]. A website domain that states the participant’s own name or username is delivered as [link]. Records containing words the participant chose to keep out are left out entirely. Masking takes out who the seller is and keeps the content useful; it does not make the records unidentifiable, and you must treat them as personal data.
Downloading and checking a file
- A ready export job states
sizeandsha256. The download answers with that SHA-256 as itsETag(in quotes),Content-Length,Accept-Ranges: bytesand a file name ofhey-data-<campaign id>.zip. Check the finished file againstsha256before you use it. - To resume, send one range,
Range: bytes=<bytes you already have>-, withIf-Range: "<sha256>". Append the body only to a206whoseContent-Rangestarts where your copy ends; a200is the whole file again, so start over. More than one range, or a range outside the file, answers416. HEADon the download returns the same headers and never counts as a delivery.- Every download request checks the key, its creator’s membership and role, the participants’ current approvals and their uploads, and is recorded in the campaign’s download history (
GET /campaigns/{id}/deliveries). The first authorized delivery of a participant’s records earns their reward; later downloads of the same records pay nothing more. - A file of more than 50 participants is checked 50 participants at a time and recorded 200 at a time before its first byte is sent, so it can take some minutes to start. If the request stops before the file starts, send it again: it continues from the participants already checked, and nobody is paid twice. Asking again for such a file once it has been delivered whole, to resume it or to download it once more with a key of the same creator, sends the same file as the same delivery: nothing more is recorded, and the download history keeps one entry for it.
- A prepared file can be downloaded until the job’s
expires_at: 24 hours after it was requested, or sooner if an approval in it lapses first. Afterwards it answers410; prepare a new export. - One export is at most 2 GiB. A larger one is refused before anything is issued; arrange a bulk delivery with Hey.
- Export jobs move through
queuedandrunningtoready, or endfailed(retry it, up to three attempts in all),blocked(something it relied on changed, such as an approval, or a rule such as the demographic minimum is not met yet;errorsays what),expiredorcancelled. A queued job may carrydispatch_wait_until, when it will next try to start.
Lifecycle and money
| Status | Meaning |
|---|---|
draft | Being written. Only a draft can be edited or submitted. |
submitted | Waiting for a manual review by Hey, because the campaign uses custom terms or touches a sensitive topic. On the standard terms a submitted campaign is approved automatically and does not wait here. |
declined | The review declined it; review_note says why. Write a new draft. |
awaiting_funding | Approved. Pay to open it; you can pay as soon as it is approved. |
active | Funded and open. People who match are offered it until the closing date (deadline on the campaign), and you can download what they approved until 7 days after the deadline. |
closed | Closed by your team, at the end of the download window, or because the organization closed. A closed campaign stays closed. |
The standard terms
A submitted campaign whose terms are exactly this text, with retention_days of 90 or fewer, is on the standard terms. GET /catalog returns the text as standard_terms.text:
Use the delivered records only for the purpose stated in this campaign. Do not sell, share or sublicense the records to another party. Do not attempt to identify or contact participants, or link their records to an identified person. Delete the records by the end of the stated retention period, which must not exceed 90 days. Pay the stated USD reward once per participant when their records are first delivered. Participants can stop future deliveries; copies already delivered cannot be recalled by Hey.
Paying and being refunded
- Hey’s fee. Hey’s fee is 30% of what you pay per participant, charged on top of the reward, which the participant is paid in full. For a reward of R cents the fee is R ×
fee_bps/ (10,000 −fee_bps), rounded half up to the cent, withfee_bps3000 inGET /catalog: a $35.00 reward costs you $50.00, and Hey keeps $15.00. Every campaign you read carriesprice:fee_bps,reward_cents,fee_centsandprice_centsper participant, andtotal_cents, the price timestarget_participants. A campaign keeps the fee it was created with; one made before the fee carriesfee_bps0. The workspace limits are on rewards alone. - Funding.
POST /funding/checkoutgives a Stripe Checkout page with two lines, the participant rewards and Hey’s fee; a person pays it in a browser, by card or, when total_cents is $2,000 or more, by bank transfer. It chargestotal_cents, in US dollars, and asks a card’s bank for 3-D Secure. When Stripe confirms the payment the campaign becomesactive. A bank transfer is confirmed when the money arrives, which can take days; meanwhile the campaign staysawaiting_fundingand nothing else can be paid for it. If the money has not arrived within 10 days, or by the closing date, Stripe’s payment is cancelled and you can start a new one. - Invoices. Checkout asks for the billing address, lets the person paying add a tax ID, and creates an invoice for the payment, made out to your organization. Hey computes no tax on it. Once the payment is confirmed,
GET /fundinglinks it asinvoice:number,hosted_url(Stripe’s page for it) andpdf_url; a payment made before invoices hasnull. - Who pays when. A new workspace pays for one campaign at a time: until it is established, checkout (and submit) answer
409while another of its campaigns, or a paid campaign of anyone in it in another new workspace or outside a workspace, is paid for or has a checkout started and is not closed.GET /fundingreportsstatus(unfunded,checkout_pending,funded,refundingorrefunded),currency, the campaign’spricefields (fee_bps,reward_cents,fee_cents,price_cents,total_cents),budget_cents(the rewards),platform_fee_cents(Hey’s fee on every place),funded_cents,reserved_cents(places held at their price),earned_cents(rewards earned),fee_earned_cents(Hey’s fee on those),remaining_cents,refund_due_cents,refunded_cents,closed,hold,test_mode,available(whether payments are open),paid_by(cardorbank_transferonce paid, otherwisenull),bank_transfer_offered,bank_transfer(while unpaid:{"status": "awaited", "since", "until"}or{"status": "ended", "ended_at"}, otherwisenull; never bank details) andinvoice. - Approvals. A participant’s exact records are approved either by the participant, after previewing them, or automatically under a standing permission they gave for campaigns on the standard terms. Each approval reserves one place, its reward and Hey’s fee, and lasts
retention_days. The campaign takes approvals up totarget_participants. - Earning. A participant earns their reward when their records are first delivered to you in an authorized download. Hey sends it to the participant 7 days later, unless your payment is disputed or reversed in that time. Hey earns its fee for that participant at the same moment. An earned reward and its fee are not refunded when the campaign closes; reserved rewards that are never delivered are not paid.
- Closing and refunds.
POST /closeends the campaign at once: nobody new can join, nothing more can be downloaded, and approvals not yet delivered are released. Download what you need first. Everything not earned, rewards and Hey’s fee alike, is refunded to the payment it came from, by Hey’s scheduled payment check or straight away onPOST /funding/refresh. The same happens on its own when the download window ends. - Holds. A dispute or an unexpected refund on the payment puts the funding on hold (
hold: true), and deliveries stop until Hey resolves it. While it is on hold, no reward is sent to a participant and nothing is refunded. - When a participant changes their mind. A participant can revoke their approval at any time, and it also stops counting if they change their uploads, their sharing choices or their profile. A new export leaves them out; a file prepared before the change can no longer be downloaded, so prepare a new one. Records you have already downloaded cannot be recalled, and a reward already earned stays earned. When a participant whose records you downloaded revokes or deletes their account, you get a deletion notice.
- When a key is revoked. Its next request answers
401. A download already being answered may finish.
Your obligations
- Your use of the records is governed by the Hey Data buyer licence, which your organization accepted when it was created, and by each campaign’s own
terms, which every participant agreed to. - Retention. Delete each delivered file by the end of the campaign’s retention period,
retention_daysfrom the day it was delivered, which the manifest repeats. The standard terms allow at most 90 days. On that day a deletion notice opens; confirm it once the file is deleted. - Withdrawals. When we notify you that a participant withdrew, stop using their records and delete them within 30 days of the notice, then confirm it. A notice left unconfirmed 7 days after its deadline sends your organization’s next campaigns to a person for review until you confirm.
- Use the records only for the campaign’s stated
purpose, and treat them as personal data: masking does not make them unidentifiable. - Keep your keys secret and revoke any you no longer use.
What the API does not do
- No webhooks. The API never calls you. Poll campaigns, funding and exports, starting every few seconds and slowing down to minutes.
- No payment by key. A person pays on the Stripe Checkout page in a browser, by card, or by bank transfer when the total is $2,000 or more.
- The studio only: creating the organization and accepting the licence, its details, team members and invitations, and creating or revoking keys.
- Delivery to your own cloud bucket is set up with Hey on request; it is not part of the API.
- No look at records before people approve. Availability gives counts only, and only when at least 5 people match.
- No changes for participants. A key cannot approve, decline or change anything on a participant’s behalf.
- No earlier specification. The API creates only
schema_version2 campaigns, and a submitted specification cannot be edited.
Questions about the API: support@hey.ai.