/membervariables

This resource allows interaction with a collection of all Member Variables.

Resource URL

/v1/applications/{communityApiKeyName}/membervariables

Note:

Use the appropriate regional endpoint to ensure that you comply with your organization's privacy policy, and applicable laws and regulations. For details about the available regional endpoints, and how to identify your organization's region, see API Access.

Available Methods

Method Description
GET Get a collection of Member Variables.
POST Create a Member Variable.

Parameters

Parameters can be appended to the request to further refine the results returned.

Operation Description Example
Refine the response by field To reduce the number of fields returned, specify the fields in a comma separated list. /membervariables?fields=constraints
Filtering by value By default, all the items are returned unless you specify your criteria using the variable name and value
You can filter the response on the values in all of the available fields except for:
  • id
  • categories
  • memberVariableValues
  • constraints
/membervariables?name=satisfaction
Paging The default is 20 items are returned at a time and the maximum is 1000. Use the limit and offset query string parameters to effectively page through the results.
Sorting You can sort the results on all of the available fields except for:
  • constraints
  • categories
  • memberVariableValues
/membervariables?sort=type:d

For more information, see Content control.

Field Descriptions

Field Description
categories The string value for the member variable category. Possible values are profileVariable, systemVariable. or both.
constraints The constraints collection specifies a set of behaviors that the system will implement for a given Member Variable. For the most part, these need not be adjusted from their defaults. For each supported constraint in the collection, a boolean value is recorded.
Property Description
disabled Not implemented
hidden When set to true, the Member Variable will no longer be returned when sending a GET request to the /membervariables resource. However, it will remain accessible by specifying an id using the /membervariables/{id} resource.
readOnly Not implemented
returnLatest When set to true, this indicates that the latest Member Value should always be returned. This is true for System Variables such as email. This behavior can be seen in the /membervalues/asof/{datetime} resource.
uniquePerMember

When this constraint is set to true, the service will ensure that a given Member Variable Value is only ever assigned (including historically) to one member. The purpose of enabling this constraint is for implementing identity such as the email System Variable.

It can also be set for non-System Variables and is helpful when integrating another system that has its own means of uniquely identifying members.

createdBy The GUID for the user who created the record.
createDate The date timestamp (UTC) for when the record was created.
dataType The string value for the value definition (for example, number).

A Member Variable also has a datatype property, which controls the type of storage and retrieval of its Member Variable Values.

A datatype can be:

  • text
  • date
  • numeric
description The string name for the member variable.
id The GUID for the given member variable.
href A link that points to specific member variable.
lastUpdatedBy The GUID for the user who last updated the record.
lastUpdateDate The date timestamp (UTC) for when the record was last updated.
links This field is always empty.
memberVariableValues The link that points to the member variable values.
name The string name for the member variable.
referenceMemberVariableId The profile variable referenced by a calculated date profile variable. This field is only returned for calculated dates. The referenced variable must be set with the type: Open and the dataType: Date.
sensitive The boolean value indicating whether or not the variable is eligible to be purged or modified.

You cannot POST a new value to the following sensitive system variables:

  • email
  • firstname
  • lastname
  • name
  • signupemail
  • signupfirstname
  • signuplastname
  • unsubscribereasonother
  • username
sequenceId This is an internal field.
source The string value for the variable type. Possible values are:
  • system
  • profile

This field may also be empty.

type The string value for question type. Possible values are:
  • open: Allows only a single Member Value to be assigned at any time, but indicates an unlimited number of possible values.

    Sample question: "Which city do you live in?"

  • singleChoice:Allows one Member Value to be assigned to a member at any point in time.

    Sample question: "Which city do you live in?"

  • multiChoice: Allows more than one Member Value to be assigned at any point in time.

    Sample question: "Select all the grocery stores you have shopped at from the list."

Note: Both singleChoice and multiChoice indicate a finite list of choices. For example, a list of answer options in a Multiple Choice question.
GET response structure

{
   "meta": {
      "offset": 0,
      "limit": 20,
      "count": 1
   },
   "items": [
      {
         "id": <GUID for member variable>,
         "name": <member variable name>,
         "description": <member variable description>,
         "source": <system|profile>,
         "type": <question type>,
         "dataType": <text|numeric|date>,
         "constraints": {
            "disabled": <true|false>,
            "hidden": <true|false>,
            "readOnly": <true|false>,
            "returnLatest": <true|false>,
            "uniquePerMember": <true|false>
         },
         "categories": [
            <array of profileVariable|profileVariable>
         ],
         "memberVariableValues": {
            "href": "https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/membervariables/membervariablevalues?memberVariableId={GUID for member variable}"
         },
         "sequenceId": <integer>,
         "sensitive": <true|false>,
         "createDate": <date and time UTC>,
         "lastUpdateDate": <date and time UTC>,
         "createdBy": <GUID of user>,
         "lastUpdatedBy": <GUID of user>,
         "links": [],
         "href": "https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/membervariables/{GUID for member variable}"
      }
   ],
   "links": [
      {
         "rel": "first",
         "href": "https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/membervariables?offset=0&limit=20"
      },
      {
         "rel": "prev"
      },
      {
         "rel": "last",
         "href": "https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/membervariables?offset=20&limit=20"
      },
      {
         "rel": "next",
         "href": "https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/membervariables?offset=20&limit=20"
      }
   ],
   "href": "https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/membervariables"
}

POST Behavior

The /membervariables resource can be created by sending a POST request either for a single item or a collection to /membervariables.

The following table indicates which properties must be included in a POST request, as well as the default values that will be set when not included.
Property Required on POST? Default Notes
categories No ["profileVariable"]
constraints No false for all
dataType No text
description No Proper-cased name The maximum number of characters is 2000.
name Yes User input required, lowercased The maximum number of characters is 400.
referenceMemberVariableId No A field ID, or list of field IDs Used for Calculated Date profile variables
sensitive No false For Calculated Dates, indicates that the referenced profile variable is sensitive.
source No Empty string
type No singleChoice
Example: POST /membervariables
[
   {
      "name": "City",
      "type": "singleChoice",
      "dataType": "text"
   },
   {
      "name": "Date of Birth",
      "type": "open",
      "dataType": "date"
   },
   {
      "name": "Areas of Interest",
      "type": "multiChoice",
      "dataType": "text"
   },
   {
      "name": "Income",
      "type": "open",
      "dataType": "numeric"
   },
   {
      "name": "Current Age",
      "type": "open",
      "dataType": "text",
      "sensitive": "true",
      "referenceMemberVariableId": "0872f5f9-d5b4-49a7-a5d7-afb201083a97"
    }
]

Sensitive Fields

All of the Member Variables contain a boolean property named sensitive. This property indicates whether or not the variable is eligible to be purged or modified.

You cannot POST a new value to the following sensitive system variables:

  • email
  • firstname
  • lastname
  • name
  • signupemail
  • signupfirstname
  • signuplastname
  • unsubscribereasonother
  • username
Example: System Variable

The following is an example of the email system variable. Notice that the value for source is system, and the value for sensitive is true. 


...
 "items": [
    {
      "id": <GUID of member variable>,
      "name": "email",
      "description": "email",
      "source": "system",
      "type": "open",
      "dataType": "text",
      "constraints": {
        "disabled": false,
        "hidden": false,
        "readOnly": false,
        "returnLatest": true,
        "uniquePerMember": true
      },
      "categories": [
        "profileVariable",
        "systemVariable"
      ],
      "memberVariableValues": {
        "href": "https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/membervariablevalues?memberVariableId={GUID for member variable}"
      },
      "sequenceId": <integer>,
      "sensitive": true,
      "createDate": <date and time UTC>,
      "lastUpdateDate": <date and time UTC>,
      "createdBy": <GUID of user>,
      "lastUpdatedBy": <GUID of user>,
      "links": [],
      "href": "https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/membervariables/{GUID for member variable}"
    },
...

System variables

System variable Variable name Description
Email email The member's email address.
First Name firstname The member's first name.
Forum Responder Type forumrespondertype

The member's participation status in a forum.

Possible values are:

  • Active
  • Lurked
  • NeverInvited
  • NonResponder
  • Passive
  • TopPoster
For more information see, Forum participation and Forum statistics.
GCM Device Tokens gcmdevicetokens This field has been deprecated.
Join Date joindate The date on which the member confirmed that they were joining the community.
Join Date joindate The date on which the member confirmed that they were joining the community.
Last Login Date lastlogindate The last date on which a member signed in to the portal.
Last Name lastname The member's last name.
Member Status memberstatus The current status of the member in the system.

Possible values are:

  • Nonmember

    The person is not a member of the community. The person's email address and profile attributesvariables are in the system; however, the person has not been recruited yet.

  • Pending
    A person is marked Pending when one of the following has occurred:
    • The person receives an email invitation to join the community
    • The person clicks the recruitment link in the email without completing the recruitment survey
    • The person completes the recruitment survey without confirming their membership
  • Active

    The person is a member of the community and can be invited to participate in activities.

  • Purged

    The member was purged from the community. You cannot send Purged members invitations or reminders for any activity type.

  • Undeliverable
    A member is marked Undeliverable if the following occurs:
    • Three consecutive hard bounces (email delivery failed because of a server error or because the email address was invalid)
    • Ten consecutive soft bounces (email delivery failed because the member's inbox was full)
    • One spam complaint (email delivered to a Hotmail, AOL, or Yahoo account was marked as spam)

    You cannot send Undeliverable individuals invitations or reminders for activities.

  • Unsubscribed

    The member no longer wants to receive emails from the community and has requested removal from the community. You cannot send Unsubscribed members invitations or reminders for activities.

Name name The name of the member.
Recruitment Communication ID recruitmentcommunicationid The unique ID associated with a recruitment's distribution email or recruitment link.
Recruitment Method recruitmentmethod The method through which a member was recruited.
Possible values are:
  • Unknown: The member's recruitment method is not known.
  • Email: The member was recruited through an email invitation.
  • SurveyLink: The member was recruited through a recruitment link.
Recruitment Source recruitmentsource The member's recruitment source (for example, a recruitment link posted on social media or a CSV upload).
Recruitment Status recruitmentstatus

The member's status in the recruitment process.

Possible values are:
  • ConfirmationSent
  • invitationsent
  • Joined
  • RecruitmentSurveyStarted
  • Unknown
  • UploadedFromCsv
Sign Up Email signupemail The email address the member used to join the community.
Sign Up First Name signupfirstname The member's first name at the time they joined the community.
Sign Up Last Name signuplastname The member's last name at the time they joined the community.
Sign Up Recruitment Stats signuprecruitmentstatus The member's status in the sign up process.

Possible values are:

  • ConfirmationSent
  • invitationsent
  • Joined
  • RecruitmentSurveyStarted
  • Unknown
  • UploadedFromCsv
Survey Responder Type surveyrespondertype

The member's survey participation status.

Possible values are:

  • goodresponder
  • idealresponder
  • NeverInvited
  • NonResponder
  • poorresponder
Unsubscribe Reason unsubscribereason

The reason why a member has requested their removal from the community and unsubscribed themselves.

During the unsubscribe process, the application asks members an optional question about why they are leaving the community. Possible values are:

  • NotSpecified (the member chose not to answer the question)
  • NotRelevant ("The communications were not relevant to me")

  • TooManyCommunications ("Too many communications")

  • NotEnoughCommunication ("Not enough communications")
  • NotAsExpected ("I was expecting something different")
  • ResponseTimeTooShort ("I am not given enough time to respond")
  • NotValued ("I don't feel that my input or opinions are valued")
  • Other (the member has a different reason for leaving the community, as specified for unsubscribereasonother)
Unsubscribe Reason (other) unsubscribereasonother The exact reason why members have requested their removal from the community and unsubscribed themselves, if they chose Other for unsubscribereason.
Upload ID uploadid The unique ID for the CSV upload.
Username username The member's username for the community.