{ "openapi": "3.0.3", "info": { "title": "RapidoReach advertiser surveys API", "version": "1.0.0", "description": "## Authentication and base URL\n\nThe existing advertiser survey campaign API lives at `/api/v1/campaigns`. Use your advertiser Settings → Security `X-Api-Key` and secret over HTTPS. This is separate from the Offers V2 HMAC header protocol and dashboard login.\n\nSign the exact full HTTPS URL **before adding enc**, including any query filters. Append `JSON.stringify(body)` (empty string for no body or `{}`), then the advertiser secret. Compute a hex hash using the configured `url_security_encryption_type`: enc_sha1 → SHA1, enc_sha2 → SHA256, enc_sha3 → SHA3-256. Add `?enc=DIGEST`, or `&enc=DIGEST` after existing query fields; enc must be last. Preserve query encoding/order and body property order. Legacy SHA3 signatures remain accepted for compatibility. This legacy protocol has no timestamp/nonce protection and does not bind the HTTP method; do not share or log signed URLs. Offers V2 uses a stronger method-bound timestamp/nonce protocol.\n\n```js\nimport { createHash } from 'node:crypto';\nconst url = 'https://www.rapidoreach.com/api/v1/campaigns/create';\nconst body = { name: 'Example study', country_language_id: 'en_US', cpi: 1.5,\n length_of_interview: 10, conversion: 20, start_date: '2026-10-03', end_date: '2026-10-15',\n survey_live_link: 'https://survey.example/live?transaction={transaction_id}',\n survey_test_link: 'https://survey.example/test?transaction={transaction_id}', max_daily_completes: 50 };\nconst json = JSON.stringify(body);\nconst enc = createHash('sha256').update(url + json + process.env.RAPIDOREACH_ADVERTISER_SECRET).digest('hex');\n// SHA256 is for enc_sha2 accounts; use your account's configured algorithm.\nconst result = await fetch(`${url}?enc=${enc}`, { method:'POST',\n headers:{'Content-Type':'application/json', 'X-Api-Key':process.env.RAPIDOREACH_ADVERTISER_KEY}, body:json });\nconsole.log(await result.json());\n```\n\n## End-to-end survey setup\n\nList country/language markets, create a draft, create quotas, fetch campaign-scoped profiling questions, add qualifications or custom screeners/options, and read everything back. Test the returned `test_redirect_url` and all survey outcomes. Both live and test links must preserve the `{transaction_id}` value. Funding and administrator review are required separately in the dashboard; an API-created draft does not deliver traffic. Funded pricing/ownership fields are protected. Use a development account and confirmed development API host for test writes.\n\n## Responses and retries\n\nLegacy responses vary by operation. Authentication failures and some validation failures return HTTP 200 with `Errors`, `ErrorCode`, `fieldErrors.List`, `Info`, and `Data`. Always inspect those fields alongside HTTP status. Missing key, invalid key, pending account and invalid signature use MISSING_API_KEY, INVALID_API_KEY, PENDING_APPROVAL or INVALID_HASH. A successful HTTP response alone is not proof of a successful write. Resource IDs are Mongo IDs unless a field explicitly says campaign_id. Nested resource routes require advertiser ownership and campaign/quota/question membership. Writes are not generally idempotent; after a timeout read saved state before repeating create or clone.\n" }, "servers": [ { "url": "https://www.rapidoreach.com", "description": "Production — use HTTPS; creation does not fund or launch a campaign." } ], "security": [ { "advertiserKey": [], "surveySignature": [] } ], "tags": [ { "name": "Campaigns" }, { "name": "Quotas" }, { "name": "Qualifications" }, { "name": "Screeners" }, { "name": "Catalogs" }, { "name": "Exports" } ], "paths": { "/api/v1/campaigns/getcampaigns": { "get": { "operationId": "get_api_v1_campaigns_getcampaigns", "tags": [ "Campaigns" ], "summary": "List survey campaigns", "description": "Lists only authenticated creator campaigns. Query filters are included in the signed URL.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyCampaign" }, "description": "" } }, "additionalProperties": true }, "example": { "message": "Advertiser Campaigns fetched successfully", "campaigns": [ { "_id": "CAMPAIGN_ID", "campaign_id": "SURVEY_NUMBER", "name": "Example study", "status": "DRAFT", "payment": "NOTCOMPLETED" } ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaign_manager", "in": "query", "required": false, "description": "", "schema": { "type": "string", "description": "" } }, { "name": "tags", "in": "query", "required": false, "description": "", "schema": { "type": "string", "description": "" } }, { "name": "skip", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "description": "" } }, { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "description": "" } } ] } }, "/api/v1/campaigns/searchcampaigns": { "post": { "operationId": "post_api_v1_campaigns_searchcampaigns", "tags": [ "Campaigns" ], "summary": "Search survey campaigns", "description": "Send filters in signed JSON. Name terms are combined as AND filters. Optional campaignId is the Mongo _id.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyCampaign" }, "description": "" } }, "additionalProperties": true }, "example": { "campaigns": [ { "_id": "CAMPAIGN_ID", "campaign_id": "SURVEY_NUMBER", "name": "Example study", "status": "DRAFT", "payment": "NOTCOMPLETED" } ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaignName": { "type": "string", "description": "" }, "campaignId": { "type": "string", "description": "" }, "skip": { "type": "integer", "description": "" }, "limit": { "type": "integer", "description": "" } } }, "example": { "campaignName": "Example", "limit": 20 } } } } } }, "/api/v1/campaigns/create": { "post": { "operationId": "post_api_v1_campaigns_create", "tags": [ "Campaigns" ], "summary": "Create a survey draft", "description": "Stores project fields, returns campaign and creator test URL. Name requires at least four characters; link validation requires {transaction_id} when supplied. Complete all fields before testing and funding.", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "campaign": { "$ref": "#/components/schemas/SurveyCampaign" }, "creator": { "type": "object", "properties": { "_id": { "type": "string", "description": "" }, "name": { "type": "string", "description": "" }, "test_redirect_url": { "type": "string", "description": "" } } } } }, "example": { "message": "Campaign created successfully", "campaign": { "_id": "CAMPAIGN_ID", "campaign_id": "SURVEY_NUMBER", "name": "Example study", "status": "DRAFT", "payment": "NOTCOMPLETED" }, "creator": { "_id": "USER_ID", "test_redirect_url": "/test/survey/OPAQUE_TEST_URL" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurveyInput" }, "example": { "name": "Example study", "country_language_id": "en_US", "cpi": 1.5, "length_of_interview": 10, "conversion": 20, "start_date": "2026-10-03", "end_date": "2026-10-15", "survey_live_link": "https://survey.example/live?transaction={transaction_id}", "survey_test_link": "https://survey.example/test?transaction={transaction_id}", "max_daily_completes": 50 } } } } } }, "/api/v1/campaigns/clonecampaigns": { "post": { "operationId": "post_api_v1_campaigns_clonecampaigns", "tags": [ "Campaigns" ], "summary": "Clone a survey campaign", "description": "Both fields are required. Cloned survey is returned under the legacy campaignQuota key; it is a campaign object.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "campaignQuota": { "$ref": "#/components/schemas/SurveyCampaign" } }, "additionalProperties": true }, "example": { "message": "Campaign cloned successfully", "campaignQuota": { "_id": "CAMPAIGN_ID", "campaign_id": "SURVEY_NUMBER", "name": "Example study", "status": "DRAFT", "payment": "NOTCOMPLETED" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaignId": { "type": "string", "description": "" }, "campaignName": { "type": "string", "description": "" } }, "required": [ "campaignId", "campaignName" ] }, "example": { "campaignId": "CAMPAIGN_ID", "campaignName": "New study" } } } } } }, "/api/v1/campaigns/{campaignId}": { "get": { "operationId": "get_api_v1_campaigns__campaignId_", "tags": [ "Campaigns" ], "summary": "Read a survey campaign", "description": "Use Mongo _id. Recalculates quota totals and estimated cost before returning campaign and opaque test_redirect_url. Read after changing quota sizes before dashboard funding.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "campaign": { "$ref": "#/components/schemas/SurveyCampaign" }, "test_redirect_url": { "type": "string", "description": "" } } }, "example": { "message": "Campaign fetched successfully", "campaign": { "_id": "CAMPAIGN_ID", "campaign_id": "SURVEY_NUMBER", "name": "Example study", "status": "DRAFT", "payment": "NOTCOMPLETED" }, "test_redirect_url": "/surveylink/create/OPAQUE_TEST_URL" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ] }, "put": { "operationId": "put_api_v1_campaigns__campaignId_", "tags": [ "Campaigns" ], "summary": "Update a survey campaign", "description": "Partial fields accepted, subject to mutation policy. Ownership/payment/derived totals cannot be changed. Funded CPI, billing_method, length_of_interview and conversion are immutable. ACTIVE requires funding and prior approval; pause is ACTIVE → INACTIVE. Archive only DRAFT/REJECTED/STOPPED.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "campaigns": { "$ref": "#/components/schemas/SurveyCampaign" } }, "additionalProperties": true }, "example": { "message": "Campaign Updated", "campaigns": { "_id": "CAMPAIGN_ID", "campaign_id": "SURVEY_NUMBER", "name": "Example study", "status": "DRAFT", "payment": "NOTCOMPLETED" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurveyUpdate" }, "example": { "name": "Updated study", "survey_live_link": "https://survey.example/live?transaction={transaction_id}", "survey_test_link": "https://survey.example/test?transaction={transaction_id}" } } } } }, "delete": { "operationId": "delete_api_v1_campaigns__campaignId_", "tags": [ "Campaigns" ], "summary": "Delete an unfunded campaign", "description": "Funded or allocated campaigns cannot be deleted.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" } } }, "example": { "message": "Campaign deleted!" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ] } }, "/api/v1/campaigns/{campaignId}/getcampaignquota": { "get": { "operationId": "get_api_v1_campaigns__campaignId__getcampaignquota", "tags": [ "Quotas" ], "summary": "List quotas", "description": "Quotas in the owned campaign.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "campaignQuota": { "type": "array", "items": { "$ref": "#/components/schemas/Quota" }, "description": "" } }, "additionalProperties": true }, "example": { "campaignQuota": [ { "_id": "QUOTA_ID", "campaign": "CAMPAIGN_ID", "name": "US adults", "num_respondents": 100 } ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ] } }, "/api/v1/campaigns/{campaignId}/campaignsquota": { "post": { "operationId": "post_api_v1_campaigns__campaignId__campaignsquota", "tags": [ "Quotas" ], "summary": "Create a quota", "description": "Creates a quota and links it to the campaign. Review sample size and saved qualifications before funding.", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "campaignQuota": { "$ref": "#/components/schemas/Quota" } }, "additionalProperties": true }, "example": { "campaignQuota": { "_id": "QUOTA_ID", "campaign": "CAMPAIGN_ID", "name": "US adults", "num_respondents": 100 } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaInput" }, "example": { "name": "US adults", "num_respondents": 100 } } } } } }, "/api/v1/campaigns/{campaignId}/clonecampaignsquota": { "post": { "operationId": "post_api_v1_campaigns__campaignId__clonecampaignsquota", "tags": [ "Quotas" ], "summary": "Clone a quota", "description": "Source quota must belong to the path campaign; clones its qualifications.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "campaignQuota": { "$ref": "#/components/schemas/Quota" } }, "additionalProperties": true }, "example": { "campaignQuota": { "_id": "QUOTA_ID", "campaign": "CAMPAIGN_ID", "name": "US adults", "num_respondents": 100 } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quotaId": { "type": "string", "description": "" } }, "required": [ "quotaId" ] }, "example": { "quotaId": "QUOTA_ID" } } } } } }, "/api/v1/campaigns/{campaignId}/campaignsquota/{campaignQuotaId}": { "get": { "operationId": "get_api_v1_campaigns__campaignId__campaignsquota__campaignQuotaId_", "tags": [ "Quotas" ], "summary": "Read a quota", "description": "Requires owned campaign and matching quota. PUT updates name and num_respondents; deletion is subject to controller policy.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "campaignQuota": { "$ref": "#/components/schemas/Quota" } }, "additionalProperties": true }, "example": { "campaignQuota": { "_id": "QUOTA_ID", "campaign": "CAMPAIGN_ID", "name": "US adults", "num_respondents": 100 } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } }, { "name": "campaignQuotaId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ] }, "put": { "operationId": "put_api_v1_campaigns__campaignId__campaignsquota__campaignQuotaId_", "tags": [ "Quotas" ], "summary": "Update a quota", "description": "Requires owned campaign and matching quota. PUT updates name and num_respondents; deletion is subject to controller policy.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "campaignQuota": { "$ref": "#/components/schemas/Quota" } }, "additionalProperties": true }, "example": { "campaignQuota": { "_id": "QUOTA_ID", "campaign": "CAMPAIGN_ID", "name": "US adults", "num_respondents": 100 } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } }, { "name": "campaignQuotaId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaInput" }, "example": { "name": "US adults", "num_respondents": 120 } } } } }, "delete": { "operationId": "delete_api_v1_campaigns__campaignId__campaignsquota__campaignQuotaId_", "tags": [ "Quotas" ], "summary": "Delete a quota", "description": "Requires owned campaign and matching quota. PUT updates name and num_respondents; deletion is subject to controller policy.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" } } }, "example": { "message": "Campaign Quota deleted!" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } }, { "name": "campaignQuotaId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ] } }, "/api/v1/campaigns/{campaignId}/campaignsquota/{campaignQuotaId}/getcampaignsqualifications": { "get": { "operationId": "get_api_v1_campaigns__campaignId__campaignsquota__campaignQuotaId__getcampaignsqualifications", "tags": [ "Qualifications" ], "summary": "List qualifications", "description": "Read saved question snapshots and accepted precodes.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "campaignQualifications": { "type": "array", "items": { "$ref": "#/components/schemas/Qualification" }, "description": "" } }, "additionalProperties": true }, "example": { "campaignQualifications": [ { "_id": "QUALIFICATION_ID", "campaignQuota": "QUOTA_ID", "question_id": 43, "pre_code_values": [ "1" ] } ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } }, { "name": "campaignQuotaId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ] } }, "/api/v1/campaigns/{campaignId}/campaignsquota/{campaignQuotaId}/campaignsqualification": { "post": { "operationId": "post_api_v1_campaigns__campaignId__campaignsquota__campaignQuotaId__campaignsqualification", "tags": [ "Qualifications" ], "summary": "Create a qualification", "description": "The current handler uses the SAMPLY master catalog for the campaign locale. QuestionID must exist there; choose accepted pre_code_values from its Options. Provider catalogs with different IDs cannot be substituted.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "campaignQualifications": { "$ref": "#/components/schemas/Qualification" } }, "additionalProperties": true }, "example": { "campaignQualifications": { "_id": "QUALIFICATION_ID", "campaignQuota": "QUOTA_ID", "question_id": 43, "pre_code_values": [ "1" ] } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } }, { "name": "campaignQuotaId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualificationInput" }, "example": { "question_id": 43, "pre_code_values": [ "1" ] } } } } } }, "/api/v1/campaigns/{campaignId}/campaignsquota/{campaignQuotaId}/campaignsqualification/{campaignQualificationsId}": { "get": { "operationId": "get_api_v1_campaigns__campaignId__campaignsquota__campaignQuotaId__campaignsqualification__campaignQualificationsId_", "tags": [ "Qualifications" ], "summary": "Read a qualification", "description": "Requires qualification membership in the path quota and owned campaign. Funded campaign quota/qualification writes return 409.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "campaignQualifications": { "$ref": "#/components/schemas/Qualification" } }, "additionalProperties": true }, "example": { "campaignQualifications": { "_id": "QUALIFICATION_ID", "campaignQuota": "QUOTA_ID", "question_id": 43, "pre_code_values": [ "1" ] } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } }, { "name": "campaignQuotaId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } }, { "name": "campaignQualificationsId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ] }, "put": { "operationId": "put_api_v1_campaigns__campaignId__campaignsquota__campaignQuotaId__campaignsqualification__campaignQualificationsId_", "tags": [ "Qualifications" ], "summary": "Update a qualification", "description": "Requires qualification membership in the path quota and owned campaign. Funded campaign quota/qualification writes return 409.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "campaignQualifications": { "$ref": "#/components/schemas/Qualification" } }, "additionalProperties": true }, "example": { "campaignQualifications": { "_id": "QUALIFICATION_ID", "campaignQuota": "QUOTA_ID", "question_id": 43, "pre_code_values": [ "1" ] } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } }, { "name": "campaignQuotaId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } }, { "name": "campaignQualificationsId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualificationInput" }, "example": { "question_id": 43, "pre_code_values": [ "2" ] } } } } }, "delete": { "operationId": "delete_api_v1_campaigns__campaignId__campaignsquota__campaignQuotaId__campaignsqualification__campaignQualificationsId_", "tags": [ "Qualifications" ], "summary": "Delete a qualification", "description": "Requires qualification membership in the path quota and owned campaign. Funded campaign quota/qualification writes return 409.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" } } }, "example": { "message": "Campaign Quota Qualification deleted!" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } }, { "name": "campaignQuotaId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } }, { "name": "campaignQualificationsId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ] } }, "/api/v1/campaigns/{campaignId}/getcustomquestions": { "get": { "operationId": "get_api_v1_campaigns__campaignId__getcustomquestions", "tags": [ "Screeners" ], "summary": "List custom screeners", "description": "Screeners belonging to the owned campaign.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "customQuestions": { "type": "array", "items": { "$ref": "#/components/schemas/Question" }, "description": "" } }, "additionalProperties": true }, "example": { "customQuestions": [ { "_id": "QUESTION_ID", "campaign": "CAMPAIGN_ID", "display_text": "", "question_options": [] } ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ] } }, "/api/v1/campaigns/{campaignId}/customquestion": { "post": { "operationId": "post_api_v1_campaigns__campaignId__customquestion", "tags": [ "Screeners" ], "summary": "Initialize a custom screener", "description": "Creates a blank default question. The create body does not set its text; use PUT with the returned _id.", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "customQuestions": { "$ref": "#/components/schemas/Question" } }, "additionalProperties": true }, "example": { "customQuestions": { "_id": "QUESTION_ID", "campaign": "CAMPAIGN_ID", "display_text": "", "question_options": [] } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ] } }, "/api/v1/campaigns/{campaignId}/customquestion/{customquestionId}": { "get": { "operationId": "get_api_v1_campaigns__campaignId__customquestion__customquestionId_", "tags": [ "Screeners" ], "summary": "Read a screener", "description": "Funded campaign screeners are read-only (writes return 409). Requires question membership in the owned campaign. PUT accepts only the documented editable fields; use the dashboard question type catalog for permitted values.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "customQuestions": { "$ref": "#/components/schemas/Question" } }, "additionalProperties": true }, "example": { "customQuestions": { "_id": "QUESTION_ID", "campaign": "CAMPAIGN_ID", "display_text": "Do you own a car?", "question_options": [] } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } }, { "name": "customquestionId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ] }, "put": { "operationId": "put_api_v1_campaigns__campaignId__customquestion__customquestionId_", "tags": [ "Screeners" ], "summary": "Update screener text and controls", "description": "Funded campaign screeners are read-only (writes return 409). Requires question membership in the owned campaign. PUT accepts only the documented editable fields; use the dashboard question type catalog for permitted values.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "customQuestions": { "$ref": "#/components/schemas/Question" } }, "additionalProperties": true }, "example": { "customQuestions": { "_id": "QUESTION_ID", "campaign": "CAMPAIGN_ID", "display_text": "Do you own a car?", "question_options": [] } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } }, { "name": "customquestionId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionUpdate" }, "example": { "display_text": "Do you own a car?", "question_type_id": "Single Punch" } } } } }, "delete": { "operationId": "delete_api_v1_campaigns__campaignId__customquestion__customquestionId_", "tags": [ "Screeners" ], "summary": "Delete a screener", "description": "Funded campaign screeners are read-only (writes return 409). Requires question membership in the owned campaign. PUT accepts only the documented editable fields; use the dashboard question type catalog for permitted values.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" } } }, "example": { "message": "Advertiser CustomQuestions deleted successfully" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } }, { "name": "customquestionId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ] } }, "/api/v1/campaigns/cq/{customquestionId}/createoption": { "post": { "operationId": "post_api_v1_campaigns_cq__customquestionId__createoption", "tags": [ "Screeners" ], "summary": "Initialize an answer option", "description": "Creates a blank default answer with cs_accept. The body does not set its value. Fetch the question, then PUT the returned option_id.", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "customQuestions": { "$ref": "#/components/schemas/Question" } }, "additionalProperties": true }, "example": { "customQuestions": { "_id": "QUESTION_ID", "campaign": "CAMPAIGN_ID", "display_text": "", "question_options": [ { "option_id": "OPTION_ID", "value": "", "control_state": "cs_accept" } ] } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "customquestionId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ] } }, "/api/v1/campaigns/cq/{customquestionId}/option/{option_id}": { "put": { "operationId": "put_api_v1_campaigns_cq__customquestionId__option__option_id_", "tags": [ "Screeners" ], "summary": "Update an answer option", "description": "Only value and control_state can be updated. sort_order is not accepted by this endpoint.", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" } } }, "example": { "message": "Custom Question Options updated successfully" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "customquestionId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } }, { "name": "option_id", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptionUpdate" }, "example": { "value": "Yes", "control_state": "cs_accept" } } } } }, "delete": { "operationId": "delete_api_v1_campaigns_cq__customquestionId__option__option_id_", "tags": [ "Screeners" ], "summary": "Remove an answer option", "description": "Requires question ownership through its campaign.", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "customQuestions": { "$ref": "#/components/schemas/Question" } }, "additionalProperties": true }, "example": { "message": "Custom Question Options deleted successfully", "customQuestions": { "_id": "QUESTION_ID", "campaign": "CAMPAIGN_ID", "display_text": "", "question_options": [] } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "customquestionId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } }, { "name": "option_id", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ] } }, "/api/v1/campaigns/{campaignId}/getcustomquestionsforprofiling": { "get": { "operationId": "get_api_v1_campaigns__campaignId__getcustomquestionsforprofiling", "tags": [ "Screeners" ], "summary": "Read formatted profiling screeners", "description": "Returns custom questions formatted for the respondent profiling flow.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" }, "example": { "Errors": [], "ErrorCode": "SUCCESS", "Data": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ] } }, "/api/v1/campaigns/listcountrylanguage": { "post": { "operationId": "post_api_v1_campaigns_listcountrylanguage", "tags": [ "Catalogs" ], "summary": "List country and language markets", "description": "Use returned market identifiers rather than hardcoded IDs. Targeting creation needs SAMPLY catalog records for that locale; the targeting lookup may fall back to US catalog questions if the selected locale has none.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" }, "example": { "Errors": [], "ErrorCode": "SUCCESS", "Data": [ { "CountryLanguageId": 9, "CountryLanguageCode": "en_US" } ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "MatchString": { "type": "string", "description": "" }, "Limit": { "type": "integer", "description": "" } } }, "example": { "MatchString": "en_US", "Limit": 20 } } } } } }, "/api/v1/campaigns/{campaignId}/getProfilingQuestionsForTargeting": { "post": { "operationId": "post_api_v1_campaigns__campaignId__getProfilingQuestionsForTargeting", "tags": [ "Catalogs" ], "summary": "Get targeting question catalog", "description": "Campaign-scoped path is preferred. Legacy path requires campaignId in signed JSON. Locale/provider must match master data. Returns existing campaign profiling questions when configured; otherwise provider catalog.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" }, "example": { "Errors": [], "ErrorCode": "SUCCESS", "Data": [ { "QuestionID": 43, "QuestionText": "Gender", "Options": [ { "Precode": "1", "OptionText": "Male" } ] } ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Opaque identifier returned by the API; owned by the authenticated advertiser.", "schema": { "type": "string", "description": "" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "CountryLangugageCode": { "type": "string", "description": "Historical spelling is exact." }, "PartnerCode": { "type": "string", "description": "Configured profiling provider code." }, "returnblank": { "type": "string", "description": "Literal string false excludes blank-catalog lookup." } }, "required": [ "CountryLangugageCode", "PartnerCode" ] }, "example": { "CountryLangugageCode": "en_US", "PartnerCode": "PROVIDER_CODE" } } } } } }, "/api/v1/campaigns/getProfilingQuestionsForTargeting": { "post": { "operationId": "post_api_v1_campaigns_getProfilingQuestionsForTargeting", "tags": [ "Catalogs" ], "summary": "Get targeting catalog (legacy path)", "description": "Campaign-scoped path is preferred. Legacy path requires campaignId in signed JSON. Locale/provider must match master data. Returns existing campaign profiling questions when configured; otherwise provider catalog.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" }, "example": { "Errors": [], "ErrorCode": "SUCCESS", "Data": [ { "QuestionID": 43, "QuestionText": "Gender", "Options": [ { "Precode": "1", "OptionText": "Male" } ] } ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "CountryLangugageCode": { "type": "string", "description": "Historical spelling is exact." }, "PartnerCode": { "type": "string", "description": "Configured profiling provider code." }, "returnblank": { "type": "string", "description": "Literal string false excludes blank-catalog lookup." }, "campaignId": { "type": "string", "description": "Owned campaign Mongo ID." } }, "required": [ "CountryLangugageCode", "PartnerCode", "campaignId" ] }, "example": { "CountryLangugageCode": "en_US", "PartnerCode": "PROVIDER_CODE", "campaignId": "CAMPAIGN_ID" } } } }, "deprecated": true } }, "/api/v1/campaigns/downloadresponses": { "get": { "operationId": "get_api_v1_campaigns_downloadresponses", "tags": [ "Exports" ], "summary": "Download respondent responses", "description": "Signed query must include campaignId (campaign_id or Mongo _id) and local_tz_string (IANA timezone). enc is removed before controller validation. Only owned campaign data is exported.", "responses": { "200": { "description": "Excel response export; legacy validation errors may instead be application/json.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "description": "", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } }, "parameters": [ { "name": "campaignId", "in": "query", "required": true, "description": "", "schema": { "type": "string", "description": "" } }, { "name": "local_tz_string", "in": "query", "required": true, "description": "IANA timezone, for example UTC.", "schema": { "type": "string", "description": "" } } ] } }, "/api/v1/campaigns/invoices": { "get": { "operationId": "get_api_v1_campaigns_invoices", "tags": [ "Exports" ], "summary": "List survey invoices", "description": "Invoices where payerId matches the authenticated advertiser user.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "" }, "invoices": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "" } } }, "example": { "message": "Advertiser Invoices fetched successfully", "invoices": [] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "403": { "description": "Account or ownership denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "404": { "description": "Resource not found or feature unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "409": { "description": "Conflict; inspect state before retrying", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "429": { "description": "Rate limit; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "500": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyReply" } } } } } } } }, "components": { "securitySchemes": { "advertiserKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "surveySignature": { "type": "apiKey", "in": "query", "name": "enc", "description": "Hex digest of unsigned full URL + serialized body + advertiser secret; last query field." } }, "schemas": { "LegacyReply": { "type": "object", "properties": { "Errors": { "type": "array", "items": { "type": "string", "description": "" }, "description": "" }, "Info": { "type": "array", "items": { "type": "string", "description": "" }, "description": "" }, "Data": { "type": "array", "items": {}, "description": "" }, "ErrorCode": { "type": "string", "description": "" }, "fieldErrors": { "type": "object", "properties": { "List": { "type": "array", "items": { "type": "object", "properties": { "FieldName": { "type": "string", "description": "" }, "Errors": { "type": "array", "items": { "type": "string", "description": "" }, "description": "" } } }, "description": "" } } }, "TotalRecords": { "type": "integer", "description": "" } }, "additionalProperties": true }, "SurveyInput": { "type": "object", "properties": { "name": { "type": "string", "description": "", "minLength": 4 }, "country_language_id": { "type": "string", "description": "CountryLanguageCode from listcountrylanguage, for example en_US; not the numeric CountryLanguageId." }, "cpi": { "type": "number", "description": "Cost per complete." }, "length_of_interview": { "type": "number", "description": "Minutes." }, "conversion": { "type": "number", "description": "Expected completion percentage." }, "start_date": { "type": "string", "description": "", "format": "date" }, "end_date": { "type": "string", "description": "", "format": "date" }, "survey_live_link": { "type": "string", "description": "Must include {transaction_id}." }, "survey_test_link": { "type": "string", "description": "Must include {transaction_id}." }, "max_daily_completes": { "type": "number", "description": "" }, "soft_launch_total_remaining": { "type": "number", "description": "" }, "supported_devices": { "type": "array", "items": { "type": "string", "description": "", "enum": [ "DESKTOP", "MOBILE", "TABLET" ] }, "description": "" }, "campaign_manager": { "type": "string", "description": "" }, "tags": { "type": "array", "items": { "type": "string", "description": "", "minLength": 3 }, "description": "" }, "research_industry": { "type": "array", "items": { "type": "string", "description": "Research industry Mongo ID." }, "description": "" }, "research_category": { "type": "array", "items": { "type": "string", "description": "Research category Mongo ID." }, "description": "" } }, "required": [ "name", "country_language_id", "cpi", "length_of_interview", "conversion", "start_date", "end_date", "survey_live_link", "survey_test_link" ] }, "SurveyUpdate": { "type": "object", "properties": { "name": { "type": "string", "description": "", "minLength": 4 }, "country_language_id": { "type": "string", "description": "CountryLanguageCode from listcountrylanguage, for example en_US; not the numeric CountryLanguageId." }, "cpi": { "type": "number", "description": "Cost per complete." }, "length_of_interview": { "type": "number", "description": "Minutes." }, "conversion": { "type": "number", "description": "Expected completion percentage." }, "start_date": { "type": "string", "description": "", "format": "date" }, "end_date": { "type": "string", "description": "", "format": "date" }, "survey_live_link": { "type": "string", "description": "Must include {transaction_id}." }, "survey_test_link": { "type": "string", "description": "Must include {transaction_id}." }, "max_daily_completes": { "type": "number", "description": "" }, "soft_launch_total_remaining": { "type": "number", "description": "" }, "supported_devices": { "type": "array", "items": { "type": "string", "description": "", "enum": [ "DESKTOP", "MOBILE", "TABLET" ] }, "description": "" }, "campaign_manager": { "type": "string", "description": "" }, "tags": { "type": "array", "items": { "type": "string", "description": "", "minLength": 3 }, "description": "" }, "research_industry": { "type": "array", "items": { "type": "string", "description": "Research industry Mongo ID." }, "description": "" }, "research_category": { "type": "array", "items": { "type": "string", "description": "Research category Mongo ID." }, "description": "" }, "status": { "type": "string", "description": "", "enum": [ "ACTIVE", "INACTIVE", "STOPPED", "ARCHIVED" ] }, "billing_method": { "type": "string", "description": "" } }, "additionalProperties": true }, "SurveyCampaign": { "type": "object", "properties": { "_id": { "type": "string", "description": "" }, "campaign_id": { "type": "string", "description": "Human-facing survey ID, distinct from _id." }, "name": { "type": "string", "description": "" }, "status": { "type": "string", "description": "" }, "creator": { "type": "string", "description": "" }, "country_language_id": { "type": "string", "description": "" }, "cpi": { "type": "number", "description": "" }, "survey_live_link": { "type": "string", "description": "" }, "survey_test_link": { "type": "string", "description": "" }, "payment": { "type": "string", "description": "" }, "target_completes": { "type": "number", "description": "" }, "estimated_total_cost": { "type": "number", "description": "" }, "fundingAllocationMicros": { "type": "integer", "description": "" } }, "additionalProperties": true }, "QuotaInput": { "type": "object", "properties": { "name": { "type": "string", "description": "" }, "num_respondents": { "type": "number", "description": "Target completes." } } }, "Quota": { "type": "object", "properties": { "_id": { "type": "string", "description": "" }, "campaign": { "type": "string", "description": "" }, "name": { "type": "string", "description": "" }, "num_respondents": { "type": "number", "description": "" }, "campaign_qualifications": { "type": "array", "items": { "type": "string", "description": "" }, "description": "" } }, "additionalProperties": true }, "QualificationInput": { "type": "object", "properties": { "question_id": { "type": "number", "description": "Current catalog QuestionID." }, "pre_code_values": { "type": "array", "items": {}, "description": "Accepted catalog precodes; match locale/provider." } }, "required": [ "question_id", "pre_code_values" ] }, "Qualification": { "type": "object", "properties": { "_id": { "type": "string", "description": "" }, "campaignQuota": { "type": "string", "description": "" }, "question_id": { "type": "number", "description": "" }, "pre_code_values": { "type": "array", "items": {}, "description": "" }, "question_detail": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true }, "QuestionUpdate": { "type": "object", "properties": { "display_text": { "type": "string", "description": "" }, "question_type_id": { "type": "string", "description": "" }, "shuffle_type": { "type": "string", "description": "" }, "question_options_type": { "type": "string", "description": "" }, "purpose": { "type": "string", "description": "" }, "logical_operator": { "type": "string", "description": "" }, "sort_order": { "type": "number", "description": "" }, "min": { "type": "number", "description": "" }, "max": { "type": "number", "description": "" }, "number_of_ratings": { "type": "number", "description": "" }, "step": { "type": "number", "description": "" } }, "additionalProperties": false }, "Question": { "type": "object", "properties": { "_id": { "type": "string", "description": "" }, "campaign": { "type": "string", "description": "" }, "display_text": { "type": "string", "description": "" }, "question_type_id": { "type": "string", "description": "" }, "question_options": { "type": "array", "items": { "type": "object", "properties": { "option_id": { "type": "string", "description": "" }, "value": { "type": "string", "description": "" }, "control_state": { "type": "string", "description": "", "enum": [ "cs_accept", "cs_reject" ] }, "sort_order": { "type": "number", "description": "" } } }, "description": "" } }, "additionalProperties": true }, "OptionUpdate": { "type": "object", "properties": { "value": { "type": "string", "description": "Answer text." }, "control_state": { "type": "string", "description": "", "enum": [ "cs_accept", "cs_reject" ] } }, "additionalProperties": false } } } }