API guide
Sampling API v2 · base URL https://api.relay-dsa.com/v2
Overview
The Relay DSA Sampling API fields your online surveys with a panel. You send your survey link and the number of completes you need; we set up and run the fieldwork, measure incidence rate (IR) and length of interview (LOI), and report the results.
Every survey runs in two phases:
- Launch – a small test field that measures the real IR and LOI.
- Resume – the main field for the remaining completes, priced with the measured values.
Field reference with every parameter: Swagger reference · machine-readable: openapi.json.
Authentication and environments
Send your API key in the Authorization header on every request:
Authorization: Bearer rdsa_test_…
| Key prefix | Environment | Effect |
|---|---|---|
rdsa_test_ | staging | Full flow on the panel's test system. No real respondents, no fieldwork costs. Use it to build and test your integration. |
rdsa_live_ | production | Real fieldwork, billed per complete. |
The key decides the environment. A survey is only visible with a key of the same company and environment. Keys are issued and revoked by the Relay DSA team; a key is shown once – store it as a secret. Never put the key into a URL or a request body.
Base URL: https://api.relay-dsa.com/v2
Quick start
1. Check your key
curl https://api.relay-dsa.com/v2/company -H "Authorization: Bearer $KEY"
2. Create a survey (starts the launch phase)
curl https://api.relay-dsa.com/v2/surveys \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: my-study-42-create" \
-d '{
"survey_name": "Pet owners Chicago",
"n": 300,
"length_of_interview": 10,
"survey_link": "https://survey.example.com/s/42",
"country": "US",
"external_id": "42"
}'
The answer (HTTP 202) contains the survey with its id and the launch phase in status draft.
3. Wait for the launch phase
curl https://api.relay-dsa.com/v2/surveys/1000001 -H "Authorization: Bearer $KEY"
Poll every few minutes (not more often than once a minute). The launch phase goes draft → in_progress → done. When it is done, actual holds the measured completes, IR, LOI and price.
4. Start the resume phase
curl -X POST https://api.relay-dsa.com/v2/surveys/1000001/start -H "Authorization: Bearer $KEY" -H "Idempotency-Key: my-study-42-start"
The resume phase fields the remaining completes (n minus the launch completes). Optionally send {"n": 400} to change the total.
Survey and phase status
| Phase status | Meaning |
|---|---|
draft | Being set up on the panel. |
in_progress | In field. |
done | Finished; actual holds completes, IR, LOI and price. |
failed | Could not be started. The team has been notified and will contact you. |
Prices are in your company currency (currency on the survey). totals on the survey sum up both phases; expected_price is the price for the full N with the measured values.
Targeting
Without targeting a survey is fielded to the general population of the market (all genders, ages 18–99, all incomes, all regions, balanced to census). With targeting you decide who may enter (qualifications) and how many of each group you want (quotas).
Step 1: read the catalog of your market
curl "https://api.relay-dsa.com/v2/targeting/qualifications?country=US&language=en" -H "Authorization: Bearer $KEY"
Markets: US, UK (en), DE (de), FR (fr), ES (es), IT (it). The catalog lists every attribute you can use:
{
"catalog_version": "3f9a1c0d2b7e4a55",
"qualifications": [
{ "qualification_code": 211, "name": "Gender", "type": "single_select",
"supported_operators": ["in", "not_in"],
"conditions": [
{ "condition_code": "111", "name": "Male", "is_nonanswer": false },
{ "condition_code": "112", "name": "Female", "is_nonanswer": false },
{ "condition_code": "113", "name": "Prefer not to say", "is_nonanswer": true } ] },
{ "qualification_code": 212, "name": "Age", "type": "number",
"supported_operators": ["between"], "range": { "minimum": 18, "maximum": 99, "unit_code": 311 } },
{ "qualification_code": 229, "name": "Postal code", "type": "postal_code",
"supported_operators": ["in"], "value_format": { "regex": "/^\\d{5}$/i" } }
]
}
Which attributes are offered differs per market and environment (staging can offer more for testing) – always build from the catalog, never from codes copied from elsewhere. The codes in the examples below are illustrations.
Keep catalog_version: you send it with every targeted survey. The catalog changes rarely; read it once a day or when a request tells you it changed.
Step 2: build the qualifications
Separate qualifications are combined with AND. Values inside one qualification are combined with OR.
| Attribute type | Operator | Send | Meaning |
|---|---|---|---|
| single_select | in | condition_codes | the person's answer is one of the codes |
| single_select | not_in | condition_codes | any answer except these codes – and except non-answers such as “Prefer not to say” (is_nonanswer: true). To include non-answers, use in with their codes. |
| multi_select | contains_any | condition_codes | the person has at least one of the codes |
| number | between | range_sets | the value lies in one of the ranges (inclusive) |
| postal_code | in | values | the postal code is in the list (max. 2000 per survey) |
Units in range_sets: age 311 (years). Income uses the unit of your company currency: USD 321, EUR 322, GBP 323 (unit_codes_by_currency in the catalog).
Codes exactly as in the catalog: "6", not "06". Postal codes keep their leading zeros ("02108").
Step 3 (optional): add quotas
A quota asks for a number of completes for one group. Rules:
- Each quota has exactly one criterion (interlocked quotas such as “women aged 25–34” are not supported).
- The quotas on one attribute must cover all its allowed values, without gaps or overlaps, and their
required_countmust add up ton. Allowed values are your qualification on that attribute; if you do not target it, the default (e.g. gender 111, 112 and 113, age 18–99). - Quotas are scaled to each phase. A quota that would get 0 completes in the launch phase is rejected – make it larger or remove it.
- When you target or quota an attribute, our default census balancing for that attribute is switched off (geography counts as one attribute: targeting states switches off region balancing). All other attributes stay census-balanced.
Step 4: send the survey
{
"survey_name": "Pet owners Chicago",
"n": 300,
"length_of_interview": 10,
"survey_link": "https://survey.example.com/s/42",
"country": "US",
"targeting": {
"catalog_version": "3f9a1c0d2b7e4a55",
"qualifications": [
{ "qualification_code": 1031, "operator": "contains_any", "condition_codes": ["112", "212"] },
{ "qualification_code": 212, "operator": "between", "range_sets": [ { "from": 25, "to": 54, "units": 311 } ] },
{ "qualification_code": 229, "operator": "in", "values": ["60601", "60602", "60603"] }
],
"quotas": [
{ "id": "cats", "required_count": 200, "criteria": [ { "qualification_code": 1031, "operator": "contains_any", "condition_codes": ["112"] } ] },
{ "id": "dogs", "required_count": 100, "criteria": [ { "qualification_code": 1031, "operator": "contains_any", "condition_codes": ["212"] } ] }
]
}
}
The request is checked completely before anything is created. If something cannot be met exactly, you get one 400 with every finding – we never widen or swap your targeting silently:
{ "error": { "code": "invalid_request", "field": "targeting",
"message": "qualifications[1] (qualification_code 225): unknown condition_codes 06 (codes are written without leading zeros: \"06\" → \"6\") | quotas on qualification_code 211: values 113 are not covered by any quota" } }
The targeting of a survey is fixed at creation. The resume phase uses exactly the same targeting; quotas are scaled to the resume N.
catalog_version
Send the version you built the request on. If the catalog changed meanwhile, the request is still accepted when the attributes you use did not change; otherwise you get a 400 naming the changed codes and the current version – read the catalog again and rebuild.
Not supported
contains_all,contains_noneand distance targeting (within_radius) – rejected with a reason.missing_value_policy– rejected until the panel confirms how people without a value are treated.- Attributes that depend on another attribute are not in the catalog.
Recontact: invite people back
Run a short screening survey A, pick the people who fit, and invite only them to survey B.
- Respondent ids: the panel appends
psid(andtransaction_id) to your survey link for every person who enters survey A. Store thepsidwith the answers – it is therespondent_idyou send back. - Create survey B without an open launch phase:
The answer is 201 – nobody is invited yet.{ "survey_name": "Cat food follow-up", "n": 150, "length_of_interview": 10, "survey_link": "https://survey.example.com/s/43", "country": "US", "launch_mode": "resume_only", "expected_incidence_rate": 80 }expected_incidence_rateis required because there is no launch phase to measure it. - Start survey B with your list:
Only people who took part in one of your surveys can be invited. The answer tells you who was accepted and why others were not (POST /surveys/{id}/start { "respondent_selection": { "mode": "include", "source_survey_ids": [1000001], "respondent_ids": ["7f2a…", "91bc…"] } }invalid,duplicate,unknown_respondent). Nobody else can enter survey B; it is never topped up with other panelists. - Add people while B is in field:
POST /surveys/{id}/respondentswith{"respondent_ids": [...]}. Sending an id twice is harmless. Stop adding when B is close to its target.
Errors, retries and limits
Every error has the same shape: { "error": { "code", "message", "field"? } }.
| HTTP | code | What to do |
|---|---|---|
| 400 | invalid_request | Fix the request; field names the field. |
| 401 | unauthorized | Check the key (prefix, revoked?). |
| 404 | not_found | Unknown survey, or one of another company/environment. |
| 409 | conflict | Wrong state, e.g. starting before the launch phase is done, or a second start. |
| 413 | payload_too_large | Body over 64 KB. |
| 422 | idempotency_mismatch | The Idempotency-Key was used with another body; use a new key. |
| 429 | rate_limited | Wait Retry-After seconds (limit: 120 requests per minute and key). |
| 500 / 503 | internal_error | Retry later with the same Idempotency-Key. |
Idempotency-Key
Send a unique Idempotency-Key (1–200 characters) with every POST. If a request times out, repeat it with the same key and body: you get the stored answer (header Idempotent-Replayed: true) and never a second survey or a second start. After a 5xx the key is released and the retry runs again.