API Integration
Introduction
Precisionsample brings efficiency and automation to online sampling with precision Marketplace, the world’s most powerful, open, and customizable online sampling platform. The Demand and Supply APIs provide a simple way to connect to millions of people and get answers in real time. By specifying a set of demographic qualifications and quotas, buyers can target a wide or very specific population on a topic of your choosing. As a supplier, you get fine grain control over your survey matching and business relationships on the platform. We want to encourage innovation with minimal limits. We ask that you please be practical and considerate when determining call frequencies. We rate limit when needed to protect the system and ensure the highest level of service to all of our clients.
Authentication
API requests should contain header “APPKey” with the secret key. Missing header or invalid secret key will lead to rejection of the request and will return 400 Bad request error.
Method Header:-Key will be provided to each partner, use this key while calling Precision Sample API in Header with name AppKey
Running Postman
The entire Precisionsample Marketplace API collection can be easily imported into Postman, by clicking the button below:
Postman is a free application that allows you to execute test calls in an intuitive interface.
Create
The purpose of this method is to insert a user into precision sample.
Method URL (POST)
https://api4.opinionetwork.com/api/Member/Create
Method Input's
| Input parameter | Description | Data Type | Required | Values |
|---|---|---|---|---|
| Rid | White Label Partner Id | integer | Yes | Accepts only integer values. << contact support for the partner ID>> |
| TxId | Transactional Id to be returned on post backs | Varchar(50) | No | Can be any values. Ex: 12343 or YD12e3w |
| ExtMemberId | Member Identifier on the partner site | Varchar (50) | Yes | Can be any values. Ex: 11213213 or AD1214 |
| Country | Country of the member | Varchar(250) | No | Can be any values. Ex: USA or CA. . For other available Country Codes to pass please refer to end of the document Appendix A. |
| State | State of the member | Varchar(50) | No | Can be any values. Ex: Texas or TX |
| First Name | First name of the member | Varchar(250) | No | Can be any values. Ex: Donald or Donald II |
| Last Name | Last name of the member | Varchar(250) | No | Can be any values. Ex: Smith or Smith Jr |
| Email Address | Email Address of the member | Varchar(250) | No | Can be any values, but a valid email address regular expression is applied |
| Zip | Zip code of the member | Varchar(10) | No | Can be any values like 80255 |
| Gender | Gender of the member | Char(1) | No | Accepts either M (for male) or F (for female) |
| DOB | Date of birth of member | varchar(20) ex: 04/14/1975 | No | Values should be in the MM/DD/YYYY format |
| Address1 | Address 1 of member | varchar(500) | No | Any string values up to 500 char length |
| Address2 | Address 2 of member | varchar(500) | No | Any string values up to 500 char length |
| Ethnicity | Ethnicity of the member | Integer | No | Accepted Values: 1 white 2 Black or African American 3 Hispanic 4 American Indian or Alaskan Native 5 Asian Indian 6 Chinese 7 Filipino 8 Japanese 9 Korean 10 Vietnamese 11 pacific islander 12 Middle Eastern 13 Other Asian 14 Other 15 Prefer not to answer |
| City | City of the member | Varchar(50) | No | Can be any values. Ex: Texas or TX |
Method Output(s)
The output is a string returned either with the following string values:
• Success (or)
• Failure
If the member is successfully inserted into the database, a unique identifier for the lead called the “Member GUID” is returned along with the success or failure message. The Member GUID is a 36 Char Hex Code, which cannot be hacked – but for all practical purposes is treated as just like any other string of length 36 characters. Example values:
• 21cc77ea-796a-4027-bd83-859db4147955
Both these values are “,” (comma) separated.
Example returned values: (are not case sensitive)
• “Success, user_guid =21cc77ea-796a-4027-bd83-859db4147955”
• “Failure”
Update
The purpose of this method is to update member PII on precision sample.
Method URL (POST)
https://api4.opinionetwork.com/api/Member/Update
Method Input(s)
| Input parameter | Description | Data Type | Required | Values |
|---|---|---|---|---|
| UserGuid | Unique Id of the member | uniqueidentifier | Yes | Ex : 21cc77ea-796a-4027-bd83-859db4147955 |
| Rid | White Label Partner Id | integer | Yes | Accepts only integer values. << contact support for the partner ID>> |
| ExtMemberId | Member Identifier on the partner site | Varchar (50) | Yes | Can be any values. Ex: 11213213 or AD1214 |
| TxId | Transactional Id to be returned on post backs | Varchar(50) | No | Can be any values. Ex: 12343 or YD12e3w |
| Country | Country of the member | Varchar(250) | No | Can be any values. Ex: USA or CA. . For other available Country Codes to pass please refer to end of the document Appendix A. |
| State | State of the member | Varchar(50) | No | Can be any values. Ex: Texas or TX |
| FirstName | First name of the member | Varchar(250) | No | Can be any values. Ex: John or Peter |
| LastName | Last name of the member | Varchar(250) | No | Can be any values. Ex: John or Peter |
| EmailAddress | Email Address of the member | Varchar(250) | No | Can be any values. Ex: john@yahoo.com |
| Zip | Zip code of the member | Varchar(10) | No | Can be any values like 80255 |
| Gender | Gender of the member | Char(1) | No | Accepts either M (for male) or F (for female) |
| DOB | Date of birth of member | varchar(20) ex: 04/14/1975 | No | Values should be in the MM/DD/YYYY format |
| Address1 | Address 1 of member | varchar(500) | No | String Values upto 500 char length. |
| Address2 | Address 2 of member | varchar(500) | No | String Values upto 500 char length. |
| Ethnicity | Ethnicity of the member | Integer | No | Accepted Values:
1 White 2 Black or African American 3 Hispanic 4 American Indian or Alaskan Native 5 Asian Indian 6 Chinese 7 Filipino 8 Japanese 9 Korean 10 Vietnamese 11 Pacific Islander 12 Middle Eastern 14 Other Asian 15 Other 16 Prefer not to answer |
| City | City of the member | Varchar(50) | No | Can be any values. Ex: California |
Method Output(s)
The output is a string returned either with the following string values:
• Success(or)
• Failure
If the lead is successfully inserted into the database, a unique identifier for the lead called the “LEAD GUID” is returned along with the success or failure message. The LEAD GUID is a 36 Char Hex Code, which cannot be hacked – but for all practical purposes is treated as just like any other string of length 32 characters. Example values:
• 21cc77ea-796a-4027-bd83-859db4147955
Both these values are “,” (comma) separated.
Example returned values: (are not case sensitive)
• “Success, user_guid =21cc77ea-796a-4027-bd83-859db4147955”
• “Failure”
Get Profile
The purpose of this post method is to list all the member profiles and their respective completion status.
Method URL (POST)
https://api4.opinionetwork.com/api/Member/GetProfile?UserGuid=%% user_guid%%
Method Input(s)
| Input Parameter | Description | Data Type | Required | Values |
|---|---|---|---|---|
| UserGuid | Lead’s Unique Identifier | uniqueidentifier | Yes | Accepts a GUID, sample value: 21cc77ea-796a-4027-bd83-859db4147955 |
Method Output(s)
The result for this Rest API Contains:
Sample Values:
Update Profile
The purpose of this method is to accept profile attributes in the JSON.
Method URL (POST)
https://api4.precisionsample.com/api/Member/UpdateProfile2
Key: Content-Type Value: application/json
Method Input(s)
| Input Parameter | Description | Data Type | Required | Values |
|---|---|---|---|---|
| Json(profile) | Json data | Json object/array | Yes |
Accepts JSON from body(raw): |
Method Output(s)
The result for this Rest API Contains:
Success Message:
Get Surveys History
The purpose of this method to provide list of surveys participated by the user and his status.
Method URL (POST)
https://api4.opinionetwork.com/api/Member/GetSurveysHistory?UserGuid=%% user_guid%%
Method Input(s)
| Input Parameter | Description | Data Type | Required | Values |
|---|---|---|---|---|
| UserGuid | Lead’s Unique Identifier | uniqueidentifier | Yes | Accepts a GUID, sample value: 21cc77ea-796a-4027-bd83-859db4147955 |
Method Output
The result for this Rest API Contains:
Unsubscribe
The purpose of this method is to unsubscribe the user from recieving email invitations.
Method URL (POST)
https://api4.opinionetwork.com/api/Member/Unsubscribe?Rid=%%_Rid_%%&UserName=%%user_guid%%
Method Input(s)
| Input Parameter | Description | Data Type | Required | Values |
|---|---|---|---|---|
| UserName (Email Address) | Email address of the member or Uniqueidentifier of the member | Varchar(250) | Yes | Can be any values, sample value: ram@gmail.com Or 21cc77ea-796a-4027-bd83-859db4147955 |
| Rid | White Label Partner Id | integer | Yes | Accepts only integer values. << contact support for the partner ID>> |
Method Output
The output is a string returned either with the following string values:
• Success (or)
• Failure
Resubscribe
The purpose of this method is to enable the user to recieve email invitations.
Method URL (POST)
https://api4.opinionetwork.com/api/Member/Resubscribe?UserGuid=%%user_guid%%
Method Input(s)
| Input Parameter | Description | Data Type | Required | Values |
|---|---|---|---|---|
| UserGuid | Lead’s Unique Identifier | uniqueidentifier | Yes | Accepts a GUID, sample value: 21cc77ea-796a-4027-bd83-859db4147955 |
Method Output
The output is a string returned either with the following string values:
• Success (or)
• Failure
Get Questions
The purpose of this method is to provide the meta data for that particular QuestionId.
Method URL (POST)
https://api4.opinionetwork.com/api/Member/GetQuestions?questionId=142
Method Input(s)
| Input Parameter | Description | Data Type | Required | Values |
|---|---|---|---|---|
| questionId | Id of a particular question | int | Yes | Accepts a id, sample value: 142 |
Method Output
The result for this Rest API after successfully invoking the method contains:
Delete
The purpose of this method is delete the user from the system.
Method URL (POST)
Method Input(s)
| Input Parameter | Description | Data Type | Required | Values |
|---|---|---|---|---|
| Rid | White Label Partner Id | integer | Yes | Accepts only integer values. << contact support for the partner ID>> |
| UserGuid | Lead’s Unique Identifier | uniqueidentifier | Yes | Accepts a GUID, sample value: 21cc77ea-796a-4027-bd83-859db4147955 |
| ExtMemberId | Member Identifier on the partner site | Varchar(20) | Yes | Can be any values. Ex: 11213213 or AD1214 |
Method Output
The result for this web service after successfully invoking the method contains:
Successfully Deleted.
Get Profiles By Country
The purpose of this method is to list all the question and options available for that country. Output of questions and options are translated according to country(country_id).
Method URL
https://api4.precisionsample.com/api/Member/GetProfilesByCountry
Key: Content-Type, Value: application/json
Method Input(s)
| Input Parameter | Description | Data Type | Required | Values |
|---|---|---|---|---|
| Json(Country_id) | Unique country_id | Jsonstring/jsonarray | Yes |
Accepts json from body(raw): { "country_id" : "231" } |
Method Output
The result for this Rest API Contains:
Memebers API
GetSurveys
The purpose of this method is to provides all the surveys for which the member was qualified to participate.
Method URL (POST)
https://api4.opinionetwork.com/api/Member/GetSurveys?UserGuid=%%user_guid%%
Method Input(s)
| Input parameter | Description | Data Type | Required | Values |
|---|---|---|---|---|
| UserGuid | Lead’s Unique Identifier | uniqueidentifier | Yes | Accepts a GUID, sample value: 21cc77ea-796a-4027-bd83- 859db4147955 |
Method Output
The result for this web service after successfully invoking the
method is an xml string which contains:
Project API
API requests should contain header “X-PSAPPKey” with the secret key. Missing header or invalid secret key will lead to rejection of the request and will return 400 Bad request error.
API URL
The white label partner API can be accessed at http://api6.precisionsample.com/
The purpose of this method is to get all the available projects with the Pre-screener Questions
Method URL (GET)
http://api6.precisionsample.com/api/projectsjson
Request Parameters
| Input Parameter | Description | Data Type | Required | Values |
|---|---|---|---|---|
| c | Country code for which country you need surveys | Varchar(2) | No | Ex : us or uk or ca or au. For other available Country Codes to pass please refer to end of the document. |
Response XML Nodes
| Name | XML Node | Type | Description |
|---|---|---|---|
| Project Id | prj_id | Integer | Unique Integer Id associated with the Project Ex: 52231 |
| Project Guid | prj_guid | Unique Identifier | Unique hash value (GUID) associated with the survey Ex: 4d45c954-13a2-4c6e-9f68-7ed60e27e8e0 |
| End date | end_date | Date Time | Estimated fielding end date Ex: 04/01/2016 |
| Survey Category ID | sc_id | Integer | Survey Category types Ex: Health, Food,Bank |
| Buyer ID | buyer_id | Integer | ID of the buyer Ex : 81 100,124 |
| Response Rate | rr | Percentage | Calculated based on Invites divided by Completes |
| Incidence Rate | ir | Float | Required Incidence Rate for the project |
| Live Incidence Rate | live_ir | Float | Current Incidence rate calculated based on completes divide by sum of completes & Terms |
| Total Completes | Total_completes | Integer | Total completes required for the Survey |
| Current Completes | cc | Integer | Completes reached for the survey |
| Complete percentage | cp | Float | Percentage of the total number of completes achieved |
| Device | device | nvarchar(25) | Device which should be used for the survey Ex : Mobile only or Non-Mobile Only or Both |
| Allow Multiple Entries | ismultiple | Boolean | “true” or “false” – Indicates if Multiple Entries is enabled for the study |
| LengthOfInterview | LOI | Integer | Estimated time it takes for a respondent to complete the client-side survey (in minutes) |
| Partner Payout | P_payout | Float | Partner Payout per complete Ex: $2.50 |
| Success Reward | reward | Float | Payout per complete (Please note that the price paid per complete to suppliers is *gross* and does not include any applicable commissions or fees) EX: $1.25 |
| Survey URL | url | Varchar(500) | Url to which the criteria matched members should be sent into the survey. Ex: |
| Exclusion Project ID | exclusion_project_id | Varchar(250) | IDs of the projects traffic that are not allowed into this survey. Ex: [174532,176732,174758,176459] |
| Quota Name | q_name | nvarchar(250) | Name of the Quota Ex: Gen Pop, 1% |
| Quota ID | q_id | integer | ID of the Quota Ex:480476 |
| Quota Guid | q_guid | uniqueidentifier | Guid of the quota Ex: 1FC3389C-30EA-4F5D-887A-D658D20F369C |
| Quota Completes | cc | Integer | Completes reached for the Quota |
| Quota Total Completes | tc | Integer | Total completes required for the Quota |
| Quota Terminates | terms | Integer | No.of Terminates for the Quota |
| Quota OverQuotas | oqs | Integer | No.of Over quotas |
| Quota Active | isactive | Boolean | "yes" or "no" - Indicates if quota is active or not |
| Country | country | Varchar(150) | Country ids for which the survey is eligible Ex: 231;38;15. For more country ids please see at the end of the document. |
| State | States | Varchar(max) | State ids for which the survey is eligible Ex : 1;2;3;4 |
| Zip Code | zips | Varchar(max) | Zip codes targeting the members. Ex: 80221;80216;80243 |
| Regions | regions | Varchar(max) | Regions targeting the members. Ex: East North Central; Ontario; |
| Dma | dmas | Varchar(max) | Dma ids targeting the members. Ex: 662;664;552;634 |
| Msa | msas | Varchar(max) | Msa ids targeting the members. Ex: 2340;2360 |
| Cma | cmas | Varchar(max) | CMA ids targeting the members. Ex: 215;216 |
| County | county | Varchar(max) | County ids targeting the members Ex: 674;683 |
| Gender | gender | Varchar(10) | Gender of the targeting criteria Ex: M or F or m or f or A(all) |
| Ethnicity | ethnicity | Varchar(30) | Ethnicity ids for targeting the criteria Ex:1;2;3;4;5 |
| Minimum age | Min_age | Int | Minimum age to allow the member to the survey Ex:18 |
| Maximum age | Max_age | Int | Maximum age for the member should to enter the survey Ex : 99 |
| Question Id | qst_id | int | Survey qualification identifier defined by the API standard Ex: 141 |
| Option Id | Opt_ids | Integer | Qualification answer option ids defined by the API Standard Ex: 3069;3070 |
Country list
| Country ID | Country Code | Country Name |
|---|---|---|
| 15 | AU | AUSTRALIA |
| 38 | CA | CANADA |
| 299 | UK | UNITED KINGDOM |
| 231 | US | UNITED STATES OF AMERICA |
| 634 | MIX | MEXICO |
| 543 | CR | COSTA RICA |
| 662 | PA | PANAMA |
| 502 | AR | ARGENTINA |
| 538 | CO | COLOMBIA |
| 730 | VE | VENEZUELA, BOLIVARIAN REPUBLIC OF |
| 665 | PE | PERU |
| 534 | CL | CHILE |
| 522 | BR | BRAZIL |
| 596 | IE | IRELAND |
| 700 | ES | SPAIN |
| 669 | PT | PORTUGAL |
| 572 | DE | GERMANY |
| 505 | AT | AUSTRIA |
| 707 | CH | SWITZERLAND |
| 565 | FR | FRANCE |
| 647 | NL | NETHERLANDS |
| 512 | BE | BELGIUM |
| 599 | IT | ITALY |
| 601 | JP | JAPAN |
| 608 | KR | South Korea (Korea, Republic of) |
| 535 | CN | CHINA |
| 709 | TW | TAIWAN |
| 592 | IN | INDIA |
| 650 | NZ | NEW ZEALAND |
| 731 | VN | VIETNAM |
| 712 | TH | THAILAND |
| 593 | ID | INDONESIA |
Redirects
At the end of the survey, we redirect the survey calls back to API
Partner pages after a Member Completes/Terminates the Survey.
Please see the below table for redirect params that are available for you.
| Parameter | Values | Sample Value | Type | Required | Description |
|---|---|---|---|---|---|
| ug | %%user_guid%% | 645D2A50-1D53-40B7-9DD5-8238AFAF8029 | varchar(36) | Optional | UserGUID you get after creating member |
| sub_id3 | %%sub_id3%% | 645D2A50-1D53-40B7-9DD5-8238AFAF8029 or fvgjhdbcdckhvjbr78475rehfb | varchar(36) | Optional | External Member ID |
| sub_id | %%sub_id%% | VAQ1234 or 123456 | varchar(36) | Optional | Click ID or Transaction ID |
| user_invitation_guid | %%user_invitation_guid%% | 6454FA50-1D53-40B7-9DD5-8238AFAF8089 | varchar(36) | Optional | User Unique survey participation ID |
| surveyid | %%project_id%% | 314581 | int | Yes | Id of the Survey, member completed |
| title | %%survey_name%% | Health Survey | varchar(250) | Yes | Name of the Survey, member completed |
| Status | %%status%% | S or T or Q | varchar(5) | Yes |
|
| survey_complete_date | %%survey_complete_date%% | 11/21/2022 | varchar(50) | Optional | Survey Completed Date |
| es_id | %%entry_project_id%% | 314567 | int | Optional | Entry Id of the Survey, member participated |
| gross | %%gross%% | 2.4 | numeric or decimal | Yes | Partner Gross revenue Share amount in $ |
| reward | %%reward%% | 1.2 | numeric or decimal | Yes | Reward amount for the member in $ or if any conversion exists it will be in the respective conversion(Coins, Points) |
| code | %%code%% | 1,2,3,4 | varchar(10) | Optional | Survey Status Name |
Post Backs
In general we do fire pixels or call backs, when an API Partner Member Completes the Survey Preliminarily, so Partners need to build the Call back URL to get the Survey Status for a Member. Please see the below table for Post back params that are available for you.
| parameter | Sample Values | Type | Required | Description |
|---|---|---|---|---|
| sub_id | VAQ1234 or 123456 | varchar(20) | Optional | External Id |
| reward | 1.2 | numeric or decimal | Yes | Reward amount for the member in $ |
| status | S or T or Q | Varchar (5) | Yes |
|
| title | Health Survey | Varchar(250) | Yes | Name of the Surrvey,member completed |
| surveyid | 9345 | int | yes | id of the survey,member completed |
| es_id | 1234 | int | Optional | Entry id of the Survey,member participated |
| gross | 2.4 | numeric or decimal | yes | partner Gross revenue amount in $ |