demand api - v7 - for print

8/12/2019 Demand API - V7 - For Print

1/23

Version 7 March 2014

Federated Sample Demand API Documentation


2/23

Page | i

Table of Contents

1. Overview ........................................................................................................................... 1

1.1 Workflow ...................................................................................................................... 1

2. Getting Started .................................................................................................................. 4

2.1 Call Frequency ............................................................................................................. 4

2.2 Base URL ...................................................................................................................... 5

2.3 Testing ......................................................................................................................... 5

3. Survey Creation & Management ........................................................................................ 5

3.1 Surveys/Create (Method 1) .......................................................................................... 5

3.2 Surveys/BySurveyNumber (Method 2a) ....................................................................... 7

3.3 Surveys/BySurveyStatus (Method 2b) .......................................................................... 7

3.4 Surveys/Update (Method 3) ......................................................................................... 8

4. Qualification Creation & Management .............................................................................. 10

4.1 SurveyQualifications/Create (Method 4) .................................................................... 10

4.2 SurveyQualifications/BySurveyNumber (Method 5) ................................................... 10

4.3 SurveyQualifications/Update (Method 6) ................................................................... 11

5. Quota Creation & Management ........................................................................................ 12

5.1 SurveyQuotas/Create (Method 7) ............................................................................... 125.2 SurveyQuotas/BySurveyNumber (Method 8) .............................................................. 13

5.3 SurveyQuotas/Update (Method 9) .............................................................................. 14

6. Allocation Creation & Management .................................................................................. 15

6.1 SupplierAllocations/Create (Method 10)..................................................................... 15

6.2 SupplierAllocations/BySurveyNumber (Method 11) ................................................... 15

6.3 SupplierAllocations/Update (Method 12) .................................................................... 16

A. Survey Parameter Details ................................................................................................ 18

B. Data Mapping .................................................................................................................. 19


3/23

Page | 1

1. Overview

Federated Sample brings efficiency and automation to online sampling with

Fulcrum, todays most powerful, open, and customizable online sampling platform.

For sample buyers, this means gaining instant and cost effective access to

respondents from hundreds of panel sources globally through the Sample

Exchange. Using Fulcrum helps save time and money by making it possible to

target hard-to-reach audiences and low incidence populations, and improves

delivery so projects are complete and on time.

The Fulcrum Demand API makes it possible for integrated clients to create a survey

in Fulcrum and manage it in-field without having to log in to the platform. The

methods work together so that surveys can be created and managed without

having to perform duplicate data entry across multiple systems. By providing aminimal number of required fields, a survey can be created in Fulcrum and run on

an automated basis.

The Demand API currently consists of methods that allow for Survey, Qualification,

and Quota Creation & Management.

The API is based on REST (REpresentational State Transfer) principles, which

makes it very easy to write and test applications. Both JSON and XML data formats

are supported.

1.1 WorkflowWhile there are many ways to integrate, the following are example use cases for

Fulcrums Demand API.

Create a New

Survey in

Fulcrum

Create SurveyAdd

QualificationsAdd Quotas

Change Survey

Status to Live

Surveys/Create

Survey

Qualifications/

Create

SurveyQuotas/

Create

Surveys/UpdateAwarded Live

New Live

Survey in

Fulcrum


4/23

Page | 2

Change

Exchange

Allocation

Change

Fulcrum

Exchange

Allocation

Surveys/Update

Updated

Exchange

Allocation

Sync Fulcrum

Quotas with

Survey

Quotas

Update Quota

Remaining

Numbers

SurveyQuotas/

Update

Updated

Quotas in

Fulcrum

Make

Changes to

Survey

Parameters

Edit Survey

Details

Edit

QualificationsEdit Quotas

Surveys/UpdateSurvey

Qualifications/

Update

SurveyQuotas/

Update

Updated

Survey in

Fulcrum

Remove

Qualifications

Remove a

Qualification

Survey

Qualifications/

UpdateActive Inactive

Qualification

Removed


5/23

Page | 3

Remove

Quotas

Remove a

Quota

SurveyQuotas/

UpdateActive Inactive

Quota

Removed

Close a

Survey in

Fulcrum

Close a Survey

Surveys/UpdateLive Complete

Closed Survey


6/23

Page | 4

2. Getting Started

Federated Sample provides API development support. All suppliers that integrate

with Federated Samples Demand API should follow this process:

2.1 Call FrequencyWhile API calls can be made easily and often, Federated Sample may limit or block

access to the API if calls are made too frequently.

Demand API

Integration Process

Sales & Documentation Overview

Business Side Kickoff Call

Spec API (Generic Test Key)

Development Call

Develop in Staging Environment (Test Key)

Weekly Calls

Demographic Mapping

Final Approval

Launch in Production (Encrypted Production Key)

Launch Projects in Fulcrum

Followup Calls


7/23

Page | 5

2.2 Base URLAll URLs referenced in the documentation have the following base:

http://vpc-apiloadbalancer-991355604.us-east-1.elb.amazonaws.com/Demand/v1/

2.3 TestingFederated Sample provides developers with a way to test the Demand API

methods without disturbing real data through the following entry point:

http://vpc-stg-apiloadbalancer-1968605456.us-east-

1.elb.amazonaws.com/Demand/v1/

The API requires an encrypted key to retrieve information about surveys and

create entry links.

The following codes may be used to gain preliminary insight about the Demand

API:

Test Key: 5175285E-D74B-46A8-AE2C-EF95B3A5175B

Account ID: 11

The API requires a key. Please email [email protected] request

your test key so you can begin testing.

Once testing is complete, please email [email protected] get your

API key to access the production API.

3. Survey Creation & Management

The survey creation and management methods allow users to create a survey in

Fulcrum, and update that surveys details.

3.1 Surveys/Create (Method 1)In order to create a new survey, there are a minimum number of fields required to

be filled in order for the survey to be added to the Survey Quota Pool list, and

consequently receive traffic. These minimum parameters must be passed in, else

survey creation will fail.


8/23

Page | 6

Method Name Create Survey

Synopsis Creates a survey in Fulcrum.

HTTP Method POST

URL (XML) /Surveys/Create/xml?key={EncryptedKey}URL (JSON) /Surveys/Create?key={EncryptedKey}

Request Parameters Required Value Default Value Response Parameters

AccountID {AccountID} AccountID

SurveyStatusCode 01 SurveyStatusCode

SurveyPriority 11 SurveyPriority

SurveyNumber NULL SurveyNumber

SurveyName {SurveyName} SurveyName

CountryLanguageID {CountryLanguageID}

CountryLanguageID

IndustryID 30 IndustryID

StudyTypeID 6 StudyTypeID

ClientCPI $ 0 ClientCPI

QuotaCPI $ 1 QuotaCPI

ClientSurveyLiveURL {URL} ClientSurveyLiveURL

TestRedirectURL {URL} TestRedirectURL

IsActive true IsActive

Quota 0 QuotaSampliciousAllocatio

n9

0 SampliciousAllocatio

n

SampliciousHedgeAc

cess

{HedgeAccess} SampliciousHedgeAc

cess

1Please refer to Appendix A for full parameter details.

2At a minimum, NULL must be passed in for all Request Parameters without Required Values.

3SurveyPriority is a value between 1 and 11, with 1 being the highest priority. No more than 15%

of any accounts surveys may have priority 1 10; all other surveys must have priority 11.4

In Fulcrum, each survey can only have one country and language. For projects where more thanone country or language are sent to the same survey (outside of Fulcrum), multiple Fulcrumprojects must be created.5 The only instances where a study type must be correctly identified are for recruit-type and

incidence checks. Otherwise, most studies can be labeled as adhocs.6ClientCPI can be set to $0 with no functional consequences. This is used in the Financial Report.

7QuotaCPI affects the traffic into the survey. The higher the QuotaCPI, the more routed traffic a

survey will receive.8Setting IsActive to false is equivalent to deleting a survey in Fulcrum.

9SampliciousAllocation is the percentage of quota reserved for Fulcrum delivered completes.


9/23

Page | 7

3.2 Surveys/BySurveyNumber (Method 2a)Surveys can be retrieved by survey number.

Method Name Get Survey by Survey NumberSynopsis Retrieves the details about a specific survey.

HTTP Method GET

URL (XML) /Surveys/BySurveyNumber/xml/{SurveyNumber}?key={En

cryptedKey}

URL (JSON) /Surveys/BySurveyNumber/{SurveyNumber}?key={Encrypt

edKey}

Request

Parameters

Response Parameters

AccountID

SurveyStatusCode

SurveyPriority

SurveyNumber

SurveyName

CountryLanguageID

IndustryID

StudyTypeID

ClientCPIQuotaCPI

ClientSurveyLiveURL

TestRedirectURL

IsActive

Quota

SampliciousAllocatio

n

SampliciousHedgeAc

cess

3.3 Surveys/BySurveyStatus (Method 2b)A list of all an accounts surveys with a certain status can be retrieved with this

method.


10/23

Page | 8

Method Name Get Surveys by Survey Status

Synopsis Retrieves information about all surveys that have a certain

status.

HTTP Method GETURL (XML) /Surveys/BySurveyStatus/xml/{SurveyStatusCode}?key={E

ncryptedKey}

URL (JSON) /Surveys/BySurveyStatus/{SurveyStatusCode}?key={Encry

ptedKey}

Request

Parameters

Response

Parameters10

AccountID

SurveyStatusCodeSurveyPriority

SurveyNumber

SurveyName

CountryLanguageID

IndustryID

StudyTypeID

ClientCPI

QuotaCPI

ClientSurveyLiveURLTestRedirectURL

IsActive

Quota

SampliciousAllocation

SampliciousHedgeAcc

ess

3.4 Surveys/Update (Method 3)

The survey fields created in the first method, Create Survey, can be updated bythe Update Survey method.

10These response parameters will be returned for all surveys with the associated SurveyStatusCode.


11/23

Page | 9

Method Name Update Survey

Synopsis Allows changes to most survey details fields.

HTTP Method PUT

URL (XML) /Surveys/Update/xml/{SurveyNumber}?key={EncryptedKey}

URL (JSON) /Surveys/Update/{SurveyNumber}?key={EncryptedKey}

Request Parameters Updateable Response Parameters

AccountID No AccountID

SurveyStatusCode Yes SurveyStatusCode

SurveyPriority Yes SurveyPriority

SurveyNumber No SurveyNumber

SurveyName Yes SurveyNameCountryLanguageID Yes CountryLanguageID

IndustryID Yes IndustryID

StudyTypeID Yes StudyTypeID

ClientCPI Yes ClientCPI

QuotaCPI Yes QuotaCPI

ClientSurveyLiveURL Yes ClientSurveyLiveURL

TestRedirectURL Yes TestRedirectURL

IsActive Yes IsActive

Quota Yes QuotaSampliciousAllocatio

n

Yes SampliciousAllocatio

n

SampliciousHedgeAc

cess

Yes SampliciousHedgeAc

cess


12/23

Page | 10

4. Qualification Creation & Management

The qualification creation and management methods allow Fulcrum standard

qualifications to be added and edited.

Approximately 80 standard qualifications may be added and edit via the Demand

API. Please refer to Standard Master document on Zendesk for a list of the

qualifications and their associated precodes:

https://federatedsample.zendesk.com/entries/20133208-Standard-Qualifications

4.1 SurveyQualifications/Create (Method 4)In order to add a qualification, there are a minimum number of fields required to

be filled in order for the qualification to be added to the survey. These minimumparameters must be passed in; else the qualification will fail to be added.

Method Name Create Qualification

Synopsis Adds a standard qualification to a survey.

HTTP Method POST

URL (XML) /SurveyQualifications/Create/xml/{SurveyNumber}?key={

EncryptedKey}

URL (JSON) /SurveyQualifications/Create/{SurveyNumber}?key={Encr

yptedKey}

Request Parameters Recommended Value Response Parameters

Name Name

QuestionID QuestionID

LogicalOperator OR LogicalOperator

NumberOfRequiredCondi

tions

1 NumberOfRequiredConditi

ons

IsActive true IsActive

PreCodes PreCodes

4.2 SurveyQualifications/BySurveyNumber (Method 5)A list of a surveys qualifications can be retrieved by survey number.


13/23

Page | 11

Method Name Get Qualifications by Survey Number

Synopsis Retrieves a specific surveys qualification information.

HTTP Method GET

URL (XML) /SurveyQualifications/BySurveyNumber/xml/{SurveyNumber}?key={EncryptedKey}

URL (JSON) /SurveyQualifications/BySurveyNumber/{SurveyNumber}?k

ey={EncryptedKey}

Request Parameters Response Parameters

Name

QuestionID

LogicalOperator

NumberOfRequiredConditions

IsActive

PreCodes

4.3 SurveyQualifications/Update (Method 6)The qualification fields created in the first method, Create Qualification, can be

updated by the Update Qualification method.

Method Name Update QualificationSynopsis Makes changes to a standard qualification in a survey.

HTTP Method PUT

URL (XML) /SurveyQualifications/Update/xml/{SurveyNumber}?key={

EncryptedKey}

URL (JSON) /SurveyQualifications/Update/{SurveyNumber}?key={Encr

yptedKey}


14/23

Page | 12


Name Yes Name

QuestionID No QuestionID

LogicalOperator Yes LogicalOperatorNumberOfRequiredCondi

tions

Yes NumberOfRequiredCondit

ions


PreCodes Yes PreCodes

5. Quota Creation & Management

The quota creation and management methods will allow users to add and update

survey quotas.

5.1 SurveyQuotas/Create (Method 7)Quota creation will only be allowed for quotas with conditions from the list of API

standard qualifications.

The API will not allow a quota to be created where the corresponding condition is

not present, e.g. to build a quota for males, the GENDER qualification and male

condition must both be included.

Method Name Create Quota

Synopsis Adds a quota to a survey.

HTTP Method POST

URL (XML) /SurveyQuotas/Create/xml/{SurveyNumber}?key={Encryp

tedKey}

URL (JSON) /SurveyQuotas/Create/{SurveyNumber}?key={EncryptedK

ey}


15/23

Page | 13

Request Parameters Recommended Value Response Parameters

SurveyQuotaID

Name Name

Quota QuotaIsActive true IsActive

Conditions

- QuestionID- PreCodes

Conditions


5.2 SurveyQuotas/BySurveyNumber (Method 8)A list of a surveys quotas can be retrieved by survey number.

Method Name Get Quotas by Survey NumberSynopsis Retrieves the quotas for a particular survey.

HTTP Method GET

URL (XML) /SurveyQuotas/BySurveyNumber/xml/{SurveyNumber}?ke

y={EncryptedKey}

URL (JSON) /SurveyQuotas/BySurveyNumber/{SurveyNumber}?key={

EncryptedKey}


SurveyQuotaIDName

Quota

IsActive

Conditions


Total Quota

- Quota- Prescreens- Completes- QuotaTypeID

Individual Quotas

- Prescreens- Completes- QuotaTypeCode


16/23

Page | 14

5.3 SurveyQuotas/Update (Method 9)The quota fields created in the first method, SurveyQuotas/Create, can be updated

by the SurveyQuotas/Update method.

Specific elements within nested quotas can be updated by identifying the relevant

QuestionID and QuotaConditionValues. For instance, to change the nested quota

Gender: Male, Age: 18-24, Region: East and only change Male to Female, but

leave Age as 18-24, send in the QuestionID for Gender and QuotaConditionValue

for female only and nothing related to Age.

Method Name Update Quota

Synopsis Makes changes to a particular survey quota.

HTTP Method PUT

URL (XML) /SurveyQuotas/Update/xml/{SurveyNumber}?key={Encry

ptedKey}

URL (JSON) /SurveyQuotas/Update/{SurveyNumber}?key={Encrypted

Key}


SurveyQuotaID No SurveyQuotaID

Name Yes Name

Quota Yes Quota


Conditions


Yes Conditions


In most instances, only the quota values need to be updated, not the entire quota

itself. The API call for this update does not include conditions.


SurveyQuotaID No SurveyQuotaID

Name Yes Name

Quota Yes Quota



17/23

Page | 15

6. Allocation Creation & Management

The allocation creation and management methods will allow users to add and

update survey allocations for each individual supplier.

6.1 SupplierAllocations/Create (Method 10)In order to add an allocation for an individual supplier, there are a minimum

number of fields required to be filled in order for the allocation to be added to the

survey. These minimum parameters must be passed in; else the allocation will fail

to be added.

Method Name Create Allocation

Synopsis Adds an individual supplier allocation to a survey.

HTTP Method POST

URL (XML) /SupplierAllocations/Create/xml/{SurveyNumber}?key={E

ncryptedKey}

URL (JSON) /SupplierAllocations/Create/{SurveyNumber}?key={Encry

ptedKey}


SupplierCode No SupplierCode

AllocationPercentage Yes AllocationPercentage

HedgeAccess Yes HedgeAccess

BlockRouterTraffic Yes BlockRouterTraffic

TCPI Yes TCPI

SupplierAllocationTargetModel Yes SupplierAllocationTargetModel

Prescreens

Completes

AllocationRemaining

HedgeRemaining

TotalRemaining

6.2 SupplierAllocations/BySurveyNumber (Method 11)A list of a surveys allocations can be retrieved by survey number.


18/23

Page | 16

Method Name List Allocations

Synopsis Retrieves the supplier allocations for a particular survey.

HTTP Method GET

URL (XML) /SupplierAllocations/BySurveyNumber/xml/{SurveyNumber}?key={EncryptedKey}

URL (JSON) /SupplierAllocations/BySurveyNumber/{SurveyNumber}?k

ey={EncryptedKey}


SurveyNumber SupplierCode

AllocationPercentage

HedgeAccess

BlockRouterTrafficTCPI

SupplierAllocationTargetModel

Prescreens

Completes

AllocationRemaining

HedgeRemaining

TotalRemaining

6.3 SupplierAllocations/Update (Method 12)The allocation fields created in the first method, SurveyAllocations/Create, can be

updated by the SurveyAllocations/Update method.

Method Name Update Allocations

Synopsis Makes changes to a particular suppliers allocations.

HTTP Method PUT

URL (XML) /SupplierAllocations/Update/xml/{SurveyNumber}?key={E

ncryptedKey}

URL (JSON) /SupplierAllocations/Update/{SurveyNumber}?key={EncryptedKey}


19/23

Page | 17


SupplierCode No SupplierCode

AllocationPercentage No AllocationPercentage

HedgeAccess No HedgeAccessBlockRouterTraffic Yes BlockRouterTraffic

TCPI Yes TCPI

SupplierAllocationTargetModel Yes SupplierAllocationTargetModel

Yes Prescreens

Yes Completes

Yes AllocationRemaining

Yes HedgeRemaining

Yes TotalRemaining


20/23

Page | 18

A. Survey Parameter Details

Parameter Datatype Range Description

ResultCount int N/A Number of parent elements returned in response

AllocationResponse N/A N/A Parent ElementAccountID int Unique number associated with the account

SurveyStatus int Defines the status of a survey. Please refer to data

SurveyPriority int Priority of the survey

SurveyName nvarchar Max Len = 2000 characters Name of the survey

CountryLanguageID int 0 to 999999

Country and Language associated with the survey.

Please refer to data map

IndustryID int 0 to 999999

Industry associated with the survey. Please refer

to data map.

StudyTypeID string

Study type associated with the survey. Please

refer to data map.

ClientCPI float 0 to 999999 The revenue to the buyer of the complete

QuotaCPI float 0 to 999999

The survey-level buyer bid price. The amount the

buyer is wil ling to pay for routed sample.

Cl ientSurveyURLLive nvarchar Max Len = 1500 characters

The URL of the live client survey a respondent is

sent to upon successfully prescreening

IsActive string "true" or "false" Indicates if survey is active or inactive

Quota int 0 to 999999 The survey's total quota

FulcrumExchangeAllocation double 0 to 100

The percentage of Exchange/Offerwall traffic that

is allocated to a survey


21/23

Page | 19

B. Data MappingURL Parameter Description ID Value (part of call) ID Text (not part of call)

SurveyStatus 06 Canceled - Non Charged

02 Pending

03 Live

04 Complete

01 Awarded

05 Canceled - With Charge

09 Invoiced

07 Complete - Non Charged

08 Completes Approved

URL Parameter Description ID Value (part of call) ID Text (not part of call)

CountryLanguageID Country and Language associated with they survey. 1 Chinese Traditional - China

2 Chinese Traditional - Hong Kong

3 Chinese Traditional - Taiwan

4 Dutch - Netherlands

5 English - Australia

6 English - Canada

7 English - India

8 English - United Kingdom

9 English - United States

10 French - France

11German - Germany

12 German - Switzerland

13 Italian - Italy

14 Japanese - Japan

15 Polish - Poland

16 Portuguese - Brazil

17 Portuguese - Portugal

18 Russian - Russia

19 Spanish - Argentina

20 Spanish - Colombia

21 Spanish - Mexico

22 Spanish - Spain

23 Swedish - Sweden

24 Korean - Korea

25 French - Canada

26 French - Belgium

27 Spanish - United States

28 Dutch - Belgium

29 Arabic - Saudi Arabia

30 Norwegian - Norway

31Danish - Denmark

32 Finnish - Finland

34 French - Switzerland

35 Italian - Switzerland

36 English - Switzerland

37 Turkish - Turkey

38 German - Austria

39 Czech - Czech Republic40 Greek - Greece


22/23

Page | 20


CountryLanguageID Country and Language associated with they survey. 41Spanish - Venezuela

42 Icelandic - Iceland

43 English - Ireland

44 Belgian - Belgium

45 Romanian - Romania

46 Bulgarian - Bulgaria

47 Spanish - Chile

49 English - South Africa

50 English - Singapore

51Luxembourg - Luxembourg

52 Indonesian - Indonesia

53 Malay - Malaysia

54 Thai - Thailand

55 Tagalog - Philippines

56 Ukrainian - Ukraine

57 English - New Zealand

58 English - Philippines

59 English - Indonesia

60 Bahasa Melayu - Singapore

61 English - Malaysia

62 Hungarian - Hungary63 Latvian - Latvia

64 Spanish - Costa Rica

65 Spanish - El Salvador

66 Spanish - Guatemala

67 Spanish - Honduras

68 Spanish - Nicaragua

69 Spanish - Panama

70 Estonian - Estonia

71Lithuanian - Lithuania

72 Hebrew - Israel

73 English - Hong Kong

74 English - Germany

75 Zulu - South Africa

76 Hindi - India

77 Arabic - Egypt78 Slovak - Slovakia

79 Slovene - Slovenia

80 Spanish - Peru

81Vietnamese - Vietnam

82 Arabic - United Arab Emirates

83 Arabic - Qatar


23/23

Page | 21


IndustryID Industry associated with the survey. 1 Automotive

2 Beauty/Cosmetics

3 Beverages - Alcoholic

4 Beverages - Non Alcoholic

5 Education

6 Electronics/Computer/Software

7 Entertainment (Movies, Music, TV, etc)

8 Fashion/Clothing

9 Financial Services/Insurance

10 Food/Snacks

11 Gambling/Lottery

12 Healthcare/Pharmaceuticals

13 Home (Utilit ies, Appliances, ...)

14 Home Entertainment (DVD, VHS)

15 Home Improvement/Real Estate/Construction

16 IT (Servers, Databases, etc)

17 Personal Care/Toiletries

18 Pets

19 Politics

20 Publishing (Newspaper, Magazines, Books)

21Restaurants22 Sports

23 Telecommunications (phone, cell phone, cable)

24 Tobacco (Smokers)

25 Toys

26 Transportation/Shipping

27 Travel

28 Video Games

29 Websites/Internet/E-Commerce

30 Other

31Sensitive Content

32 Explicit Content


StudyTypeID Study type associated with the survey. 1Adhoc

2 Diary

3 Focus Group - Offline

4 Focus Group - Online

5 IHUT

6 Other

7 Phone to Web

8 Recruit - CLT

9 Recruit - F2F

10 Recruit - Focus Group

11 Recruit - Panel

12 Recruit - Recontact

13 Tracking - Monthly

14 Tracking - Quarterly

15 Tracking - Weekly

16 Wave Study

17 Web to Phone

18 Internal Use19 Top Off

20 End of Router

demand api - v7 - for print

Documents