Skip to content
Developer

List respondent engagements

POST
/list-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.

Inbound (entry URL)

After receiving engagements the partner will need to use the start_url (inbound) to send the respondents into a survey.

Please Note

  • The start_urlmust be signed using the Dynata signing algorithm.
  • The engage start_url does not require any additional query string parameters, all necessary fields are stored in the context (ctx).
  • Partners should still append any custom tracking query string parameters required for their implementation.

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters ”
dynata-expiration
required
string format: date-time

RFC3339 timestamp indicating request expiration

dynata-access-key
required
string

Dynata provided access key

Example
ABCD1234
dynata-signature
required
string

Signature created using the dynata methodology

Example
c156e91013eb715edb2b07df5491497a807206b1796bb7d031505107a9dbdcdf

Request Body

Section titled “Request Body ”
object
respondent_id
required

Partner’s respondent identifier. Accepts 100 characters, 3-byte chars.

string
fingerprinting_data
object
width

Device width

integer format: int64
height

Device height

integer format: int64
ip_address

Respondent’s IP address

string
http_headers
object
key
additional properties
Array<string>
device_type

Device form factor

string
Allowed values: DESKTOP TABLET SMARTPHONE
filters
object
max_opportunities
number
default: 1 >= 1 <= 10

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Qualified groups

One of:

Qualification

object
qualified
Array<object>
object
quota_group_id

Opportunity group identifier

integer format: int64
project_id

Opportunity project identifier

integer format: int64
start_url

Inbound, entry URL

string
nullable
context_id

Context ID used in the refinement flow with /internal/refine-engagement

string
nullable
exact_match

If true, the group_id is a full match. If false, additional profiling will be required to collect the missing respondent attributes.

boolean
nullable
actual_length_of_interview

Average length of interview in minutes based on prior completes.

integer format: int32
nullable
priority

Dynata recommends this as a high priority opportunity.

boolean
nullable
bid_length_of_interview
integer format: int32
bid_incidence_rate
number format: float
categories
Array<integer>
cpi
number format: float
Examples
{
  "qualified": {
    "properties": {
      "quota_group_id": 123145,
      "project_id": 12354,
      "start_url": "https://respondent.qa-rex.dynata.com/start?ctx=ctx123",
      "exact_match": false,
      "actual_length_of_interview": 9,
      "priority": false,
      "bid_length_of_interview": 10,
      "bid_incidence_rate": 55,
      "categories": [
        550
      ],
      "cpi": 3.5
    }
  }
}

400

Section titled “400 ”

Bad request

object
message
required
string

401

Section titled “401 ”

Invalid credentials

object
message
required
string

403

Section titled “403 ”

Unauthorized

object
message
required
string

500

Section titled “500 ”

Internal server error

object
message
required
string