All Versions

Version 1
Version 2


Page tree

Supplier API v2

Skip to end of metadata
Go to start of metadata

Table of Contents

Overview

The /members endpoint is available for you to add or update your members in our system. It also allows you to see what information we have collected about your members through our pre-screening process, or to remove members and their associated data.

We do not require you to send your member data to us in advance, unless you plan to utilize any endpoints in which we attempt to evaluate a member for a specific target. However, we do require that you send a unique member identifier to us for each member within the survey URL. The variable name and procedures for doing this will be discussed as a part of your on-boarding process.

All of the API endpoints provided utilize your member id. We do not expose our internal ids to you, and consequently do not require you to map our internal ids to your members. We hope that this will simplify your integration with our API.

By utilizing your member ID through the API and through the target survey URLs, we are able to accurately match your members to their data when they arrive at our site. This simplifies the pre-screening process and provides a better member experience because we will not ask your member to answer any questions for which we already have a stored response. The more data you provide up front, or the more data we collect on repeat visits, the better the experience for your members!

Version 1.0

Data Model

NameTypeGETPOSTPUTRequiredDescription
_links#_links(tick)(error)(error)(error)Object containing links to related resources
_metadata#_metadata(tick)(error)(error)(error)Metadata describing this resource
memberId
integer(tick)(tick)(error)(tick)The ID provided by you for this member
memberStatus
enumeration(tick)(error)(error)(error)
NameDescription
activeThe member is considered active and is allowed to participate in our surveys.
temporary usage restrictionThe member has hit a limit on the number of surveys allowed and is temporarily restricted from taking surveys. Refer to temporaryRestrictionExpires in the _metadata to see when the restriction will be lifted.
temporary quality restrictionThe member has failed a minor quality check and is temporarily restricted from taking surveys. Refer to temporaryRestrictionExpires in the _metadata to see when the restriction will be lifted.
bannedThe member has failed a major quality check and is permanently banned from participating in our surveys.
emailstring(tick)(tick)(tick)(error)

Member's email address

languageenumeration(tick)(tick)(tick)(tick)

Member's primary language. Refer to the list of valid language codes.

firstNamestring(tick)(tick)(tick)(error)

Member's first name

lastNamestring(tick)(tick)(tick)(error)

Member's last name

birthDatedate(tick)(tick)(tick)(tick)Member's full birth date.
addressAddress(tick)(tick)(tick)(tick)Object containing the member's address information.

Examples


{
  "_links": {
    "self": {
      "href": "https://supplier.cmix.com/api/v2/members/ID0001",
      "class": "members",
      "identifier": "ID0001"
    },
    "demographics": {
      "href": "https://supplier.cmix.com/api/v2/members/ID0001/demos",
      "class": "demos"
    }
  },
  "_metadata": {
    "created": "2019-01-08T10:37:02Z",
    "lastModified": "2019-01-08T10:38:58Z"
  },
  "memberId": "ID0001",
  "memberStatus": "active",
  "email": "id0001@example.com",
  "language": "EN",
  "firstName": "Kevin",
  "lastName": "Lirot",
  "birthDate": "1971-01-28",
  "address": {
    "country": "US",
    "streetAddress": "8600 S Wilkinson Way, Suite D",
    "city": "Perrysburg",
    "state": "OH",
    "postalcode": "43551",
    "zipPlus4": "9331",
    "zipDeliveryPoint": "86"
  }
}

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

valuesLinkLink to the acceptable response values for this demographic

Examples

"self": {
  "href": "https://qa-supplier.cmix.com/api/v2/demographics/16",
  "class": "demographics",
  "identifier": 16
},
"values": {
  "href": "https://qa-supplier.cmix.com/api/v2/demographics/16/values",
  "class": "values"
}

_metadata

NameTypeDescription
createddatetimeWhen this member was created
lastModifieddatetimeWhen the last modifications were made to this member
temporaryRestrictionExpiresdatetimeBased on the member status, the date/time when this member will again be eligible to participate in our surveys.

Examples

{
  "created": "2018-08-21T10:34:16Z",
  "lastModified": "2018-08-22T13:39:13Z",
  "temporaryRestrictionExpires": "2019-01-09T00:00:00Z"
}

Address

Typically we only collect country and postal code, and country is the only information required for every member. Note that we may run a validation on postal codes submitted, and may reject data that we deem invalid. 

You may only submit country, postal code, and street address through this API. Any other address information shown may be derived by Critical Mix based on other information collected. We reserve the right to run additional validations and collect additional information about a member's address as required for specific targets. In the event that a project requires additional PII, it will be clearly indicated in the targetPii data element of the targetCriteria. Even though we do not allow you to set this additional data directly, we do make the data available for you to fetch via GET requests. This allows us to be transparent to you about additional data we have stored about your members in the event there are any privacy concerns.


NameTypeGETPOSTPUTRequiredDescription
country
enumerationThis is the only part of the address that is required for all members. See Countries for the list of acceptable country codes.
streetAddress
enumerationcross (x)

This should only contain data that is typically contained in address lines 1 and 2, such as street name and direction, building number, apartment, suite, etc. It should NOT contain personal or business names, city, state, province, region, or postal code. You may choose not to send this data initially. But, as with all other data points, we will collect the data as a part of our pre-screening process if the member is evaluated for a project that requires additional PII. Refer to the note above for additional information.

cityenumerationcross (x)cross (x)cross (x)

City, as determined by Critical Mix based on Postal Code. This may be null unless we have chosen to run additional validations on the provided Postal Code.

statestringcross (x)cross (x)cross (x)

State for US Residents, as determined by Critical Mix based on Postal Code. This may also contain region or province information for members from other countries. This data will only be populated if the member has been evaluated for a target which requires additional PII to be collected. Please refer to the note above for more information.

postalcodestringcross (x)

Postal Code is not required. However, for some countries, most targets will require postal code to be collected as a part of the pre-screening process. We will collect this information as needed.

zipPlus4datecross (x)cross (x)cross (x)For US members only, this data may be populated if we have the member's full address and have run additional data validations to determine this value.
zipDeliveryPointaddresscross (x)cross (x)cross (x)For US members only, this data may be populated if we have the member's full address and have run additional data validations to determine this value.

Examples


{
  "country": "US",
  "streetAddress": "8600 S Wilkinson Way, Suite D",
  "city": "Perrysburg",
  "state": "OH",
  "postalcode": "43551",
  "zipPlus4": "9331",
  "zipDeliveryPoint": "86"
}

 

  • No labels
Write a comment…