Opportunity Targeting

Opportunities have three key concepts for targeting: cells, filters, and quotas.

Cells

Cells are the most basic unit in targeting; they define the target attribute and qualifying attribute values. Each cell has a kind that determines its value structure. There are currently six cell kinds:

Every cell kind has a tag, attribute_id, and negate property.

tag is a value that is used to identify the cell and is referenced by filters and quotas as explained later in the documentation.
attribute_id is a value that identifies the attribute associated with the cell.
negate is a boolean value that indicates how the cell should be evaluated. When true the negate value indicates that an inverse evaluation should be performed. For instance, the default evaluation of a “VALUE” cell is “equal to”, but when negate is true, the evaluation will be “not equal to”.

kind	negate=`false`	negate=`true`
Value	is-equal-to	is-not-equal-to
List	is-in-list	is-not-in-list
Range	is-between	is-not-between
Collection	is-in-collection	is-not-in-collection
Ineffable	cannot be defined	cannot be defined
Answered	respondent-has-answered	respondent-has-not-answered
Invite Collections	is-in-collection	is-not-in-collection
Static Invite Collections	is-in-collection	is-not-in-collection

Value Cell

A value cell is a cell that defines an is-equal-to or is-not-equal-to evaluation. Only a single attribute answer value is present on a value cell’s value property.

{
  "tag": "90606986-5508-461b-a821-216e9a72f1a0",
  "attribute_id": 120,
  "negate": false,
  "kind": "VALUE",
  "value": "45398"
}

List Cell

A list cell is a cell that defines an is-in-list or is-not-in-list evaluation. A list cell has an additional operator property that can change the evaluation of its answer set. An operator value of AND changes the list evaluation to contains-all-of or does-not-contain-all-of. An operator value of OR indicates the default evaluation. Many attribute answer values can be present on a list cell’s list property.

{
  "tag": "aa7169c0-cb34-499a-aadd-31e0013df8fd",
  "attribute_id": 231302,
  "negate": false,
  "operator": "OR",
  "kind": "LIST",
  "list": [
    "514802",
    "514804",
    "514808",
    "514810"
  ]
}

Range Cell

A range cell is a cell that defines an is-between or is-not-between (inclusive) evaluation. A lower-bound and upper-bound integer value can be present on a range cell in the range.from and range.to properties. When the upper or lower-bound of the range is null, this represents an unbounded range.

{
  "tag": "75a36c67-0328-4c1b-a4dd-67d34688ff68",
  "attribute_id": 80,
  "negate": false,
  "kind": "RANGE",
  "range": {
    "from": 18,
    "to": 65
  }
}

Collection Cell

A collection cell is a cell that defines a large list of values having an is-in-collection or is-not-in-collection evaluation. A collection cell has an additional operator property that can change the evaluation of its answer set. An operator value of AND changes the collection evaluation to contains-all-of or does-not-contain-any-of. An operator value of OR indicates the default evaluation. This large list of values must be downloaded via the /download-collection endpoint using the value found in the cell’s collection property.

{
  "tag": "ff65b422-e810-4f3f-b1f8-f4e63b59ffa2",
  "attribute_id": 8,
  "negate": false,
  "operator": "OR",
  "kind": "COLLECTION",
  "collection": "2169733"
}

Ineffable Cell

An ineffable cell is a cell that cannot be defined in any way that can be understood by a partner. A partner may choose to ignore opportunities containing such cells, or send traffic into them with the understanding that there is additional targeting that the partner cannot account for.

{
  "tag": "dd64b622-ed10-4a3b-e1h8-a4e63b59vha2",
  "attribute_id": 83,
  "negate": false,
  "kind": "INEFFABLE"
}

Answered Cell

An answered cell is a cell that defines a boolean condition: either a respondent answer exists in Dynata’s system when negate is false, or a respondent answer does not exist when negate is true.

{
  "tag": "kei35kkjj-d00k-52kj-b3j4-a4jinx9832",
  "attribute_id": 8,
  "negate": true,
  "kind": "ANSWERED"
}

Invite Collections Cell

An invite collections cell is a cell that defines a large list of values having an is-in-collection or is-not-in-collection evaluation. An invite collections cell has an additional operator property that can change the evaluation of its answer set. An operator value of AND changes the collection evaluation to contains-all-of or does-not-contain-any-of. An operator value of OR indicates the default evaluation.

[
  {
    "tag": "d559212d-7984-4239-89c2-06c29588d79e",
    "attribute_id": 238383,
    "negate": false,
    "operator": "OR",
    "kind": "INVITE_COLLECTIONS",
    "invite_collections": [
      "621065",
      "621075"
    ]
  },
  {
    "tag": "d559212d-7984-4239-89c2-06c29588d79e",
    "attribute_id": 238384,
    "negate": true,
    "operator": "OR",
    "kind": "INVITE_COLLECTIONS",
    "invite_collections": [
      "621041",
      "621042"
    ]
  }
]

Static Invite Collections Cell

A static invite collections cell is a cell that defines a large list of values having an is-in-collection or is-not-in-collection evaluation. A static invite collections cell has an additional operator property that can change the evaluation of its answer set. An operator value of AND changes the collection evaluation to contains-all-of or does-not-contain-any-of. An operator value of OR indicates the default evaluation.

[
  {
    "tag": "d559212d-7984-4239-89c2-06c29588d79e",
    "attribute_id": 28,
    "negate": false,
    "operator": "OR",
    "kind": "STATIC_INVITE_COLLECTIONS",
    "invite_collections": ["28_2171139"]
  },
  {
    "tag": "d559212d-7984-4239-89c2-06c29588d79e",
    "attribute_id": 28,
    "negate": true,
    "operator": "OR",
    "kind": "STATIC_INVITE_COLLECTIONS",
    "invite_collections": ["28_2171137"]
  }
]

Filters

Filters are grouping structures that define how cells should be combined for evaluation. Filters have no quota or status, so they can be thought of as general qualifying criteria. The filters property of an opportunity is an array of “filter groups” which each contain an array of “filter objects”. Filter objects each contain an array of “filter cells”, the values of which are tags that reference the individual cells defined in the cells top-level property of the opportunity.

No Filters
Section titled “No Filters”

Though rare, it’s possible for opportunities to have no filters.

Filter Groups

Filter groups have an AND relationship between one another. For a respondent to qualify for an opportunity, the respondent must match each filter group defined. For a respondent to match a filter group, the respondent must match at least one filter object within the filter group.

Filter Objects

Filter objects within a filter group have an OR relationship between one another. As stated earlier, to match a filter group, a respondent must match at least one filter object within the group. For a respondent to match a filter object, the respondent must match all filter cells referenced in the filter object.

Filter Cells

Each filter cell within a filter object is a reference to the tag of a cell defined within the cells top-level property of the opportunity. Filter cells have an AND relationship between one another, indicating that a respondent must match all referenced cells within the filter object.

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

In the above example, the evaluation logic for a qualifying respondent would look like the following:

((aa7169c0-cb34-499a-aadd-31e0013df8fd OR (a1c44026-6c20-40e4-ab7c-0bf6e7bd7890 AND 90606986-5508-461b-a821-216e9a72f1a0)) AND 75a36c67-0328-4c1b-a4dd-67d34688ff68)

Quotas

Quotas are grouping structures that define how cells should be combined for evaluation. Quotas are nearly identical to filters, however, quotas will have a count and status. In order for a respondent to qualify for a quota, the quota’s count must be greater than zero and must have a status of “OPEN”. The quotas property of an opportunity is an array of “quota groups” which each contain an array of “quota objects”. Quota objects each contain an array of “quota cells”, the values of which are tags that reference the individual cells defined in the cells top-level property of the opportunity.

Quota Groups

Quota groups have an AND relationship between one another. For a respondent to qualify for an opportunity, the respondent must match each quota group defined. For a respondent to match a quota group, the respondent must match at least one quota object within the quota group.

Quota Objects

Quota objects within a quota group have an OR relationship between one another. As stated earlier, to match a quota group, a respondent must match at least one quota object within the group. For a respondent to match a quota object, the respondent must match all quota cells referenced in the quota object. Also, the quota object must have a count property value that is greater than 0, and the quota object must have a status property value equal to “OPEN”.

Quota Cells

Each quota cell within a quota object is a reference to the tag of a cell defined within the cells top-level property of the opportunity. Quota cells have an AND relationship between one another, indicating that a respondent must match all referenced cells within the quota object.

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

In the above example, the quota 9b331500690bfa19e442a32ad8c74923332318792f98441b025c5638028d4339 has a CLOSED status. Therefore, any respondent matching that quota will not qualify.

Project Requirements

Each opportunity contains a requirements object as part of its definition. These requirements define specific criteria for an opportunity. For example, an opportunity with requirements.requires_webcam = true will call for a webcam to participate in the client survey. Partners may use a requirements to match or exclude respondents from opportunities.

:requirements	description
`requires_recontact`	Requires inviting (recontacting) specific respondents to a follow-up client survey.
`requires_pii_collection`	Requires respondents to provide personally identifiable information (PII) within the client survey.
`requires_webcam`	Requires respondents to use a webcam to participate.
`requires_eye_tracking`	Requires respondents to use facial recognition technology, such as eye tracking.
`requires_cookie_drops`	Requires partners to allow Dynata to drop a cookie on the respondent.
`requires_sample_plus`	Requires partner-uploaded respondent PII to expand third-party matched data.
`requires_app_vpn`	Requires respondents to download a software application.
`requires_manual_rewards`	Requires additional incentives to be manually awarded to respondents by partners outside the typical survey flow.

{
  "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
  }
}