You may obtain estimated feasibility on a target demographic without first creating a survey.

January 2020 - We now return recommended pricing in the response of this API endpoint.

Request

POST $apihost/$basepath/feasibility

($apihost is the environment against which you are testing, All Buy API calls will require access_token parameter in the header)

Considerations

This endpoint is meant to be used as an estimator for the feasibility and pricing of a specific target, or multiple targets.

When requesting feasibility, you should take into consideration all qualifications and condition codes that are accepted in this quota. For example - if your survey has a qualification on gender = male, and your quotas has criteria for ages 45-49, your feasibility request should contain both the gender qualification and the age qualification.

{
            "buyer_quota_id": "abc1",
            "required_count": 50,
            "criteria": [
                {
                    "qualification_code": 211,
                    "condition_codes": [
                        "111"
                    ]
                },
				{
                    "qualification_code": 212,
                    "range_sets": [
                        {
                            "from": 45,
                            "to": 49,
                            "units": 311
                        }
                    ]
                }
            ]
        }

Query String Parameters:

Response Parameter	Type	Description	Example

Response Parameter

Type

Description

Example

summary

integer - enum:

1: return feasibility without supplier information (default)

2: return feasibility by supplier for the targets

You may select the output type by switching between 1 (summary) or 2 (count by supplier)

1:

{
	"buyer_quota_id": "abc21",
	"count": 539,
	"unused_qualifications": []
}

2:

{
	"buyer_quota_id": "abc21",
	"count": 539,
	"unused_qualifications": [],
	"suppliers": [
       {
         "supplier_id": 23,
         "count": 539
       }
    ]
}

Request Body Parameters:

Request Parameter	Type	Required	Description

Request Parameter	Type	Required	Description
survey_localization	string	Yes	e.g. en_US , specifies the locale for which feasibility will be fetched.
completes_required	number	Yes	Specifies the number of completed interviews you need to this for survey.
expected_ir	number	Yes	Specifies the expected incidence of the target
expected_loi	number	Yes	Specifies the expected length of interview for the target
field_time	number	Yes	number of days in field
quotas	array of objects	Yes	Specifies the specific target quota for which we are returning feasibility.

`quotas` Array Body Parameters:

Request Parameter	Type	Required	Description

Request Parameter	Type	Required	Description
required_count	integer	Yes	Specifies the number of completed interviews you need to this target. The `count` for each supplier will display the max of this number, and the estimated feasibility. The `count` for the target will display the sum of those feasibility.
buyer_quota_id	string	Yes	This is a buyer defined identifier that will be used in the api response. Can be non-unique as it is a temporary id.
criteria	array of objects	Yes	specifies the list of targeting criteria to be factored into the feasibility calculation

`criteria` Array Body Parameters:

Behaves the same way as the quota creation call. You may reuse the model you use. Please be sure to include all qualification condition code options that you wish to be considered as part of this calculation.

Request Parameter	Type	Required	Description

Request Parameter	Type	Required	Description
qualification_code	integer	Yes
condition_codes	array of strings	either condition_code or range_sets is required
range_sets	array of objects	either condition_code or range_sets is required
range_sets.from	integer	required if range_sets is used
range_sets.to	integer	required if range_sets is used
range_sets.units	integer	required if range_sets is used	According to Codes & Units

Response Parameters:

Response Parameter	Type	Description	Example

Response Parameter	Type	Description	Example
quotas	array	Returns the feasibility for the quotas requested	See Below
recommended_cpi	decimal	Returns a recommended cpi that can be used when launching/creating the project Recommended_cpi is the average CPI of for all suppliers added in the survey. Regardless of the feasibility. It correlates in the UI with CPI when survey is launched.	1.32
feasibility_cpi	decimal	Feasibility CPI is the CPI for the supplier with feasibility in the system. It correlates in the UI with CPI when survey is in draft.
max_feasibility		These are Supplier input feasibility data. NOTE: The reason for 0 is that Suppliers are not inputting it.

Quotas Response Parameters:

Response Parameter	Type	Description	Example

Response Parameter	Type	Description	Example
count	integer	Number of estimated completes given targeting criteria, incidence rate, and device targeting for a survey. The `count` for each supplier will display the max of this number, and the estimated feasibility. The `count` for the target will display the sum of those feasibilities.	400
unused_qualifications	array of integers	Defines the qualification codes that were not factored into the calculation of `count`. If our service has no information on a qualification's genpop ir, we will not use it in the calculation for feasibility.	[1031, 1032]
buyer_quota_id	unique string	identifying underlying quota - this is unique within a survey, NOT across surveys.	abc123
suppliers	array	Only present if `summary=2` is set in the query string parameters. Array of supplier counts for the target.

`Suppliers` Response Parameters:

Response Parameter	Type	Description	Example

Response Parameter	Type	Description	Example
count	integer	Number of estimated completes given targeting criteria, incidence rate, and device targeting for a survey. The `count` for each supplier will display the max of this number, and the estimated feasibility. The `count` for the target will display the sum of those feasibilities.	400
supplier_id	integer	Supplier ID of the Supplier	1

Sample Request:

Sample Request

POST api.spectrumsurveys.com/buyers/v2/feasibility

{
    "survey_localization": "en_US",
    "completes_required": 100,
    "expected_ir": 50,
    "expected_loi": 5,
    "field_time": 7,
    "quotas": [
        {
            "buyer_quota_id": "abc1",
            "required_count": 50,
            "criteria": [
                {
                    "qualification_code": 211,
                    "condition_codes": [
                        "111"
                    ]
                }
            ]
        },
        {
            "buyer_quota_id": "abc2",
            "required_count": 50,
            "criteria": [
                {
                    "qualification_code": 212,
                    "range_sets": [
                        {
                            "from": 13,
                            "to": 99,
                            "units": 311
                        }
                    ]
                }
            ]
        }
    ]
}

Response

Response Code

200

Response Body

//?summary=1

{
    "quotas": [
        {
            "buyer_quota_id": "abc1",
            "count": 23,
            "unused_qualifications": []
        },
        {
            "buyer_quota_id": "abc2",
            "count": 14148176,
            "unused_qualifications": []
        }
    ],
	"recommended_cpi":1.38
}

//?summary=2

{
    "quotas": [
        {
            "buyer_quota_id": "abc1",
            "count": 23,
            "unused_qualifications": [],
            "suppliers": [
                {
                    "supplier_id": 2,
                    "count": 23
                }
            ]
        },
        {
            "buyer_quota_id": "abc2",
            "count": 14148176,
            "unused_qualifications": [],
            "suppliers": [
                {
                    "supplier_id": 2,
                    "count": 14148176
                }
            ]
        }
    ],
	"recommended_cpi":1.38
}

PureSpectrum Buyer API

Obtaining Feasibility & Pricing Without Creating Survey

Request

Considerations

Query String Parameters:

Request Body Parameters:

`quotas` Array Body Parameters:

`criteria` Array Body Parameters:

Response Parameters:

Quotas Response Parameters:

`Suppliers` Response Parameters:

Sample Request:

Sample Request

Response

Response Code

Response Body

Obtaining Feasibility & Pricing Without Creating Survey

Request

Considerations

Query String Parameters:

Request Body Parameters:

quotas Array Body Parameters:

criteria Array Body Parameters:

Response Parameters:

Quotas Response Parameters:

Suppliers Response Parameters:

Sample Request:

Sample Request

Response

Response Code

Response Body

`quotas` Array Body Parameters:

`criteria` Array Body Parameters:

`Suppliers` Response Parameters: