Skip to content
Developer

Receive opportunity notifications

POST
/receive-notifications

To process opportunity notifications we recommend the following.

  1. Call to get notifications in queue (max 50 will be returned, based on provided limit value)
  2. if there are no notifications to process, pause 5 seconds, then try again
  3. if notifications are present, process and acknowledge each one using /ack-notifications, then loop immediately back to step 1 to receive more notifications.

This will ensure that the queue is processed as quickly as possible without overwhelming either system with a constant loop of nothing to process.

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
ADSF23ADF354GFDDS23
dynata-signature
required
string

Signature created using the Dynata methodology

Example
dsklj435kljhfdSAFdsalk34

Request Body

Section titled “Request Body ”
object
limit

Maximum number of opportunities to return per request

integer format: int64
>= 1 <= 50
Example
25
shards

Sharding options for concurrent consumption

object
count
required

Total number of shards; should equal number of consumers

integer format: int64
>= 1 <= 5
Example
3
current
required

Requesting consumer identifier; cannot be greater than number of shards

integer format: int64
>= 1 <= 5
Example
3
visibility_timeout

The period of time, in seconds, during which other consumers will be unable to receive a notification

integer format: int32
<= 600
Example
300

Responses

Section titled “ Responses ”

200

Section titled “200 ”

List of opportunity notifications

Array
object
id
required

Unique identifier of opportunity

integer format: int64
Example
12345
status
required

Current opportunity status

string
Allowed values: OPEN PAUSED CLOSED
Example
OPEN
length_of_interview
required

Estimated length of interview

integer format: int32
Example
10
incidence_rate
required

Estimated incidence rate (IR) for a quota group. The IR is the percentage of respondents in the general population expected to qualify for the quota group.

integer format: int32
Example
80
cost_per_interview
required

Offer price per interview

number format: float
Example
0.55
completes
required

Total fielding completes requested

integer format: int64
Example
100
group_id
required

Identifier of opportunity group

integer format: int64
Example
112411272
evaluation
required

Click balancing mode

string
Allowed values: COMPLETES STARTS
Example
COMPLETES
days_in_field
required

Expected duration of opportunity in days

integer format: int32
Example
25
locale
required

Localization of the opportunity

object
language
required

Lowercase two-character ISO language value

string
/^[a-z]{2}$/
Example
en
country
required

Uppercase two-character ISO country value

string
/^[A-Z]{2}$/
Example
US
devices
required

Devices supported by opportunity

Array<string>
Allowed values: mobile desktop tablet
Example
[
  "desktop",
  "tablet"
]
links
required

Entry links of opportunity

object
live
required

Live entry link

string format: uri
Example
https://respondent.qa-rex.dynata.com/start?ctx=7321f626-0de5-4d45-b138-29864ce635b4&language=en
created
required

Creation date of opportunity

string format: date-time
project_exclusions
required

Projects that prevent respondent participation in this project

Array<integer>
Example
[
  293847,
  561112
]
category_exclusions

Categories that prevent respondent participation in this project

Array<integer>
Example
[
  23,
  10
]
notified
required

RFC3339 timestamp of notification

string format: date-time
project_id
required

Identifier of opportunity project — opportunities in the same project have mutual participation exclusions

integer format: int64
Example
1589419
order_number
required

Unique project identifier.

string
/^ORD-\d+-\w+$/
Example
ORD-1234-5ab678
requirements
required

Learn more here

object
requires_recontact
required

Requires inviting (recontacting) specific respondents to a follow up survey.

boolean
requires_pii_collection
required

Requires respondents to provide personally identifiable information (PII) within client survey.

boolean
requires_webcam
required

Requires respondents to utilize their webcam to participate.

boolean
requires_eye_tracking
required

Requires use of facial recognition technology with respondents, such as eye tracking.

boolean
requires_cookie_drops
required

Requires partner to allow Dynata to drop a cookie on respondent.

boolean
requires_sample_plus
required

Requires partner-uploaded respondent PII to expand third-party matched data.

boolean
requires_app_vpn
required

Requires respondents to download a software application.

boolean
requires_manual_rewards
required

Requires additional incentives to be manually awarded to respondent by partner outside of the typical online survey flow.

boolean
category_ids

Categories related to opportunity

Array<integer>
Example
[
  123,
  456,
  789
]
client_id
required

Identifier of client requesting the study. (requires permission to view)

integer format: int64
nullable
Example
54321
cells

Individual target definitions

Learn more here

Array
One of:
Value

Learn more here

object
tag
required

Cell reference tag

string
Example
163a74b4-68fd-4bae-b264-03e626a20b2f
attribute_id
required

Identifier of the Dynata attribute. If the value is -1 it means it’s an ineffable cell and it should discarded

integer format: int64
Example
80
negate
required

Negative evaluation of value(s)

boolean
kind
required
string
Allowed values: VALUE
value

Single cell value; populated when cell kind is VALUE

string
filters

Target combinations without a limit or status.

Learn more here

Array<Array<object>>
Example
[
  [
    {
      "id": "1a2f3de4474642f684ec9ba4d72168f8f459efb49f971775a4eaf0c18ac22d83",
      "cells": [
        "aa7169c0-cb34-499a-aadd-31e0013df8fd"
      ]
    },
    {
      "id": "b331500690bfa19e442a32ad8c74923332318792f98441b025c5638028d4339",
      "cells": [
        "a1c44026-6c20-40e4-ab7c-0bf6e7bd7890",
        "90606986-5508-461b-a821-216e9a72f1a0"
      ]
    }
  ],
  [
    {
      "id": "a64df572cbb25b374bb1b7b702b6e96f2e256485f0631cae1dd5fbb011d3aa8c",
      "cells": [
        "75a36c67-0328-4c1b-a4dd-67d34688ff68"
      ]
    }
  ]
]
quotas

Target combinations with a limit and status.

Learn more here

Array<Array>
Example
[
  [
    {
      "id": "1a2f3de4474642f684ec9ba4d72168f8f459efb49f971775a4eaf0c18ac22d83",
      "cells": [
        "aa7169c0-cb34-499a-aadd-31e0013df8fd"
      ],
      "count": 652,
      "status": "OPEN"
    },
    {
      "id": "b331500690bfa19e442a32ad8c74923332318792f98441b025c5638028d4339",
      "cells": [
        "a1c44026-6c20-40e4-ab7c-0bf6e7bd7890",
        "90606986-5508-461b-a821-216e9a72f1a0"
      ],
      "count": 56,
      "status": "CLOSED"
    }
  ],
  [
    {
      "id": "a64df572cbb25b374bb1b7b702b6e96f2e256485f0631cae1dd5fbb011d3aa8c",
      "cells": [
        "75a36c67-0328-4c1b-a4dd-67d34688ff68"
      ],
      "count": 100,
      "status": "OPEN"
    }
  ]
]

Headers

Section titled “Headers ”
notification-count
integer format: int64
Example
50

Number of returned notifications

notification-total
integer format: int64
Example
100

Number of notifications in the account’s queue

400

Section titled “400 ”

Bad request

object
message
required

A human readable description of the error

string

401

Section titled “401 ”

Invalid credentials

object
message
required

A human readable description of the error

string

403

Section titled “403 ”

Unauthorized

object
message
required

A human readable description of the error

string

500

Section titled “500 ”

Internal server error

object
message
required

A human readable description of the error

string