/membervalues

This resource allows the interaction with a collection of all Member Values for your community.

Note: Member data APIs expose all the member data stored in the database. When you make a simple call that requests all the variables for all the members without filter controls, you are essentially requesting a copy of the full database.
To avoid timeouts and performance issues, we strongly recommend using a time range to filter your requests plus one or more of the following parameters:
  • memberId
  • memberVariableId
  • memberVariableValue
Examples:
  • Get all variables for a subset of members within a specific time range
  • Get some variables all members within a specific time range

For more information, see Content control.

Resource URL

/v1/applications/{communityApiKeyName}/membervalues

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 values.
POST Create a member value.

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. /membervalues?fields=memberEmail
Filtering on items 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
  • links
Tip: You can filter a memberVariableValue on an open end text response.

/membervalues?memberEmail=email@example.com

/membervalues?memberVariableName=email&q="memberVariableValue.contains("gmail")"

Tip: If the memberVariableValue is a string, but the member variable value is actually an integer, then format your query string as q=memberVariableValue="integer".

For example, /membervalues?membervariablename=groupId&q=memberVariableValue="123"

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:
  • communityId
  • href
  • id
  • links
  • memberDataSetType
  • memberEmail
/membervalues?sort=memberId:d

For more information, see Content control.

Field Descriptions

Field Description
communityId This field is deprecated and will likely be removed from this resource. Please do not use.
createDate Date and timestamp (UTC) the Member Value was created.
createdBy GUID of the user who created the Member Value.
effectiveDate This field exposes the time-series aspect of Member Value data. The date-time is formatted as UTC at which this Member Value is effective.

The implication is that the said Member Value is valid from this time forward, unless another Member Value is recorded at a later point in time, in which case the newer Member Value would then take precedence.

href Link to the Member Value.
id GUID of the Member Value.
lastUpdateDate Date and timestamp (UTC) the Member Value was last updated.
lastUpdatedBy GUID of the user who last updated the Member Value.
links This field will always be empty.
memberDataSetType Live or Test, distinguishing if this Member Value represents test data or live data.
memberEmail The current email address for the member to whom this Member Value belongs.
Note: memberEmail is modeled and stored as a System Variable called email, but returned here for convenience given the prominence of email as an external identifier for members.
memberId The GUID of the member to whom this Member Value belongs.
memberSequenceId The integer ID of the member to whom this Member Value belongs.
memberVariableId The GUID of the Member Variable to which the assigned Member Variable Value belongs.
memberVariableName The name of the Member Variable to which the assigned Member Variable Value belongs.
memberVariableSequenceId The integer ID of the Member Variable to which the assigned Member Variable Value belongs.
memberVariableType The type of Member Variable to which the assigned Member Variable Value belongs.
memberVariableValue The value of the Member Variable Value being assigned.
memberVariableValueId The GUID of the Member Variable Value being assigned.
memberVariableValueSequenceId The integer ID of the Member Variable Value being assigned.
GET response structure

{
  "meta": {
    "offset": 0,
    "limit": 1,
    "count": 1
  },
  "items": [
    {
      "id": <GUID of member value>,
      "communityId": <deprecated>,
      "memberId": <GUID of member>,
      "memberEmail": <current email address of member>,
      "memberVariableId": <GUID of member variable>,
      "memberVariableName": <name of member variable>,
      "memberVariableType": <type of member variable>,
      "memberVariableValueId": <GUID of member variable value>,
      "memberVariableValue": <value of member variable value>,
      "memberSequenceId": <integer ID of member>,
      "memberVariableSequenceId": <integer ID of member variable>,
      "memberVariableValueSequenceId": <integer ID of member variable value>,
      "memberDataSetType": <Live|Test>,
      "effectiveDate": <date-time (UTC) as of when this member value became effective>,
      "createDate": <date-time (UTC of create date)>,
      "lastUpdateDate": <date-time UTC of last update>,
      "createdBy": <GUID of user>,
      "lastUpdatedBy": <GUID of user>,
      "links": [],
      "href": "https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/membervalues/{membervaluesId}"
    }
  ],
  "links": [
    {
      "rel": "first",
      "href": "https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/membervalues?limit=1&offset=0"
    },
    {
      "rel": "prev"
    },
    {
      "rel": "last",
      "href": "https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/membervalues?limit=1&offset=1688"
    },
    {
      "rel": "next",
      "href": "https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/membervalues?limit=1&offset=1"
    }
  ],
  "href": "https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/membervalues?limit=1"
}

POST Behavior

The /membervalues resource is feature rich in its POST behavior. In its simplest form, it can be used to create an assignment between an existing member, Member Variable, and Member Variable Value. At its most complex, it can be used to create a new member, a new Member Variable, a new Member Variable Value, and link those together. As such, there is a large number of possible scenarios.

In general, it is not recommended to create new Member Variable Values via this mechanism. However, it will often be more convenient not to explicitly create Member Variable Values first, but instead, specify the membervariablevalue property, and allow the service to manage creation if needed.

Property Required On POST? Default
effectiveDate No Current date-time (UTC)
memberDataSetType No Live
memberEmail Alternate for memberId N/A
memberId Yes User input required
memberSequenceId Alternate for memberId N/A
memberVariableId Yes User input required
memberVariableName Alternate for memberVariableId N/A
memberVariableSequenceId Alternate for memberVariableId N/A
memberVariableType No
Note: This field is required if you are creating a new member variable which is not recommended.

Specify the membervariablevalue property instead, and allow the service to manage creation if needed.

N/A
memberVariableValue Alternate for memberVariableValueId
Tip: For most cases, (especially for open type variables), it will be easiest to provide the value directly.
N/A
memberVariableValueId Yes
Tip: For bulk POSTs of singleChoice or multiChoice variables, it is recommended to look up these IDs and include them when creating the ID.
User input required
memberVariableValueSequenceId Alternate for memberVariableValueId N/A
Example: POST /membervalues

[
   {
      "memberVariableId": <GUID of member variable value>,
      "memberId": <GUID of member>,
      "memberVariableValue": <value of member variable value>
   },
   {
      "memberVariableId": <GUID of member variable value>,
      "memberId": <GUID of member>,
      "memberVariableValue": <value of member variable value>
   }
]