Skip to content
Developer

Get Started

Getting Started

Partner will need to sign and validate all requests according to Dynata’s signing algorithm.

Attribute Mapping

First partners should use the list-attributes and get-attribute-info to map Dynata attributes into their system. The attribute mapping information can then be used to profile respondents.

Create Respondents

Partners must create a respondent using the put-respondent endpoint before calling list-engagements. It’s recommended at a minimum to include the birth_date, gender, andpostal_code upon creation to ensure engagements. In addition partners should profile respondents with any known attributes from their attribute mapping information.

Get Engagements

After a respondent has been created, use the [list_engagments] endpoint to request engagements. It’s recommended partners pass thedevice_type and ip_address fingerprinting_data properties for deduplication purposes.  

Note

Fingerprinting is not 100% foolproof, but in providing both device_typeand ip_address, Dynata can catch as many dupes as possible before returning engagements.

The list-engagements endpoint will return up to 10 engagements (quota_group_ids) for an individual respondent. If no engagements are available for a respondent, it will return a disposition and status.

List Engagements Flow

The following steps are recommended to get engagements for a respondent:

  1. First, call the list-engagements endpoints right before displaying the engagements to the respondent.
  2. Only get the total amount (up to 10) that will be displayed to the respondent.
  3. After a respondent clicks on an engagement, discard the list.
  4. Then repeat the flow when the respondent is ready to view a new list of engagements.

Inbound

After receiving engagements partners will need to use the start_url (inbound) to send the respondents into a survey. The start_url is respondent specific. A tracking ID can be added if desired, but only start_url is required, along with any additional attributes.

For a partial match where some respondent attributes may be missing or expired the respondent will go through Dynata’s refinement. Dynata will prescreen for certain attributes when an engagement requires it for targeting. Refinement will only ask the questions required for the survey.

Outbound

When the respondent session has concluded, the respondent will be redirected to the partner’s redirect URL. All redirect URLs will contain query string parameters for disposition and status. The disposition parameter contains an integer value indicating the disposition of the respondent session. The status parameter contains an integer value indicating more detail about the disposition. The possible values for each disposition and their associated status values are documented here.

All redirect URLs, upon return to the partner, are signed using the Dynata signing algorithm. Partners are responsible for validating the signature in the redirect URL to ensure that it has not been tampered with.