Request details
a detailed description of Feasibility parameters available in the request
POST /supplier/v1/feasibility-check
The bid request is structured into a JSON format and is then pushed to each appropriate supplier’s platform, using a POST method, to the URL endpoint provided by each integrated sample partner and stored on the S1 side under the usual accounts
Tips and tricks
jobNumberInternal - can be used to track which are the commissioned bids
countryCultures - multi-language feasibility requests need to be supported. For example on Canada: English and French projects are covering 73% from entire need, English only projects just 24%, French only projects 3%.
numberOfCompletes - it's a string that needs to support values like "max". Max being the case when we need back the maximum available capacity on the given target and quotas.
incidenceRatePercent - takes into account the quotas and target as described in the request
| Property | Description | Type | Required |
|---|---|---|---|
| bidId | A GUID ('Globally Unique Identifier') attached to each feasibility request. This ID can be used to link feasibility requests together. Under the same Bidid, multiple FeasibilityID can be generated | GUID | Yes |
| bidName | A human readable description to name a given request. | Text | No |
| FeasibilityID | A GUID identifier attached to each feasibility request. | GUID | Yes |
| jobNumberInternal | Project identifier, to be used as reference for billing process | Text | No |
| bidMode | Values available: PreCommissioning / Quoting stage - before project is awarded on the IIS side. Multiple bids versions can be made for the same project. PostCommissioning - after project is awarded. The project specs are set. Project is pre-field. InField - project is already in field. Learning – for cases when we need to learn about sample capabilities to be used in the feasibility process (cached version). | Text | Yes |
| bidSupportEmail | The email address that can be used to inquire about problems with the feasibly API or the usage of the partner endpoint. | Text / email | No |
| countryCode | The standard 2 letter country code for the specific country the current project will be fielded in. In this example “US” signals that this project will be fielded in United States. | Text / ISO Code | Yes |
| countryCultures | A list of “2-2” format language codes where a two-character language code & two digit country code is used to specify the languages required for the request. The example below specifies "en-US" and "es-US", which means that we are looking for both English and / or Spanish speakers. If for example the request would be only for English speakers, then the json will contain: "countryCultures":["en-us"] | List of text / ISO language code | Yes |
| numberOfCompletes | The number of completes required for the survey. If value is specified as “max”, then the answer needs to contain the maximum number of completes that can be achieved based on the audience definition (target & quotas). Tip: The reason for requesting the maximum number of completes, and not a specific value, is because we are searching for the best budget option based on different number of completes. In the same time, the maximum number of interviews will indicate as well the potential to achieve higher volumes | String | Yes |
| incidenceRatePercent | The incident rate in percent (0.0-100.0) as per the specified target. | Float | Yes |
| FieldDurations | Field duration input describing the number of hours / days a study is expected to stay in field. “4h” stands for a field duration of 4 hours, “12h” represents 12 hours, and 1d & 2d represent 1 day and 2days. Possible values: 4h, 12h, 16h, 1d, 2d, 3d, 4d, 5d, 6d, 7d If the request is for 5d and you are unable to check the feasibility for this FD, it's ok to check the feasibility on the closest duration to 5d that you can and send the response with the FD the feasibility was checked on. | List of strings | Yes |
| collectPii | If true, the survey will collect personally identifiable information from the respondent | Boolean | Yes |
| Facialcoding | If true, the survey will require the respondent to permit a web cam to validate the respondent’s engagement during the survey | Boolean | Yes |
| freshSample | COMING SOON | Boolean | No |
| fieldStartDate | The time in UTC when the survey is expected to launch. | Text / UTC-Date | No |
| lengthOfInterview | The average number of minutes that a respondent should need to finish the survey | Number | Yes |
| preferredCurrency | The standard 3 letter currency code for the expected currency in the answer for CPI value. In this example “USD” signals that this the answer for CPI is expected in USD currency. This is not a mandatory requirement, as the answer can support any currency if correctly specified. | Text / ISO Code | Yes |
| sampleCategory | The expected sample category of the survey. The values are available by using the method sample-category-list. The value of the “sampleCategory” field will correspond with one of the “categoryNames” values returned by the sample-category-list supplier API method. | Text | No |
| sampleSubCategory | The expected sample subcategory for the survey. The values are available by using the method sample-category-list. The “sampleSubCaterory” corresponds with one of the “name” values of a category’s “subcategory” list from the sample-category-list supplier API method. Note: Not call sampleCategories have a subcategory and this value may be null. | Text | No |
| researchType | The “researchType” field will be the “name” field from the list of Ipsos research categories available from mthode research-types | Text | Yes |
| researchCategories | The survey will have one or more categories corresponding with the list of Ipsos research categories available with method: categories. The “name” value of the category hierarchy in the categories where the category is the child category (by parent id) to the generic category, which itself is a child of the mainCategory (also by parent id). Any number of category tuples can be sent in the list. | list of objects with keys of mainCategory, genericCategory, and category | No |
| allowMobile | If true, the survey will allow mobile respondents to complete the survey | Boolean | Yes |
| allowTablet | If true, the survey will allow tablet respondents to complete the survey | Boolean | Yes |
| allowDesktop | If true, the survey will allow desktop respondents to complete the survey | Boolean | Yes |
| Target | A list of “target” objects with their fields defined below. | Array | Yes |
| Quotas | A list of “quota” objects with their fields defined below. | Array | Yes |
| needRecontact | If true, the supplier should recontact panelists on specific type of surveys | Boolean | Yes |
{
"bidId":"S1-Event-532670",
"bidName":"Name of the Bid",
"feasibilityId":"a3f5be49-571d-49f0-8ae7-270569e1449f",
"jobNumberInternal":"1805257401",
"bidMode":"PreCommissioning",
"bidSupportEmail":"[email protected]",
"countryCode":"US",
"countryCultures":[
"en-us",
"es-us"
],
"numberOfCompletes":"max",
"incidenceRatePercent":80.0,
"fieldDurations":[
"4h"
],
"collectPii":false,
"facialCoding":false,
"freshSample":true,
"fieldStartDate":"2019-05-30T22:00:00Z",
"lengthOfInterview":15,
"preferredCurrency":"USD",
"sampleCategory":"Gen pop sample",
"sampleSubCategory":"",
"researchType":"Other (MKT, PLM, Tracking etc.)",
"researchCategories":[
{
"mainCategory":"Food and Beverages",
"genericCategory":"FOOD-CONDIMENTS/SEASONING/SAUCES",
"category":"SALAD DRESSING/SALAD OIL"
}
],
"allowMobile":false,
"allowTablet":true,
"allowDesktop":true,
"quotaTables":[
{
"tableName":"Table:agerange: x ",
"quotas":[
{
"quotaId":"7c4f3cde-de4a-4b78-a2f7-1ac04fd55947",
"quotaName":"agerange_1-E1",
"interviewType":"completes",
"questions":[
{
"answers":[
{
"id":-1,
"rangeStart":"18",
"rangeEnd":"24"
}
],
"id":-1,
"operator":"OR"
}
],
"percentage":14.0
},
{
"quotaId":"8a559028-6365-4557-a036-44e564e37988",
"quotaName":"agerange_2-E1",
"interviewType":"completes",
"questions":[
{
"answers":[
{
"id":-1,
"rangeStart":"25",
"rangeEnd":"34"
}
],
"id":-1,
"operator":"OR"
}
],
"percentage":22.0
},
{
"quotaId":"857dfa0f-612f-45ac-8bbb-df04deecdd4d",
"quotaName":"agerange_3-E1",
"interviewType":"completes",
"questions":[
{
"answers":[
{
"id":-1,
"rangeStart":"35",
"rangeEnd":"44"
}
],
"id":-1,
"operator":"OR"
}
],
"percentage":20.0
},
{
"quotaId":"f0e4004a-0bb5-4317-bd5d-ac02a8da4cdd",
"quotaName":"agerange_4-E1",
"interviewType":"completes",
"questions":[
{
"answers":[
{
"id":-1,
"rangeStart":"45",
"rangeEnd":"54"
}
],
"id":-1,
"operator":"OR"
}
],
"percentage":22.0
},
{
"quotaId":"99fb3f7e-dfae-4a23-9a00-637d34dca0a1",
"quotaName":"agerange_5-E1",
"interviewType":"completes",
"questions":[
{
"answers":[
{
"id":-1,
"rangeStart":"55",
"rangeEnd":"65"
}
],
"id":-1,
"operator":"OR"
}
],
"percentage":22.0
}
]
},
{
"tableName":"Table:Gender S1 - NA: x ",
"quotas":[
{
"quotaId":"b90c7c7c-de3a-4434-8d4b-03f26ae9e8c6",
"quotaName":"resp_genderfemale-E1",
"interviewType":"completes",
"questions":[
{
"answers":[
{
"id":65236
}
],
"id":12203,
"operator":"OR"
}
],
"percentage":51.0,
"completes":null,
"maxCompletes":null
},
{
"quotaId":"8a31b6b2-fc1c-4125-9f12-417f32d11397",
"quotaName":"resp_gendermale-E1",
"interviewType":"completes",
"questions":[
{
"answers":[
{
"id":65237
}
],
"id":12203,
"operator":"OR"
}
],
"percentage":49.0
}
]
}
],
"target":[
{
"questions":[
{
"id":-1,
"answers":[
{
"id":-1,
"rangeStart":"1",
"rangeEnd":"65"
}
],
"operator":"OR"
}
]
},
{
"questions":[
{
"id":12203,
"answers":[
{
"id":65236
},
{
"id":65237
}
]
}
]
}
]
}
Updated over 1 year ago