{"openapi":"3.1.0","info":{"title":"Relay DSA – Sampling API","version":"2.0.0","description":"API to field online surveys: create a survey (launch phase), start the main phase (resume), read results, target panelists and invite people back (recontact).\n\n**New here?** Read the [API guide](https://developers.relay-dsa.com/) first: quick start, targeting step by step, recontact, errors and retries.\n\n**Authentication:** `Authorization: Bearer <API key>`. Keys start with `rdsa_live_` (production) or `rdsa_test_` (staging, no real fieldwork costs) and are issued by the Relay DSA team. The key decides the environment; a survey is only visible with a key of its own company and environment.\n\n**Flow:** `POST /surveys` → launch phase (small test field to measure incidence rate and length of interview) → wait until the launch phase is `done` (`GET /surveys/{id}`) → `POST /surveys/{id}/start` → resume phase until N is reached.\n\n**Errors** always have the shape `{ \"error\": { \"code\", \"message\", \"field\"? } }`. Requests that cannot be met exactly are declined with a reason; nothing is silently widened or replaced."},"servers":[{"url":"https://api.relay-dsa.com/v2","description":"Production and staging (the API key decides)"}],"security":[{"apiKey":[]}],"tags":[{"name":"Company","description":"The company behind the API key."},{"name":"Surveys","description":"Create, start and read surveys."},{"name":"Targeting","description":"Attributes you can target, per market. Send them as `targeting` with POST /surveys."},{"name":"Recontact","description":"Invite people from earlier surveys back: POST /surveys with launch_mode resume_only, then POST /surveys/{id}/start with respondent_selection, then add more people here."}],"paths":{"/company":{"get":{"tags":["Company"],"operationId":"getCompany","summary":"Company of the API key","responses":{"200":{"description":"The company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (120 requests per minute and key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Internal error. The team has been notified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/surveys":{"get":{"tags":["Surveys"],"operationId":"listSurveys","summary":"List surveys","description":"Surveys of your company in the key's environment, newest first.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"next_cursor of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"One page of surveys.","content":{"application/json":{"schema":{"type":"object","required":["items","next_cursor"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Survey"}},"next_cursor":{"type":["string","null"]}}}}}},"400":{"description":"Invalid limit or cursor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (120 requests per minute and key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Internal error. The team has been notified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Surveys"],"operationId":"createSurvey","summary":"Create a survey","description":"Creates the survey and starts its launch phase. With `targeting` the request is checked against the catalog first; every finding is returned in one 400. With `launch_mode: resume_only` (recontact) only the survey is created – nobody is invited until `POST /surveys/{id}/start` with a `respondent_selection`.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional, 1–200 characters. Repeating a request with the same key and the same body returns the stored answer (header `Idempotent-Replayed: true`) and never creates a second survey. The same key with a different body → 422; while the first request is still running → 409.","schema":{"type":"string","minLength":1,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSurveyRequest"}}}},"responses":{"201":{"description":"Recontact survey created (no phase, no fieldwork yet).","content":{"application/json":{"schema":{"type":"object","properties":{"survey":{"$ref":"#/components/schemas/Survey"}}}}}},"202":{"description":"Survey created, launch phase started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartedSurvey"}}}},"400":{"description":"Invalid input, a targeting finding or a value that cannot be priced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body larger than 64 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (120 requests per minute and key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Internal error. The team has been notified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/surveys/{id}":{"get":{"tags":["Surveys"],"operationId":"getSurvey","summary":"Get a survey with its phases","parameters":[{"name":"id","in":"path","required":true,"description":"Survey id.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"The survey.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Survey"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown survey (or one of another company or environment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (120 requests per minute and key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Internal error. The team has been notified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/surveys/{id}/start":{"post":{"tags":["Surveys"],"operationId":"startSurvey","summary":"Start the resume phase (or a recontact survey)","description":"Standard survey: starts the resume phase for the remaining completes (n minus launch completes), priced with the measured incidence rate and length of interview. Allowed once, after the launch phase is `done`.\n\nRecontact survey (`launch_mode: resume_only`): starts the single fieldwork phase for the people in `respondent_selection`. Only people who took part in one of your earlier surveys can be invited; the answer lists who was accepted and why others were not.","parameters":[{"name":"id","in":"path","required":true,"description":"Survey id.","schema":{"type":"integer","minimum":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional, 1–200 characters. Repeating a request with the same key and the same body returns the stored answer (header `Idempotent-Replayed: true`) and never creates a second survey. The same key with a different body → 422; while the first request is still running → 409.","schema":{"type":"string","minLength":1,"maxLength":200}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSurveyRequest"}}}},"responses":{"202":{"description":"Phase started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartedSurvey"}}}},"400":{"description":"Invalid input, n not above the launch completes, or nobody in respondent_selection can be invited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown survey.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Started already, launch phase not done yet, or the measured values cannot be priced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (120 requests per minute and key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Internal error. The team has been notified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/surveys/{id}/respondents":{"post":{"tags":["Recontact"],"operationId":"addRespondents","summary":"Invite more people to a running recontact survey","description":"Idempotent per id: ids that are already invited count as accepted and are not sent twice. Stop adding people when the survey is close to its target.","parameters":[{"name":"id","in":"path","required":true,"description":"Survey id.","schema":{"type":"integer","minimum":1}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional, 1–200 characters. Repeating a request with the same key and the same body returns the stored answer (header `Idempotent-Replayed: true`) and never creates a second survey. The same key with a different body → 422; while the first request is still running → 409.","schema":{"type":"string","minLength":1,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddRespondentsRequest"}}}},"responses":{"200":{"description":"Invitations recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"survey_id":{"type":"integer"},"respondent_selection":{"$ref":"#/components/schemas/SelectionResult"}}}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown survey.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Not a recontact survey, not started yet, or already completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (120 requests per minute and key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Internal error. The team has been notified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/targeting/qualifications":{"get":{"tags":["Targeting"],"operationId":"getTargetingCatalog","summary":"Targeting attributes of a market","description":"The attributes you can target in a market, with codes, labels, type, allowed operators and values. Send `catalog_version` with your targeting; requests built on an older version are accepted only if the attributes you use did not change.","parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string","enum":["US","UK","DE","FR","ES","IT"]}},{"name":"language","in":"query","required":true,"description":"Market language: en for US/UK, de, fr, es, it.","schema":{"type":"string","example":"en"}}],"responses":{"200":{"description":"The catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}},"400":{"description":"Unknown country or wrong language.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (120 requests per minute and key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"500":{"description":"Internal error. The team has been notified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Catalog temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key issued by Relay DSA (`rdsa_live_…` or `rdsa_test_…`). Only in the Authorization header."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","invalid_request","conflict","idempotency_mismatch","idempotency_in_progress","rate_limited","payload_too_large","unprocessable","internal_error"]},"message":{"type":"string"},"field":{"type":"string","description":"Request field the error refers to, if any."}}}}},"Company":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"email":{"type":["string","null"]},"currency":{"type":"string","enum":["USD","EUR"]},"email_recipients":{"type":"array","items":{"type":"string","format":"email"}},"environment":{"type":"string","enum":["production","staging"]}}},"CreateSurveyRequest":{"type":"object","additionalProperties":false,"required":["survey_name","n","length_of_interview","survey_link","country"],"properties":{"survey_name":{"type":"string","maxLength":200,"example":"Pet owners, Chicago"},"n":{"type":"integer","minimum":1,"maximum":100000,"description":"Total completes (launch + resume)."},"length_of_interview":{"type":"number","minimum":1,"maximum":35,"description":"Estimated minutes."},"survey_link":{"type":"string","format":"uri","description":"http:// or https:// link of your survey."},"country":{"type":"string","enum":["US","UK","DE","FR","ES","IT"],"description":"Case-insensitive."},"external_id":{"type":"string","maxLength":100,"description":"Your own id; becomes part of the survey name."},"additional_recipients":{"type":"array","maxItems":20,"items":{"type":"string","format":"email"},"description":"Receive the phase mails in addition to your company recipients."},"targeting":{"$ref":"#/components/schemas/Targeting"},"launch_mode":{"type":"string","enum":["standard","resume_only"],"default":"standard","description":"resume_only = recontact survey without an open launch phase."},"expected_incidence_rate":{"type":"integer","minimum":1,"maximum":100,"description":"Required with launch_mode resume_only (there is no launch phase to measure it)."}}},"Targeting":{"type":"object","additionalProperties":false,"required":["catalog_version"],"description":"Separate qualifications are combined with AND; values inside one qualification with OR. Not combinable with launch_mode resume_only.","properties":{"catalog_version":{"type":"string","description":"catalog_version of GET /targeting/qualifications."},"qualifications":{"type":"array","maxItems":50,"items":{"type":"object","additionalProperties":false,"required":["qualification_code","operator"],"description":"One targeting criterion. Use exactly one of condition_codes (single/multiple choice), values (postal codes) or range_sets (numbers). Codes and operators come from GET /targeting/qualifications.","properties":{"qualification_code":{"type":"integer","example":211},"operator":{"type":"string","enum":["in","not_in","contains_any","between"],"description":"contains_all, contains_none and within_radius are not supported and are rejected with a reason."},"condition_codes":{"type":"array","items":{"type":"string"},"example":["111"],"description":"Exactly as listed in the catalog (no leading zeros: \"6\", not \"06\")."},"values":{"type":"array","items":{"type":"string"},"example":["60601","02108"],"description":"Postal codes; must match the catalog's value_format.regex. At most 2000 per survey."},"range_sets":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["from","to","units"],"properties":{"from":{"type":"integer"},"to":{"type":"integer"},"units":{"type":"integer","description":"Age 311; income: the unit of your company currency (USD 321, EUR 322, GBP 323)."}}}}}}},"quotas":{"type":"array","maxItems":100,"description":"Quotas on one attribute must cover all its allowed values without gaps or overlaps, and their required_count must add up to n. Exactly one criterion per quota.","items":{"type":"object","additionalProperties":false,"required":["id","required_count","criteria"],"properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"required_count":{"type":"integer","minimum":1},"criteria":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","additionalProperties":false,"required":["qualification_code","operator"],"description":"One targeting criterion. Use exactly one of condition_codes (single/multiple choice), values (postal codes) or range_sets (numbers). Codes and operators come from GET /targeting/qualifications.","properties":{"qualification_code":{"type":"integer","example":211},"operator":{"type":"string","enum":["in","not_in","contains_any","between"],"description":"contains_all, contains_none and within_radius are not supported and are rejected with a reason."},"condition_codes":{"type":"array","items":{"type":"string"},"example":["111"],"description":"Exactly as listed in the catalog (no leading zeros: \"6\", not \"06\")."},"values":{"type":"array","items":{"type":"string"},"example":["60601","02108"],"description":"Postal codes; must match the catalog's value_format.regex. At most 2000 per survey."},"range_sets":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["from","to","units"],"properties":{"from":{"type":"integer"},"to":{"type":"integer"},"units":{"type":"integer","description":"Age 311; income: the unit of your company currency (USD 321, EUR 322, GBP 323)."}}}}}}}}}}},"example":{"catalog_version":"3f9a1c0d2b7e4a55","qualifications":[{"qualification_code":212,"operator":"between","range_sets":[{"from":25,"to":54,"units":311}]}],"quotas":[{"id":"men","required_count":150,"criteria":[{"qualification_code":211,"operator":"in","condition_codes":["111"]}]},{"id":"women","required_count":150,"criteria":[{"qualification_code":211,"operator":"in","condition_codes":["112","113"]}]}]}},"StartSurveyRequest":{"type":"object","additionalProperties":false,"properties":{"n":{"type":"integer","minimum":1,"maximum":100000,"description":"New total N (optional)."},"respondent_selection":{"$ref":"#/components/schemas/RespondentSelection"}}},"RespondentSelection":{"type":"object","additionalProperties":false,"required":["mode","respondent_ids"],"description":"Recontact surveys only. respondent_id = the `psid` appended to your entry link in earlier surveys.","properties":{"mode":{"type":"string","enum":["include"]},"source_survey_ids":{"type":"array","maxItems":100,"items":{"type":"integer"},"description":"Optional: only people from these surveys."},"respondent_ids":{"type":"array","minItems":1,"maxItems":10000,"items":{"type":"string"}}}},"AddRespondentsRequest":{"type":"object","additionalProperties":false,"required":["respondent_ids"],"properties":{"respondent_ids":{"type":"array","minItems":1,"maxItems":10000,"items":{"type":"string"}}}},"SelectionResult":{"type":"object","properties":{"requested":{"type":"integer"},"accepted":{"type":"integer"},"rejected":{"type":"array","items":{"type":"object","properties":{"respondent_id":{"type":"string"},"reason":{"type":"string","enum":["invalid","duplicate","unknown_respondent"]}}}},"newly_added":{"type":"integer","description":"POST /respondents only: ids that were not on the list before."}}},"StartedSurvey":{"type":"object","properties":{"survey":{"$ref":"#/components/schemas/Survey"},"run":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}},"respondent_selection":{"$ref":"#/components/schemas/SelectionResult"}}},"Phase":{"type":"object","properties":{"phase":{"type":"string","enum":["launch","resume"]},"status":{"type":"string","enum":["draft","in_progress","done","failed"],"description":"draft = being set up, in_progress = in field, done = finished with actual values, failed = could not be started."},"n":{"type":["integer","null"]},"estimated":{"type":"object","properties":{"length_of_interview":{"type":["number","null"]},"incidence_rate":{"type":["number","null"]},"price":{"type":["number","null"]}}},"actual":{"type":"object","properties":{"n":{"type":["integer","null"]},"length_of_interview":{"type":["number","null"]},"incidence_rate":{"type":["number","null"]},"price":{"type":["number","null"]}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Survey":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"external_id":{"type":["string","null"]},"n":{"type":"integer"},"survey_link":{"type":"string"},"country":{"type":"string"},"environment":{"type":"string","enum":["production","staging"]},"launch_mode":{"type":"string","enum":["standard","resume_only"]},"currency":{"type":"string","enum":["USD","EUR"],"description":"Currency of all prices."},"email_recipients":{"type":"array","items":{"type":"string"}},"totals":{"type":"object","properties":{"completes":{"type":["integer","null"]},"price":{"type":["number","null"]},"incidence_rate":{"type":["number","null"]},"length_of_interview":{"type":["number","null"]},"expected_price":{"type":["number","null"]}}},"phases":{"type":"array","items":{"$ref":"#/components/schemas/Phase"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Catalog":{"type":"object","properties":{"catalog_version":{"type":"string"},"country":{"type":"string"},"language":{"type":"string"},"environment":{"type":"string","enum":["production","staging"]},"fetched_at":{"type":"string","format":"date-time"},"stale":{"type":"boolean","description":"true: served from cache while a refresh runs."},"notes":{"type":"array","items":{"type":"string"}},"qualifications":{"type":"array","items":{"type":"object","properties":{"qualification_code":{"type":"integer"},"name":{"type":"string"},"name_en":{"type":"string"},"type":{"type":"string","enum":["single_select","multi_select","number","postal_code"]},"allowed_in":{"type":"array","items":{"type":"string","enum":["qualifications","quotas"]}},"supported_operators":{"type":"array","items":{"type":"string","enum":["in","not_in","contains_any","between"]}},"conditions":{"type":"array","items":{"type":"object","properties":{"condition_code":{"type":"string"},"name":{"type":"string"},"name_en":{"type":"string"},"is_nonanswer":{"type":"boolean","description":"e.g. 'Prefer not to say'; excluded by not_in."}}}},"range":{"type":"object","properties":{"minimum":{"type":"integer"},"maximum":{"type":"integer"},"unit_code":{"type":"integer"},"unit_codes_by_currency":{"type":"object","additionalProperties":{"type":"integer"}}}},"value_format":{"type":"object","properties":{"regex":{"type":"string"}}}}}}}}}}}