Version 7 March 2014

Federated Sample
Demand API Documentation

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) ............................................................................... 12
5.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


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 a
minimal 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 Workflow
While there are many ways to integrate, the following are example use cases for
Fulcrums Demand API.


Create a New
Survey in
Fulcrum
Create Survey
Add
Qualifications
Add Quotas
Change Survey
Status to Live
Surveys/Create
Survey
Qualifications/
Create
SurveyQuotas/
Create
Surveys/Update
Awarded Live
New Live
Survey in
Fulcrum

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
Qualifications
Edit Quotas
Surveys/Update
Survey
Qualifications/
Update
Survey
Quotas/
Update
Updated
Survey in
Fulcrum
Remove
Qualifications
Remove a
Qualification
Survey
Qualifications/
Update
Active Inactive
Qualification
Removed

Page | 3













Remove
Quotas
Remove a
Quota
SurveyQuotas/
Update
Active Inactive
Quota
Removed
Close a
Survey in
Fulcrum
Close a Survey
Surveys/Update
Live Complete
Closed Survey

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 Frequency
While 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

Page | 5

2.2 Base URL
All URLs referenced in the documentation have the following base:
http://vpc-apiloadbalancer-991355604.us-east-1.elb.amazonaws.com/Demand/v1/

2.3 Testing
Federated 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 support@federatedsample.com to request
your test key so you can begin testing.

Once testing is complete, please email support@federatedsample.com to 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.




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
1
Required Value
2
Default Value Response Parameters
AccountID {AccountID} AccountID
SurveyStatusCode 01 SurveyStatusCode
SurveyPriority
3
11 SurveyPriority
SurveyNumber NULL SurveyNumber
SurveyName {SurveyName} SurveyName
CountryLanguageID
4
{CountryLanguag
eID}
CountryLanguageID
IndustryID 30 IndustryID
StudyTypeID
5
6 StudyTypeID
ClientCPI
6
$ 0 ClientCPI
QuotaCPI
7
$ 1 QuotaCPI
ClientSurveyLiveURL {URL} ClientSurveyLiveURL
TestRedirectURL {URL} TestRedirectURL
IsActive
8
true IsActive
Quota 0 Quota
SampliciousAllocatio
n
9

0 SampliciousAllocatio
n
SampliciousHedgeAc
cess
{HedgeAccess} SampliciousHedgeAc
cess

1
Please refer to Appendix A for full parameter details.
2
At a minimum, NULL must be passed in for all Request Parameters without Required Values.
3
SurveyPriority 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 than
one country or language are sent to the same survey (outside of Fulcrum), multiple Fulcrum
projects 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.
6
ClientCPI can be set to $0 with no functional consequences. This is used in the Financial Report.
7
QuotaCPI affects the traffic into the survey. The higher the QuotaCPI, the more routed traffic a
survey will receive.
8
Setting IsActive to false is equivalent to deleting a survey in Fulcrum.
9
SampliciousAllocation is the percentage of quota reserved for Fulcrum delivered completes.

Page | 7

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

Method Name Get Survey by Survey Number
Synopsis 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
ClientCPI
QuotaCPI
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.


Page | 8

Method Name Get Surveys by Survey Status
Synopsis Retrieves information about all surveys that have a certain
status.
HTTP Method GET
URL (XML) /Surveys/BySurveyStatus/xml/{SurveyStatusCode}?key={E
ncryptedKey}
URL (JSON) /Surveys/BySurveyStatus/{SurveyStatusCode}?key={Encry
ptedKey}

Request
Parameters
Response
Parameters
10

AccountID
SurveyStatusCode
SurveyPriority
SurveyNumber
SurveyName
CountryLanguageID
IndustryID
StudyTypeID
ClientCPI
QuotaCPI
ClientSurveyLiveURL
TestRedirectURL
IsActive
Quota
SampliciousAllocation
SampliciousHedgeAcc
ess

3.4 Surveys/Update (Method 3)
The survey fields created in the first method, Create Survey, can be updated by
the Update Survey method.




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

Page | 9

Method Name Update Survey
Synopsis Allows changes to most survey details fields.
HTTP Method PUT
URL (XML) /Surveys/Update/xml/{SurveyNumber}?key={EncryptedKe
y}
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 SurveyName
CountryLanguageID 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 Quota
SampliciousAllocatio
n
Yes SampliciousAllocatio
n
SampliciousHedgeAc
cess
Yes SampliciousHedgeAc
cess

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 minimum
parameters 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.



Page | 11

Method Name Get Qualifications by Survey Number
Synopsis Retrieves a specific surveys qualification information.
HTTP Method GET
URL (XML) /SurveyQualifications/BySurveyNumber/xml/{SurveyNumbe
r}?key={EncryptedKey}
URL (JSON) /SurveyQualifications/BySurveyNumber/{SurveyNumber}?k
ey={EncryptedKey}

Request Parameters Response Parameters
Name
QuestionID
LogicalOperator
NumberOfRequiredConditi
ons
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 Qualification
Synopsis 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}










Page | 12

Request Parameters Updateable Response Parameters
Name Yes Name
QuestionID No QuestionID
LogicalOperator Yes LogicalOperator
NumberOfRequiredCondi
tions
Yes NumberOfRequiredCondit
ions
IsActive Yes IsActive
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}








Page | 13

Request Parameters Recommended Value Response Parameters
SurveyQuotaID
Name Name
Quota Quota
IsActive true IsActive
Conditions
- QuestionID
- PreCodes
Conditions
- QuestionID
- PreCodes

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

Method Name Get Quotas by Survey Number
Synopsis 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}

Request Parameters Response Parameters
SurveyQuotaID
Name
Quota
IsActive
Conditions
- QuestionID
- PreCodes
Total Quota
- Quota
- Prescreens
- Completes
- QuotaTypeID
Individual Quotas
- Prescreens
- Completes
- QuotaTypeCode

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}

Request Parameters Updateable Response Parameters
SurveyQuotaID No SurveyQuotaID
Name Yes Name
Quota Yes Quota
IsActive Yes IsActive
Conditions
- QuestionID
- PreCodes
Yes Conditions
- QuestionID
- PreCodes

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.

Request Parameters Updateable Response Parameters
SurveyQuotaID No SurveyQuotaID
Name Yes Name
Quota Yes Quota
IsActive Yes IsActive



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}

Request Parameters Updateable Response Parameters
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.




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}

Request Parameters Response Parameters
SurveyNumber SupplierCode
AllocationPercentage
HedgeAccess
BlockRouterTraffic
TCPI
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={Encry
ptedKey}





Page | 17

Request Parameters Updateable Response Parameters
SupplierCode No SupplierCode
AllocationPercentage No AllocationPercentage
HedgeAccess No HedgeAccess
BlockRouterTraffic Yes BlockRouterTraffic
TCPI Yes TCPI
SupplierAllocationTargetModel Yes SupplierAllocationTargetModel
Yes Prescreens
Yes Completes
Yes AllocationRemaining
Yes HedgeRemaining
Yes TotalRemaining








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 Element
AccountID 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 willing to pay for routed sample.
ClientSurveyURLLive 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

Page | 19

B. Data Mapping


URL Parameter Description ID Value (part of call) ID Text (not part of call)
SurveyStatus 06 Canceled - Non Charged
02 Pending
03 Live
04 Complete
01Awarded
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. 1Chinese 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
21Spanish - 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 Republic
40 Greek - Greece

Page | 20


URL Parameter Description ID Value (part of call) ID Text (not part of call)
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
61English - Malaysia
62 Hungarian - Hungary
63 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 - Egypt
78 Slovak - Slovakia
79 Slovene - Slovenia
80 Spanish - Peru
81Vietnamese - Vietnam
82 Arabic - United Arab Emirates
83 Arabic - Qatar

Page | 21




URL Parameter Description ID Value (part of call) ID Text (not part of call)
IndustryID Industry associated with the survey. 1Automotive
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
11Gambling/Lottery
12 Healthcare/Pharmaceuticals
13 Home (Utilities,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)
21Restaurants
22 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
URL Parameter Description ID Value (part of call) ID Text (not part of call)
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
11Recruit - Panel
12 Recruit - Recontact
13 Tracking - Monthly
14 Tracking - Quarterly
15 Tracking - Weekly
16 Wave Study
17 Web to Phone
18 Internal Use
19 Top Off
20 End of Router