Skip to content
Developer

List respondent engagements

POST
/list-engagements
curl --request POST \
  --url https://respondent.rex.dynata.com/list-engagements \
  --header 'Content-Type: application/json' \
  --header 'dynata-access-key: ABCD1234' \
  --header 'dynata-expiration: 2026-04-15T12:00:00Z' \
  --header 'dynata-signature: c156e91013eb715edb2b07df5491497a807206b1796bb7d031505107a9dbdcdf' \
  --data '{ "respondent_id": "user1234", "fingerprinting_data": { "width": 600, "height": 800, "ip_address": "1.1.1.1", "http_headers": { "additionalProperty": [ "example" ] }, "device_type": "DESKTOP" }, "filters": { "max_opportunities": 1 } }'

Please Note

Only ipv4 format is accepted for ip addresses.

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”
Media typeapplication/json
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 ipv4 address (currently ipv6 isn’t supported)

string format: ipv4
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

Media typeapplication/json
One of:
Qualifications

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 qualification flow with /internal/continue-qualification

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": [
    {
      "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

Media typeapplication/json
object
message
required
string
Examplegenerated
{
  "message": "example"
}

401

Section titled “401”

Invalid credentials

Media typeapplication/json
object
message
required
string
Examplegenerated
{
  "message": "example"
}

403

Section titled “403”

Unauthorized

Media typeapplication/json
object
message
required
string
Examplegenerated
{
  "message": "example"
}

429

Section titled “429”

Too many requests

Media typeapplication/json
object
message
required
string
Examplegenerated
{
  "message": "example"
}

Headers

Section titled “Headers”
retry-after
string
Example
300

The number of seconds a client must wait before making a new request.

500

Section titled “500”

Internal server error

Media typeapplication/json
object
message
required
string
Examplegenerated
{
  "message": "example"
}