Basics

Get Surveys URL:

https://matchapi.peanutlabs.com/publisher/api/v1/surveys/match

Protocol

HTTP/HTTPS

Method

POST

Content-Type

“application/json; charset=utf-8”

Response type

JSON

Auth

None

The Request Body

user_id

Dynata User ID (string)

pub_id

your App ID (integer)

iv

a cryptographically random initialization vector for the encrypted payload (string)

payload

(string) The payload for the ‘Get Surveys’ endpoint is the same as ‘Register User’, except you no longer need to include the user profile.

The Payload (Encrypted)

(string) The payload field in the request body is a JSON object, serialized to string/bytes, padded to 128 bit blocksize, encrypted with AES CBC mode, and finally base64 encoded. The JSON object has the following structure (description of fields following the example):

{
    "program_id": "points",
    "offers": True,
    "cpi": False,
    "user_ip": "4.35.165.126",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Safari/604.1.38"   
}

program_id

(optional, string) only applicable if your application is configured with multiple virtual currency reward programs. If omitted, the default virtual currency configured for your application will be used (99% of our partners). If you do have multiple virtual currency reward programs set up, pass the ID of the program for the API to use this currency when matching surveys and formatting results. The API will return surveys with the user reward in terms of this program’s virtual currency.

offers

(optional, string) only applicable if you want to return a list of Offers in the response for any given user. Set the field to True to include Offers. Otherwise, set the field to False or omit this key-value pair entirely.

cpi

(optional, string) This is the amount we’ll pay you for each complete. If you want this value returned, set the field to True. Otherwise, set the field to False or omit this key-value pair entirely.

user_ip

(required, string) the IP address of the end-user for whom the API request is being made. A user’s IP address is used for geographic survey targeting, as well as other eligibility and security checks. Since the API call can be made server-to-server (as opposed to originating from the user’s browser) we can’t rely on the IP address of the request. This is the only mandatory field in the payload.

user_agent

(required, string) the user_agent of the end-user’s browser. We use this to help tailor matches for browser, operating system, and device compatibility. Projects with device targeting will not be included in match results if no user_agent is provided.

Successful Response

    "program_id": "points",
    "user_id": "avdempsey-1-91ae9381f1",
    "surveys": [
        {
          "id": "6512bd43d9caa6e02c990b0a82652dca",
					"offer_id": 923638,
          "title": "Survey",
          "reward": "your_incentive_name",
          "reward_amount": 50,
          "screenout_reward": 0,
          "average_loi": 10,
          "incidence_rate": 20,
          "link": "https://nomad/direct_link/?user_id=avdempsey-1-91ae9381f1&iv=zaEYJEPYZdtB1a2G7q%2Bojw%3D%3D&payload=YSClqh8yUCFgwRC%2B437yFSUuJJE%2FRZNtDtq2LZr7Tcu08FiwUD5N1D9HBtfLsBbikahzVuuy4z9kzbuSw%2BMHIeiJKbj4v4TneZia%2FuA879v6i0Q14Tsx1aIh94nHiKAQ9W6Slq8YdJgB3%2BR92wyoIg%3D%3D&sub_id=",
          "topics": [],
          "survey_type": [],
          "respondent_type": []
        }
    ]
}

Content-Type

“application/json; charset=utf-8”

program_id

(string) the program ID for the virtual currency used by the API to format results.

user_id (string) the same user ID passed to the API in the request.

surveys (array of objects) the list of surveys matched for the user.

Surveys have the following parameters:

id

(string) the hashed unique ID for each survey.

offer_id

(string) the unique ID for each survey.

title

(string) a display title for the survey. Currently this will always be the string “Survey”.

reward

(string) the display name for the virtual currency the user will be rewarded with for participating in the survey. Suitable for showing the user.

reward_amount

(JSON number: float or int) the user incentive for completing the survey in terms of reward currency. To display the reward amount to the user, you could format both the reward and reward_amount fields into a string.

screenout_reward

(JSON number: float or int) if your program_id has a screenout reward configured, this will display the reward amount that should be issued to the user if they screen out.

average_loi

(integer) the average time it takes a user to successfully complete the survey in

minutes

The research client’s quoted LOI (if available) will be used until there are enough completed interviews in our system to generate a better average. If neither the client’s quoted LOI or enough completed interviews are available, a default of 10 is provided.

incidence_rate

(integer) a proxy for the conversion rate of the survey. The value is an integer, but should be treated as a percentage. For example, a value of 20 indicates a 20% estimated conversion. The research client’s quoted IR will be used until there are enough completed interviews in our system to generate a better conversion rate. If neither is available, a default of 20 is provided.

link

(string) the URL to send your user to to take this survey. “&sub_id=” is appended to the end of the URL, you can supply a tracking ID for this user’s participation in this survey under the sub_id parameter. You should provide a unique tracking ID for each survey+user combination.

topics

(array) currently this field will always be an empty array. In the future it will include survey topic information.

survey_type

(array) currently this field will always be an empty array. In the future it will include survey type information.

respondent_type

(array) currently this field will always be an empty array. In the future it will include respondent type information.

Example Successful API Response Surveys and Offers

{
    "program_id": "points",
    "user_id": "avdempsey-1-91ae9381f1",
    "surveys": [
        {
          "id": "6512bd43d9caa6e02c990b0a82652dca",
          "title": "Survey",
          "reward": "your_incentive_name",
          "reward_amount": 50,
          "screenout_reward": 0,
          "average_loi": 10,
          "incidence_rate": 20,
          "link": "http://nomad/direct_link/?user_id=avdempsey-1-91ae9381f1&iv=zaEYJEPYZdtB1a2G7q%2Bojw%3D%3D&payload=YSClqh8yUCFgwRC%2B437yFSUuJJE%2FRZNtDtq2LZr7Tcu08FiwUD5N1D9HBtfLsBbikahzVuuy4z9kzbuSw%2BMHIeiJKbj4v4TneZia%2FuA879v6i0Q14Tsx1aIh94nHiKAQ9W6Slq8YdJgB3%2BR92wyoIg%3D%3D&sub_id=",
          "topics": [],
          "survey_type": [],
          "respondent_type": []
        }
    ]
    "offers":[
        {
          "id":"c4ca4238a0b923820dcc509a6f75849b",
          "external_project_id":"Offer1557882931",
          "offer_filter_tag":[],
          "headline_text":"Offer Title 1557882931",
          "requirement_text":"",
          "free":false,
          "credit_card_required":false,
          "creative":[],
          "reward":"filices",
          "reward_amount":375,
          "screenout_reward":0,
          "cpi":"3.75",
          "link":"http://nomadtest/direct_link/?user_id=saad-1-6b3a3994dc&iv=A6yQXI%2FJP35Y1lF%2BmCHmDw%3D%3D&payload=Z6qA44VpCHifqciiq7RoC7QZOducBxUG6gJIpvhWSILIGnxLiqiSzT6EEb4zkHLmmj9idlShwP5C2zHKg6Tn0ayGR5dOdDjVWaVtDisucoLLBpVvKL186kVnMleagskHhRY6FVb1Hk4avTOJFrtTLg%3D%3D&sub_id="
        }
    ] 
}

offers

(array of objects) the list of offers matched for the user. Only included if the following is included in payload: “offers”: 1

Offers have the following parameters:

id

(string) the internal ID for each offer.

external_project_id

(string) the external ID for each offer.

offer_filter_tag

(array) the list of categories associated with the offer.

headline_text

(string) The title of the offer

requirements_text

(string) What the user must submit in order to complete the offer.

Free

(boolean) Indicates whether the user needs to pay money to complete the offer.

credit_card_required

(boolean) Indicates whether the user needs a credit card to complete the offer.

creative

(array) A list of creatives that can be used in your UI to market the offer.

reward

(string) The virtual currency for the reward payout.

reward_amount

(integer) The amount to be paid out for completing the offer using your virtual currency.

screenout_reward

(integer) The amount to be paid out for being dismissed from an offer.

cpi

(string) The cost-per-incidence (CPI) for the offer.

link

(string) The URL to send the user to take the offer. “&sub_id=” is appended to the end of the URL, you can supply a tracking ID for this user’s participation in this survey under the sub_id parameter. You should provide a unique tracking ID for each survey+user combination.

Error Response Codes

  1. JSON or Transport error

  2. Publisher ID Invalid

  3. User is Banned

  4. User ID Invalid

  5. Required Parameters Missing

  6. Program Invalid

  7. User IP Did Not Match Specified Country

  8. Failed Registration on #dob#

  9. User Profile required (happens when it’s a new user)

  10. Invalid iv or Payload

  11. No Surveys found for user

  12. Error Calling Matching Service (internal error)

Appendix

Packing your Security key

Python

security_key = bytes('12345678')
packed_key = binascii.unhexlify(security_key)