Create Your First Survey

To get started, you need to have received your login and API KEY from PureSpectrum team.

Feasibility

Each survey should start with evaluating the feasibility of the required audience on our Marketplace panels.

PureSpectrum feasibility provides an estimate of the number of respondents available based on the qualifications and quotas set for a specific locale. It's possible to obtain the feasibility and recommended price, without creating a survey.

Example

locale: en_US

targeting = males aged 45-49

number of completes = 100

LOI = 10mins

IR = 70%

field time = 5days

we get the Feasibility to be 506804 (subject to suppliers enabled for the account)

This feasibility can be obtained by sending a POST request to the /feasibility endpoint.

Staging: https://staging.spectrumsurveys.com/buyers/v2/feasibility

Production: https://api.spectrumsurveys.com/buyers/v2/feasibility

When requesting feasibility, you should include all required qualifications and condition codes.

The endpoint is meant to be used as an estimator for the feasibility and CPI of your survey audience.

Example Request

For example - if your survey has a qualification on gender=male, and your quotas have criteria for ages 45-49, your feasibility request should contain both the gender qualification and the age qualification.

Payload:

{
    "survey_localization": "en_US",
    "completes_required": 100,
    "expected_ir": 70,
    "expected_loi": 10,
    "field_time": 5,
    "quotas": [
        {
            "buyer_quota_id": "abc1",
            "required_count": 100,
            "criteria": [
                {
                    "qualification_code": 211,
                    "condition_codes": [
                        "111"
                    ]
                },
                {
                    "qualification_code": 212,
                    "range_sets": [
                        {
                            "from": 45,
                            "to": 49,
                            "units": 311
                        }
                    ]
                }
            ]
        }
    ]
}

Response 🟢 200:

{
    "quotas": [
        {
            "buyer_quota_id": "abc1",
            "count": 506804
        }
    ],
    "max_feasibility": 0,
    "recommended_cpi": 1.06,
    "unused_criterias": [],
    "unused_qualifications": [],
    "feasibility_cpi": 1.06,
    "total_feasibility": 506804,
    "difficult_quotas": []
}

For more information on the feasibility endpoint, visit the Feasibility & Pricing API reference page.

Create a Survey

To create a new survey on the PureSpectrum platform, you need to send a POST request to the /surveys endpoint.

Staging: https://staging.spectrumsurveys.com/buyers/v2/surveys

Production: https://api.spectrumsurveys.com/buyers/v2/surveys

The request body should contain the following data as a minimum:

Create survey minimum request schema

Example Request

Payload

{
  "survey_title": "Test New Survey",
  "survey_category_code": 211,
  "survey_localization": "en_US",
  "completes_required": 300,
  "expected_ir": 60,
  "expected_loi": 10,
  "live_url": "https://my.survey.com?survey_id=1234",
  "field_time": 10
}

The response JSON data will contain all the newly created survey information.

Example Response

Response 🟢 201:

{
    "aida": {
        "enabled": false,
        "selected_quota_ids": []
    },
    "qbp": {
        "enable": false
    },
    "qlc": {
        "enable": false,
        "multiple_quotas": {
            "enable": false,
            "count_by_quota": false,
            "compensate_by_quota": false
        }
    },
    "soft_launch": {
        "enable": false
    },
    "unique_links": {
        "enable": false
    },
    "click_balancing": 0,
    "estimated_clicks": 0,
    "survey_external_id": "",
    "ps_survey_status": 11,
    "offer_price": null,
    "incl_excl": 0,
    "quota_throttling": false,
    "url_transform": false,
    "subscriber_emails": [],
    "survey_title": "Test New Survey",
    "survey_category_code": 211,
    "completes_required": 300,
    "field_time": 10,
    "buyer_message": null,
    "is_modular_survey": false,
    "live_url": "https://my.survey.com?survey_id=1234",
    "billing_id": "PS1173622",
    "test_url": null,
    "expected_loi": 10,
    "expected_ir": 60,
    "ps_survey_id": 1173622,
    "buyer_surveygroup_ref": null,
    "buyer_surveygroup_refs": [],
    "test_ps_survey_entry_link": "https://staging.spectrumsurveys.com/#/start-survey?survey_id=1173622&ps_redirect_test=1&bsec=a70mx8&supplier_id=23",
    "survey_localization": "en_US",
    "uniqueLinks": false,
    "quotas": [],
    "qualifications": [],
    "is_feot_enabled": false,
    "feot": {},
    "survey_grouping": [],
    "blend_id": null,
    "schedule_launch": {
        "enable": false,
        "info": {
            "date": null,
            "hours": null,
            "minutes": null,
            "timezone": null,
            "dateTimeInISO": null
        }
    },
    "price_reco": false,
    "project_creation_date": "2025-05-14T15:33:35.187Z",
    "project_last_complete_date": null,
    "is_dq_enable": false,
    "mc_count": 0,
    "tc_count": 0,
    "basic_token": {
        "enable": false,
        "value": null
    },
    "is_pure_price_rate_card_enable": true,
    "dq_settings": {
        "purescore_filter_enabled": true,
        "fp_device_check": true,
        "fp_fraud_check": true
    },
    "product": "",
    "pds_ignore_override": false,
    "supplier_allocation_throttle": true,
    "blend_applied": false
}

For more information and examples on the surveys endpoint, visit the Create survey API reference page.

Test Survey

Create a survey.

From the response of create survey, get the test_ps_survey_entry_link e.g. https://staging.spectrumsurveys.com/#/start-survey?survey_id=1234567&ps_redirect_test=1&bsec=a70mx8&supplier_id=23

Open the link in a browser, answer the PureSpectrum screening questions and then complete your survey.
A transaction_id and PSID will be appended to the URL.

At the end of the survey, you will be redirected back to PureSpectrum e.g. https://staging.spectrumsurveys.com/landing?st=21&transaction_id=2rpgF6K36lMn8Ow0GMmwoy&supplier_id=26&survey_id=1234567&ps_rstatus=21&psid=test

Test transactions will not be part of the counts on the UI Dashboard.
To see the test transactions, download the report with Include Test Transactions option enabled and look for the PSID = "test".

Take Survey Live

Send a PUT request to the /surveys/{SURVEY_ID}/status endpoint with a ps_survey_status code of 22.

Staging: https://staging.spectrumsurveys.com/buyers/v2/surveys/{SURVEY_ID}/status

Production: https://api.spectrumsurveys.com/buyers/v2/surveys/{SURVEY_ID}/status

This will transition your survey from a draft state to a live state.

Once the survey is live, real respondents will start to come in Production.

For more information about the update survey status endpoint, visit Update survey status API reference page.

Live Survey Management

During live field you can update the price via the Update offer price endpoint or pause / close the survey via the Update survey status endpoint.

For more information about the update price endpoint, visit Update offer price API reference page.

Close Survey

The survey will automatically have its status changed to Paused, once it reaches its goal or it has its quotas fulfilled.

You have the option to accept or reconcile completes using the Reconciliation endpoint.

You can also close it yourself via the Update survey status endpoint.

For more information about the Reconciliation endpoint, visit Reconciliation API reference page.

Create Your First Survey

Feasibility#

Create a Survey#

Test Survey#

Take Survey Live#

Live Survey Management#

Close Survey#

Feasibility

Create a Survey

Test Survey

Take Survey Live

Live Survey Management

Close Survey