Integration Documentation

Follow this integration guide to optimize your setup with the Project API. If you’ve never work with a Dynata API product before, the steps below walk you through the best way to effectively use the API. You may also skip this guide and go directly to the API endpoints. Please reach out to our team if you have any questions: partners@dynata.com.

Step 1: Obtain your credentials

Login to the Portal and create or choose an existing an Application. The benefit of using an existing App Id is that all of your users’ profile information is already saved.

Once you’ve decided which App ID you’ll use for the integration, go to “Apps” in the navigation bar, select the App Id, and go to “Credentials”. App ID will be your client_id, and client_secret will be your transaction key.

Step 2: Create mapping of profile attributes.

Reach out to our team and request the library of all targeting attribute IDs and values. Each attributeID has a list of possible values. You’ll need this mapping for two purposes:

  1. To interpret project details and understand the targeting attributes for each survey.
  2. To build rich user profiles when registering your members.

Mapping your internal profile attributes to our attributes will yield the best results. Please reach out to a Dynata team member and we can provide assistance.

Step 3: Register Respondents

Each of your members needs to be registered before they can be sent into a survey through the Register Respondent endpoint. The user ID passed in the Register Respondent request will be the uid value used in the survey entry URL.

The following profile attributes are required: Sex, DOB, Country Code, and Zip Code.

Please include additional profile attributes in the profileData field using the mapping from Step 1. Adding more attributeIDs for each user and building rich profiles allows clients to better determine the feasibility of your supply.

View the profile of any user you’ve registered through the Get Respondent Endpoint.

To update respondents who are already registered, call the Register Respondent endpoint with the new profile. Each call will overwrite the previous data, so make sure to include the complete profile with each request.

Step 4: Get a list of All Projects

Once you understand attribute mapping and registering respondents, you can begin requesting the ‘Get All Projects’ endpoint to see what opportunities are best suited for your users.

Each project returned contains basic details, including its State, Line Items with targeting attributes and values, and a list of exclusions. Projects in the Launched state will be available for incoming traffic, where projects in the Provisioned State will be accessible soon. Projects that are Closed and Cancelled will still be available for analysis, but no further traffic will be accepted.

The most important information for yield management will be located at the Line Item Level. A line item is a project entity that exists for a specific market and language that the survey is targeting for. Each Line Item defines the target market and the number of completes required.

Step 5: Interpreting Line Items

Each line items contains lower level details about the survey and a list of different targeting attribute groups.

One of the most important details is the SurveyURL, otherwise known as the Survey Entry Link. In step 5 we’ll show you how to configure this URL for each of your users.

In order to configure this URL, you need LineItemID and Quota Cell ID, and you need to know how Line Items are structured. Starting at the highest level going down, the order is Quota Plans --> Quota Cells --> Quota Nodes --> Quota cellIDs. Below is a description of each:

  1. Quota Plans

A Quota Plan describes all the Quota Groups, Quota Cells, and Quota Nodes that a user must qualify for in order to enter a survey.

  1. Quota Groups

A user must qualify for each Quota Group in order to enter a survey.

  1. Quota Cells

Within each Quota Group, there are Quota Cells. A User must qualify for one Quota Cell within each Quota Group to qualify for a survey.

  1. Quota Nodes

Each Quota Cell has Quota nodes. A user must qualify for ALL Quota nodes within a Quota Cell to Qualify for the Quota Cell.

  1. Quota Cell IDs

Quota Cell ID is the label for each Quota Cell. In the entry URL, you will use quota cell IDs and populate the query parameter like this: qcids=1,4,5

Please ask our team for a visual to help you better understand the Quota Plan and the relationship between Quota Groups, Quota Cells, and Quota Nodes.

Step 6: Configure your Survey Entry URL

Below is an example of a marketplace SurveyEntry endpoint. The variables in between the ## should be replaced with appropriate values before entering a survey.

*marketplace/surveyEntry.php?hash=#hash#&tid=#tid#&uid=#uid#&appid=#appid#&ltid=#ltid#&qcids=#qcids#*
  1. hash => {hash-value}

    The {hash-value} will be a HMAC (Sha256) produced from a message and secret key. The message is {uid} + {lineItemID} + {appid}. The secret key is {TransactionKey}

  2. tid = Publisher’s tracking id (sub_id).

    The tid is a value that’s passed in the entry URL and returned in the Redirect URL. For example, if your Redirect URL contains sub_id=#sub_id#, and if you set tid=232 in the entry URL, then the Redirect URL will show sub_id=232. This value is required.

  3. uid = respondent ID

    The respondent ID is found in the Create Respondent API response; this is your user’s id.

  4. appid = application ID in supplier portal.

  5. ltid = Line Item ID.

  6. qcids = Quota Cell IDs.

    Provide the Quota Cell IDs for the Line Items a respondent qualifies for.

After all the parameters are inserted correctly into the Survey Entry URL, you’re ready to send the user into the link. However, you need to configure your redirect links so users can return to the right endpoint after existing the survey. Follow the instructions in Step 6.

Optional Parameters

If you want to map your user clicks to their transactions, we recommend passing the sub_id paramter in the entry URL. You may pass in the parameter sub_id= in the entry URL and append any value to it, for example, sub_id=455. When you include sub_id=#sub_id# in the redirect or callback URL, the value appended in the entry URL will be shown in place of #sub_id#.

You may also add &match=true in your entry URL. When you do this, we’ll validate the user before sending them into a survey.

Why is this helpful? Sometimes you may send in the wrong user to a survey. For example, the survey asks for Iowa residents but you send in California residents. If you have &match=true, we’ll compare the user’s profile to the survey’s targeting attributes. If the user is a match, they’ll be redirected to the survey. If they’re not a match, they’ll be redirected to your custom landing pages.

Step 7: Setting up redirects URLs.

Redirect URLs can be configured in your Publisher Portal. Please reach out to partners@dynata.com for assistance.

Step 8: Reporting

After you’re all setup and sending respondents into surveys and returning them to your application, use the Get Project Report and Get Line Item Report to monitor and optimize the surveys your users are participating in.

The Get Project Report provides observed data from actual panelists at the Project and Line Item levels.

The Get Line Item Report provides observed data from actual panelists at the Line Item, Quota Group, and Quota Cell levels.

You may also login to the Portal located at to access transaction level reporting, callbacks, and chargeback information.