Build on the CosmosPanel
Survey Supply API

The CosmosPanel Supplier API is a RESTful interface that gives panel operators and research platforms programmatic access to CosmosPanel's live B2B survey inventory. Instead of manually coordinating project briefs via email, the API lets your platform automatically discover available surveys, match them to your panelists' professional profiles, and route qualifying respondents directly into live studies.

The integration is built for both high-volume consumer panels looking to diversify into B2B, and specialist B2B panel operators who want to expand their monetisable inventory without sourcing projects individually.

Core capabilities

• Pull live inventory — Fetch all surveys currently open to your panel, filtered by market, category, CPI, and target profile.
• Generate entry links — Create unique, trackable URLs for each panelist you route into a survey.
• Receive status callbacks — Get real-time postback notifications when respondents complete, terminate, or hit a quota-full condition.
• Manage profiling — Retrieve the full list of profiling attributes CosmosPanel uses to qualify B2B respondents, so you can match your own panel data accordingly.
• Monitor quotas — Check live quota availability before routing respondents, reducing dead-end experiences.

The API flow follows five steps that repeat for every survey campaign:

1. Authenticate — Your platform authenticates with your API key in every request header.
2. Fetch inventory — Call GET /v3/surveys to retrieve all surveys currently available for your panel, including targeting criteria, CPI, and quota availability.
3. Match respondents — Compare each survey's targeting requirements against your panelists' stored profile data (job function, seniority, industry, company size, geography).
4. Generate & send entry links — For each matching panelist, call the entry link endpoint to generate a unique URL, then embed it in your survey invitation.
5. Receive callbacks — CosmosPanel posts a status notification to your configured endpoint when each respondent completes, terminates, reaches quota full, or is flagged as a security terminate.

Your platform bears no responsibility for survey scripting, sampling, or quality control — CosmosPanel handles all of that upstream. Your role is to supply verified B2B professionals and trust that the redirect flow accurately reflects each respondent's outcome.

CosmosPanel pays suppliers per verified complete (CPI — Cost Per Interview). The CPI for each survey is displayed in the survey listing response and varies based on LOI, incidence rate, and target profile complexity. No payment is made for terminates, quota-full redirects, or security terminates.

All API requests must include your unique API key in the request header. Keys are provisioned per supplier account and scoped to your approved panel markets.

Header format

X-API-Key: cp_live_xxxxxxxxxxxxxxxxxxxx

Obtaining your API key

1. Log in to the CosmosPanel Supplier Dashboard at supplier.cosmospanel.com
2. Navigate to Settings → API Access
3. Click Generate Key — your live key will be displayed once. Copy and store it securely.

Key types

Before routing live respondents, complete the following checklist with your integration team:

1. Receive API credentials from your CosmosPanel account manager.
2. Configure your Postback URL in the dashboard — this is the endpoint CosmosPanel will call with respondent status updates.
3. Use your cp_test_ key to verify the full entry → complete/terminate → callback flow in sandbox.
4. Validate that your system correctly handles all four callback statuses: complete, terminate, quota full, and security terminate.
5. Switch to your cp_live_ key and begin routing production traffic.

Quick test request

curl -X GET \
  https://api.cosmospanel.com/v3/surveys \
  -H "X-API-Key: cp_test_xxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

All endpoints are served over HTTPS. The base URL for all requests is:

https://api.cosmospanel.com/v3

List Available Surveys

{
  "data": [
    {
      "survey_id":     "cp_srv_a3f9b2c1",
      "title":         "IT Security Decision-Makers — US",
      "market":        "US",
      "category":      "it_decision_maker",
      "loi_minutes":   12,
      "cpi_usd":       18.50,
      "ir_estimate":   0.22,
      "quota_remaining": 47,
      "quota_total":   150,
      "closes_at":     "2026-05-10T23:59:00Z",
      "targeting": {
        "job_functions": ["IT", "Security"],
        "seniority":    ["Director", "VP", "C-Suite"],
        "company_size": ["500-999", "1000+"],
        "industries":   ["Technology", "Financial Services"]
      }
    }
  ],
  "meta": {
    "total":       84,
    "next_cursor": "eyJpZCI6ImNwX3Nydl9hM2Y5YjJjMiJ9"
  }
}

Get Survey Details

{
  "survey_id":   "cp_srv_a3f9b2c1",
  "title":       "IT Security Decision-Makers — US",
  "status":      "live",
  "loi_minutes": 12,
  "cpi_usd":     18.50,
  "quotas": [
    {
      "quota_id":    "q_001",
      "description": "Director level, 500-999 employees",
      "remaining":   24,
      "total":       75
    },
    {
      "quota_id":    "q_002",
      "description": "VP / C-Suite, 1000+ employees",
      "remaining":   23,
      "total":       75
    }
  ]
}

Generate Entry Link

{
  "respondent_id": "your_panel_uid_12345",
  "redirect_url":  "https://yourpanel.com/survey-return",
  "locale":        "en-US",
  "profile": {
    "job_function":  "IT",
    "seniority":    "Director",
    "company_size": "500-999",
    "industry":     "Financial Services",
    "country":      "US"
  }
}

{
  "entry_url":    "https://api.cosmospanel.com/v3/enter/cp_tok_f8e2a91b3d",
  "token":        "cp_tok_f8e2a91b3d",
  "expires_at":   "2026-04-24T12:00:00Z",
  "pre_qualified": true
}

List Profile Attributes

{
  "attributes": [
    {
      "key":      "job_function",
      "label":    "Job Function",
      "type":     "enum",
      "values":   ["IT", "Finance", "HR", "Marketing",
                   "Operations", "Sales", "Legal", "Procurement",
                   "C-Suite / General Management", "Other"]
    },
    {
      "key":      "seniority",
      "label":    "Seniority Level",
      "type":     "enum",
      "values":   ["Individual Contributor", "Manager",
                   "Director", "VP", "C-Suite", "Owner / Partner"]
    },
    {
      "key":      "company_size",
      "label":    "Company Size (employees)",
      "type":     "enum",
      "values":   ["1-9", "10-49", "50-249",
                   "250-499", "500-999", "1000+"]
    },
    {
      "key":      "industry",
      "label":    "Industry Sector",
      "type":     "enum",
      "values":   ["Technology", "Financial Services",
                   "Healthcare", "Manufacturing", "Retail",
                   "Professional Services", "Education", "Government",
                   "Energy & Utilities", "Media & Telecoms", "Other"]
    }
  ]
}

Check Quota Status

When a respondent finishes their session — whether they complete the survey, get screened out, or hit a full quota — CosmosPanel redirects them back to the redirect_url you provided, appending status parameters to the URL.

CosmosPanel also fires a server-side postback to your configured Postback URL. Always rely on the server-side postback for revenue attribution — client-side redirects can be blocked by browsers or abandoned mid-session.

Redirect URL patterns

Server-side postback

In addition to browser redirects, CosmosPanel fires a GET request to your configured Postback URL for every completion:

GET https://yourpanel.com/postback
  ?event=complete
  &respondent_id=your_panel_uid_12345
  &survey_id=cp_srv_a3f9b2c1
  &token=cp_tok_f8e2a91b3d
  &cpi_usd=18.50
  ×tamp=2026-04-21T14:33:00Z
  &signature=sha256_hmac_signature

The signature field is an HMAC-SHA256 hash of the full postback URL signed with your API key. Verify this signature server-side before crediting a completion to prevent fraud.

CosmosPanel substitutes the following dynamic variables into redirect and postback URLs at runtime:

All errors return a JSON body with a code, message, and optional details field.

{
  "error": {
    "code":    "survey_quota_full",
    "message": "All quotas for this survey are complete.",
    "status":  409
  }
}

Rate limits are applied per API key. If you exceed a limit, the API returns a 429 rate_limit_exceeded response with a Retry-After header indicating the number of seconds before you may retry.

Who sends survey invitations to panelists?

You do. CosmosPanel provides the survey inventory and entry link generation. Your platform manages panelist communication, invitation scheduling, and the member experience. This gives you full control over your respondent relationship and incentive structures.

What incentives do panelists receive?

That is entirely your decision. CosmosPanel pays you the CPI on every verified complete. How you split that revenue with your panelists — whether through points, cash, vouchers, or charity donations — is governed by your own panel programme terms.

How is the CosmosPanel API different from other survey supply APIs?

CosmosPanel exclusively operates in the B2B segment. Every survey in our inventory targets business professionals by job function, seniority, industry, and company size. If your panel has a professional member base, our inventory is a direct, high-CPI match — without requiring you to build separate B2B sourcing relationships.

What happens if a survey closes mid-campaign?

The survey status transitions to closed. Any panelists who attempt to enter after closure receive a survey_closed error or a quota-full redirect. We recommend polling quota_remaining before sending bulk invitations.

Can I integrate across multiple markets with a single key?

Yes. A single API key can access all markets approved for your account. Use the market query parameter to filter survey listings per market when routing country-specific invitations.

Is there a sandbox environment?

Yes. Use your cp_test_ API key against the same base URL. Sandbox surveys simulate the full redirect and postback flow with synthetic respondent outcomes. No revenue is accrued in sandbox mode.

CosmosPanel provides dedicated integration support during your initial onboarding period, and ongoing technical assistance via email for all active supplier partners.

• Integration queries — Endpoint behaviour, parameter clarification, profile mapping assistance.
• Postback verification — Help verifying HMAC signatures and validating your server-side callback handler.
• Revenue discrepancies — Disputes over complete counts or CPI rates should be raised within 30 days of the relevant billing period.
• API key management — Key regeneration, market scope changes, and rate limit increases require account manager approval.