Receive opportunity notifications

POST

/receive-notifications

const url = 'https://registry.rex.dynata.com/receive-notifications';
const options = {
  method: 'POST',
  headers: {
    'dynata-expiration': '2026-04-15T12:00:00Z',
    'dynata-access-key': 'ADSF23ADF354GFDDS23',
    'dynata-signature': 'dsklj435kljhfdSAFdsalk34',
    'Content-Type': 'application/json'
  },
  body: '{"limit":25,"shards":{"count":3,"current":3},"visibility_timeout":300}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://registry.rex.dynata.com/receive-notifications \
  --header 'Content-Type: application/json' \
  --header 'dynata-access-key: ADSF23ADF354GFDDS23' \
  --header 'dynata-expiration: 2026-04-15T12:00:00Z' \
  --header 'dynata-signature: dsklj435kljhfdSAFdsalk34' \
  --data '{ "limit": 25, "shards": { "count": 3, "current": 3 }, "visibility_timeout": 300 }'

To process opportunity notifications we recommend the following.

Call to get notifications in queue (max 50 will be returned, based on provided limit value)
if there are no notifications to process, pause 5 seconds, then try again
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

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

application/json

object

limit

Maximum number of opportunities to return per request

integer format: int64

>= 1 <= 50

Example

shards

Sharding options for concurrent consumption

object

count

required

Total number of shards; should equal number of consumers

integer format: int64

>= 1 <= 5

Example

current

required

Requesting consumer identifier; cannot be greater than number of shards

integer format: int64

>= 1 <= 5

Example

visibility_timeout

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

integer format: int32

<= 600

Example

Responses

200

List of opportunity notifications

application/json

Array

object

required

Unique identifier of opportunity

integer format: int64

status

required

Current opportunity status

string

Allowed values: OPEN PAUSED CLOSED

length_of_interview

required

Estimated length of interview

integer format: int32

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

cost_per_interview

required

Offer price per interview

number format: float

completes

required

Total fielding completes requested

integer format: int64

group_id

required

Identifier of opportunity group

integer format: int64

evaluation

required

Click balancing mode

string

Allowed values: COMPLETES STARTS

days_in_field

required

Expected duration of opportunity in days

integer format: int32

locale

required

Localization of the opportunity

object

language

required

Lowercase two-character ISO language value

string

/^[a-z]{2}$/

country

required

Uppercase two-character ISO country value

string

/^[A-Z]{2}$/

devices

required

Devices supported by opportunity

Array<string>

Allowed values: mobile desktop tablet

links

required

Entry links of opportunity

object

live

required

Live entry link

string format: uri

created

required

Creation date of opportunity

string format: date-time

project_exclusions

required

Projects that prevent respondent participation in this project

Array<integer>

category_exclusions

Categories that prevent respondent participation in this project

Array<integer>

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

order_number

required

Unique project identifier.

string

/^ORD-\d+-\w+$/

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>

client_id

required

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

integer format: int64

nullable

cells

required

Individual target definitions

Learn more here

Array

One of:

Value

Learn more here

object

tag

required

Cell reference tag

string

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

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

Range

Learn more here

object

tag

required

Cell reference tag

string

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

negate

required

Negative evaluation of value(s)

boolean

kind

required

string

Allowed values: RANGE

range

Describes the bounds of the cell value range; populated when cell kind is RANGE

object

from

required

Lower bound of cell value range

integer format: int64

nullable

required

Upper bound of cell value range

integer format: int64

nullable

List

Learn more here

object

tag

required

Cell reference tag

string

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

negate

required

Negative evaluation of value(s)

boolean

kind

required

string

Allowed values: LIST

operator

required

Indicates the comparison operation to use.

string

Allowed values: OR AND

list

required

List of cell values; populated when cell kind is LIST

Array<string>

Collection

Learn more here

object

tag

required

Cell reference tag

string

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

negate

required

Negative evaluation of value(s)

boolean

kind

required

string

Allowed values: COLLECTION

operator

required

Indicates the comparison operation to use.

string

Allowed values: OR AND

collection

required

Identifier of a large collection of values available for download; populated when cell kind is COLLECTION

string

filters

Target combinations without a limit or status.

Learn more here

Array<Array<object>>

quotas

Target combinations with a limit and status.

Learn more here

Array<Array>

Example

[
  {
    "id": 12345,
    "status": "OPEN",
    "length_of_interview": 10,
    "incidence_rate": 80,
    "cost_per_interview": 0.55,
    "completes": 100,
    "group_id": 112411272,
    "evaluation": "COMPLETES",
    "days_in_field": 25,
    "locale": {
      "language": "en",
      "country": "US"
    },
    "devices": [
      "desktop",
      "tablet"
    ],
    "links": {
      "live": "https://respondent.qa-rex.dynata.com/start?ctx=7321f626-0de5-4d45-b138-29864ce635b4&language=en"
    },
    "project_exclusions": [
      293847,
      561112
    ],
    "category_exclusions": [
      23,
      10
    ],
    "project_id": 1589419,
    "order_number": "ORD-1234-5ab678",
    "requirements": {
      "requires_recontact": false,
      "requires_pii_collection": false,
      "requires_webcam": false,
      "requires_eye_tracking": false,
      "requires_cookie_drops": false,
      "requires_sample_plus": false,
      "requires_app_vpn": false,
      "requires_manual_rewards": false
    },
    "category_ids": [
      123,
      456,
      789
    ],
    "client_id": 54321,
    "cells": [
      {
        "tag": "163a74b4-68fd-4bae-b264-03e626a20b2f",
        "attribute_id": 80,
        "negate": false,
        "kind": "VALUE"
      }
    ],
    "filters": [
      [
        {
          "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": [
      [
        {
          "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

notification-count

integer format: int64

Example

Number of returned notifications

notification-total

integer format: int64

Example

Number of notifications in the account’s queue

400

Bad request

application/json

object

message

required

A human readable description of the error

string

Example^generated

{
  "message": "example"
}

401

Invalid credentials

application/json

object

message

required

A human readable description of the error

string

Example^generated

{
  "message": "example"
}

403

Unauthorized

application/json

object

message

required

A human readable description of the error

string

Example^generated

{
  "message": "example"
}

500

Internal server error

application/json

object

message

required

A human readable description of the error

string

Example^generated

{
  "message": "example"
}

Receive opportunity notifications

Parameters

Header Parameters

Example

Example

Request Body

Example

Example

Example

Example

Responses

200

Example

Headers

Example

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

500

Examplegenerated

Example^generated

Example^generated

Example^generated

Example^generated