All Versions

Version 1
Version 2


Page tree

Supplier API v2

Skip to end of metadata
Go to start of metadata


Targets define the criteria and price for a specific group of respondents needed to fulfill a need on one of our projects.

Table of Contents

Version 1.0

Data Model

NameTypeDescription
_links_linksObject containing links to related resources
_metadata_metadataMetadata describing this resource
targetIdintegerID of this target.
projectIdstringID of the project to which this target belongs. This is commonly referred to as our "CX Number"
audienceIdintegerAudience ID, provided for compatibility with version 1 of this API.
targetNamestring

User entered text for the name of the target. Sometimes this may be descriptive of the target. But, because it is user entered text and the target definition may change over time, we do not recommend using this data as a basis for logic or screening criteria.

This name is NOT a suitable name to be displayed to your members!

cpiMoneyThe current price we will pay for each completed interview.
statusenumeration
NameDescription
pendingThe target has not yet been launched. We do not recommend taking any action at this time as the setup may not be complete, or the target may never become active. See the Note below.
activethe target is currently open to receive traffic.
pausedthe target is not currently accepting traffic, but may open again in the future.
closedthe target is closed and will not re-open.

Note: Targets that are in pending status will not typically be returned by this API in your list of available targets from /targets. However, if you have the identifier for a target in this status, you will be able to call the /targets/{id} endpoint to retrieve the details of the target. This is to facilitate working manually with a project manager who may be looking for special assistance with a target that may not have launched yet.

expectedDaysInFieldintegerThe total number of days that this target is expected to be in field.
fillMethodenumeration
NameDescription
asap

Traffic should be sent in a manner to fill the need as soon as possible

evenly

Traffic should be sent at a pace to evenly fill quotas throughout the entire expected time in field. We may throttle your traffic to accommodate this.

expectedIncidencedecimalThe estimated incidence of survey completion among those who qualify for the survey and fit open quotas.
calculatedIncidencedecimalThe calculated incidence as completes / (completes + terminates) within the actual survey. This will be null until we have had sufficient traffic to calculate a reasonably accurate value.
expectedLoiintegerThe estimated length of interview.
calculatedLoiintegerThe calculated length of interview as the median of all completed surveys.
targetUrlTargetURLA URL object that specifies the URL and expected parameters.
targetSegmentenumeration

Identifies the market segment of the target audience

NameDescription
B2BThe target is intended for a Business-to-Business market
B2CTha target is intended for a Business-to-Consumer market
targetCategoryenumerationRefer to the list of target categories.
targetCriteriaTargetCriteriaScreening Criteria for this target.

Examples

{
  "_links": {
    "self": {
      "href": "https://supplier.cmix.com/api/v2/targets/141928",
      "class": "targets",
      "identifier": 141928
    },
    "exclusions": {
      "href": "https://supplier.cmix.com/api/v2/exclusions/104937",
      "class": "exclusions",
      "identifier": 104937
    }
  },
  "_metadata": {
    "created": "2018-08-21T10:34:16Z",
    "lastModified": "2018-08-22T13:39:13Z",
    "firstLaunched": "2018-08-21T10:45:51Z",
    "targetExpanded": "2018-08-21T10:34:16Z"
  },
  "targetId": 141928,
  "projectId": "CX - 57310",
  "audienceId": 307236,
  "cpi": {
    "amount": 2,
    "currency": "USD"
  },
  "status": "active",
  "expectedDaysInField": 3,
  "fillMethod": "asap",
  "expectedIncidence": 75,
  "calculatedIncidence": 72.36,
  "expectedLoi": 15,
  "calculatedLoi": 14,
  "targetUrl": {
    "url": "https://s.oneopinion.com/atc/src/100100JJCO6NGUTXR72XLNKV/15529876N8TPO4NZFKDLZWLW",
    "parameters": {
      "memberId": "mid",
      "sessionId": "sid"
    }
  },
  "targetSegment": "B2C",
  "targetCategory": "General Population",
  "targetCriteria": {
    "country": "US",
    "language": "EN",
    "basis": "completes",
    "requested": 5,
    "remaining": 4,
    "targetPii": {
      "addressRequired": true,
      "emailAddressRequired": false,
      "piiValidations": [
        {
          "validationService": "verity",
          "vaidationCriteria": "5"
        }
      ]
    },
    "invitationListId": null,
    "exclusionListId": 104937
  }
}

Links to related resources. Links are provided only in cases where the linked resource exists in the context of this target. 

NameTypeDescription
selfLink

Self-referencing link to the current object

qualificationsLinkLink to get the detailed qualifications for this target
invitationsLinkLink to the invitation list for this target, if one exists
exclusionsLinkLink to the exclusion list for this target, if one exists

Examples

{
  "self": {
    "href": "https://supplier.cmix.comapi/v2/targets/141928",
    "class": "targets",
    "identifier": 141928
  },
  "qualifications": {
    "href": "https://supplier.cmix.comapi/v2/targets/141928/qualifications",
    "class": "qualifications",
  },
  "exclusions": {
    "href": "https://supplier.cmix.com/api/v2/exclusions/104937",
    "class": "exclusions",
    "identifier": 104937
  }
}

_metadata

Links to related resources. Links are provided only in cases where the linked resource exists in the context of this target. 

NameTypeDescription
createddatetime

When this target was created

lastModifieddatetimeWhen the last modifications were made to this target
firstLauncheddatetimeIf the target has been set active, then this is the date that it first happened. This can be used as the reference point for expectedDaysInField.
targetExpandeddatetimeThis date specifically tracks only changes that expand the target criteria, meaning previously disqualified respondent may now qualify. You may consider re-evaluating anyone who disqualified prior to this date.

Examples

{
  "created": "2018-08-21T10:34:16Z",
  "lastModified": "2018-08-22T13:39:13Z",
  "firstLaunched": "2018-08-21T10:45:51Z",
  "targetExpanded": "2018-08-21T10:34:16Z"
}

TargetURL

This is the URL to which you should direct your members for participation in this target. The expected parameters must be passed in order for the member to be properly identified by our system. You may pass any additional parameters that you desire in the URL. The additional parameters will be stored and passed back to you unmodified in the redirect back to you at the end of the members participation.

NameTypeDescription
urlstringThe base URL directed to this target
parametersarray of ParametersRequired parameters that must be appended to the URL

Parameters

NameTypeDescription
memberIdstringThe expected name of the parameter in which you should pass your ID for the participating member
sessionIdstring

The expected name of the parameter in which you should pass a unique session or transaction ID for each participant

Examples

The blow example illustrates a response where the member id should be passed as "mid" and the session ID should be passed as "sid". Assuming that you are sending a member whose id is "X123" and you have generated a uniques session ID as "Y456" then the resulting full entry URL for the target for this member would be:

https://s.oneopinion.com/atc/src/100100JJCO6NGUTXR72XLNKV/15529876N8TPO4NZFKDLZWLW?mid=X123&sid=Y456

 

{
  "url": "https://s.oneopinion.com/atc/src/100100JJCO6NGUTXR72XLNKV/15529876N8TPO4NZFKDLZWLW",
  "parameters": {
    "memberId": "mid",
    "sessionId": "sid"
  }
}

 

 

TargetCriteria

Describes the pre-screening criteria which must be met for members to qualify to attempt the survey.

NameTypeDescription
countryenumerationTarget is open only to participants from the specified country. Refer to the list of valid country codes.
languageenumeration

Target is open only to participants who speak the specified language. Refer to the list of valid language codes.

basisenumeration
NameDescription
completesquantities are based on number of completes within the client survey.
startsquantities are based on number of starts within the client survey (sometimes referred to as "click balanced")
requestedintegerOverall number of completes/starts requested. This quantity may be a common target across multiple suppliers.
remainingintegerRemaining number of completes/starts still needed. This accounts for activity from other suppliers and may be a common remaining quantity.
targetPiiTargetPiiDescribes the PII requirements for this project,
invitationListIdintegerId of the invitation list. If not null, then an invitations link will be provided in the _links object.
exclusionListIdintegerId of the exclusion list. If not null, then an exclusions link will be provided in the _links object.

If a member ID exists in both invitations and exclusions for the same target, the exclusion list will take precedence over the invitation.

Examples

{
  "country": "US",
  "language": "EN",
  "basis": "completes",
  "requested": 5,
  "remaining": 4,
  "targetPii": {
    "addressRequired": true,
    "emailAddressRequired": false,
    "piiValidations": [
      {
        "validationService": "verity",
        "vaidationCriteria": "5"
      }
    ]
  },
  "invitationListId": null,
  "exclusionListId": 104937
}

TargetPii

This describes Critical Mix's requirement to collect PII from your member during the pre-screening process. We may need to collect PII for a variety of reasons, such as:

  1. To send a product for an In Home Use Test
  2. To allow for us to recontact the member for a planned follow-up survey
  3. To make payment of additional promised incentives
  4. To facilitate additional external data matches

This is the requirement for Critical Mix to collect and store PII. The survey may have its own requirements for collection of PII by our client which are not indicated here.

Any collected PII which fails to pass our validations may result in the member being blocked from all future survey opportunities, even those which do not require the collection of PII.

NameTypeDescription
addressRequiredbooleanIndicates that we are required to collect the member's full name and address for this target. Postal Code will be validated against standard lists or patterns. US Addresses will be validated using Imperium's Address Correction service.
emailAddressRequiredbooleanIndicates that email address must be collected from the member. Email addresses will be validated using Imperium's Real Mail validation service.
piiValidationsPiiValidationsList of additional PII validations that are required for this target.

Examples

{
  "addressRequired": true,
  "emailAddressRequired": false,
  "piiValidations": [
    {
      "validationService": "verity",
      "vaidationCriteria": "5"
    }
  ]
}

PiiValidations

This is an array of additional third-party services that will be used to validate PII that is collected from your member. You can improve your conversion rate by running these validations yourself prior to sending your member into the target, and only sending those members who meet the specified requirements.

NameTypeDescription
validationServiceenumerationName of the third-party validation service. The validation services and their criteria are described below.
validationCriteriaenumerationIdentifier for the definition of the required passing criteria, as described below.
validationServicevalidationCriteriaRequirements
Verity1Verity Score must be >= 1
2Verity Score must be >= 2
3Verity Score must be >= 3
4Verity Score must be >= 4
5 Verity Score must be >= 5
6Verity Score must be >= 6
7Verity Score must be = 7

Examples

[
  {
    "validationService": "verity",
    "vaidationCriteria": "5"
  }
]

Document Revision History

 

Version Date Comment
Current Version (v. 3) Dec 03, 2018 14:04 Kevin Lirot:
Added section for Document Revision History
v. 2 Nov 07, 2018 13:47 Kevin Lirot:
Added qualifications link and fixed data types in example JSON
v. 1 Oct 15, 2018 12:55 Kevin Lirot


  • No labels
Write a comment…