Skip to content

List (list)

list is the standard Dataverse marketing list entity. akoyaGO uses it to group contacts (and less commonly, accounts and leads) for segmentation, mailings, and third-party email-platform audience sync. Lists can be static (explicit member enumeration) or dynamic (stored query that re-evaluates on demand).

For the complete base schema, see the Microsoft Dataverse list reference. This page focuses on how integration partners use list in akoyaGO.

At a glance
Display name Marketing List
Logical name list
Primary ID attribute listid
Primary name attribute listname
Entity set name (Web API) lists
Ownership UserOwned
Change tracking Enabled (standard)
Audit Enabled (standard)

Web API

GET  {org}/api/data/v9.2/lists
GET  {org}/api/data/v9.2/lists({listid})
POST {org}/api/data/v9.2/lists

The akoyaGO role of list

Typical uses:

  • External audience mapping — each external email-platform audience corresponds to one akoyaGO list. Partners pull the list's members and push them to the external platform.
  • Event invitations — static lists of invitees.
  • Segmentation via akoya_CriteriaList — akoyaGO's custom criteria entities layer on top of list to define reusable membership rules.
  • Mail merges and form letter distribution.

Columns most used in integrations

Logical name Type Description
listname String Display name.
purpose String Free-text purpose / description.
type Boolean Static (false) vs. dynamic (true).
createdfromcode Choice Member entity type — 2 (account), 3 (lead), 4 (contact). Most akoyaGO lists are type 4.
membercount Integer Cached member count.
lockstatus Boolean Whether the list is locked (prevents member changes).
query String For dynamic lists, the FetchXML query that defines membership.
createdon / modifiedon DateTime Standard lifecycle timestamps.
statecode / statuscode Choice Active / inactive lifecycle.

Reading list members

Static and dynamic lists expose their members through the listmember_association relationship. For a static contact list:

GET {org}/api/data/v9.2/lists({listid})/listmember_association?$select=contactid,fullname,emailaddress1&$filter=statecode eq 0
Accept: application/json
OData-Version: 4.0
OData-MaxVersion: 4.0

LIST_ID="..."
curl "https://{org}.crm.dynamics.com/api/data/v9.2/lists($LIST_ID)/listmember_association?\$select=contactid,fullname,emailaddress1&\$filter=statecode%20eq%200" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "OData-Version: 4.0" \
  -H "OData-MaxVersion: 4.0"

list_id = "..."
r = requests.get(
    f"{ORG}/api/data/v9.2/lists({list_id})/listmember_association",
    params={"$select": "contactid,fullname,emailaddress1", "$filter": "statecode eq 0"},
    headers=headers,
)
members = r.json()["value"]

var listId = new Guid("...");
var query = new QueryExpression("listmember") {
    ColumnSet = new ColumnSet("entityid"),
    Criteria = {
        Conditions = {
            new ConditionExpression("listid", ConditionOperator.Equal, listId)
        }
    }
};
var members = service.RetrieveMultiple(query);
foreach (var m in members.Entities) {
    var contactId = m.GetAttributeValue<Guid>("entityid");
    var c = service.Retrieve("contact", contactId,
        new ColumnSet("fullname", "emailaddress1"));
}

For a dynamic list, members are resolved on the fly. The AddMembersList and CopyDynamicListToStatic messages convert between the two — see Dataverse actions for marketing lists.

Supported messages

Message Supported
Create ✓
Retrieve ✓
RetrieveMultiple ✓
Update ✓
Delete ✓
AddMembersList ✓ (static lists)
RemoveMembersList ✓ (static lists)
CopyDynamicListToStatic ✓
Upsert — (no akoyaGO alternate keys)

Examples

Conventions

Examples assume ORG (env URL), access_token (valid bearer), headers (standard Dataverse headers dict), and service (a ServiceClient instance). See Authentication.

List all active marketing lists of contacts

GET {org}/api/data/v9.2/lists?
  $select=listname,purpose,type,membercount&
  $filter=statecode eq 0 and createdfromcode eq 4&
  $orderby=listname asc
Accept: application/json
OData-Version: 4.0
OData-MaxVersion: 4.0

curl "https://{org}.crm.dynamics.com/api/data/v9.2/lists?\$select=listname,purpose,type,membercount&\$filter=statecode%20eq%200%20and%20createdfromcode%20eq%204&\$orderby=listname%20asc" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "OData-Version: 4.0" \
  -H "OData-MaxVersion: 4.0"

r = requests.get(
    f"{ORG}/api/data/v9.2/lists",
    params={
        "$select": "listname,purpose,type,membercount",
        "$filter": "statecode eq 0 and createdfromcode eq 4",
        "$orderby": "listname asc",
    },
    headers=headers,
)
lists = r.json()["value"]

var query = new QueryExpression("list") {
    ColumnSet = new ColumnSet("listname", "purpose", "type", "membercount"),
    Criteria = {
        Conditions = {
            new ConditionExpression("statecode", ConditionOperator.Equal, 0),
            new ConditionExpression("createdfromcode", ConditionOperator.Equal, 4)
        }
    },
    Orders = { new OrderExpression("listname", OrderType.Ascending) }
};
var lists = service.RetrieveMultiple(query);

Members of a specific list

Static and dynamic lists both expose members through the listmember_association relationship.

GET {org}/api/data/v9.2/lists({listid})/listmember_association?
  $select=contactid,firstname,lastname,emailaddress1,akoya_godonateemailconfirmed&
  $filter=statecode eq 0
Accept: application/json
OData-Version: 4.0
OData-MaxVersion: 4.0

curl "https://{org}.crm.dynamics.com/api/data/v9.2/lists({listid})/listmember_association?\$select=contactid,firstname,lastname,emailaddress1,akoya_godonateemailconfirmed&\$filter=statecode%20eq%200" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "OData-Version: 4.0" \
  -H "OData-MaxVersion: 4.0"

r = requests.get(
    f"{ORG}/api/data/v9.2/lists({list_id})/listmember_association",
    params={
        "$select": "contactid,firstname,lastname,emailaddress1,akoya_godonateemailconfirmed",
        "$filter": "statecode eq 0",
    },
    headers=headers,
)
members = r.json()["value"]

// Query listmember to get contact IDs for a given list, then retrieve the contacts.
var memberQuery = new QueryExpression("listmember") {
    ColumnSet = new ColumnSet("entityid"),
    Criteria = {
        Conditions = {
            new ConditionExpression("listid", ConditionOperator.Equal, listId)
        }
    }
};
var memberRows = service.RetrieveMultiple(memberQuery);

var contactIds = memberRows.Entities
    .Select(e => e.GetAttributeValue<Guid>("entityid"))
    .ToList();

var contactQuery = new QueryExpression("contact") {
    ColumnSet = new ColumnSet("firstname", "lastname", "emailaddress1", "akoya_godonateemailconfirmed"),
    Criteria = {
        Conditions = {
            new ConditionExpression("contactid", ConditionOperator.In, contactIds.Cast<object>().ToArray()),
            new ConditionExpression("statecode", ConditionOperator.Equal, 0)
        }
    }
};
var members = service.RetrieveMultiple(contactQuery);

Change history

This page documents the akoyaGO-specific usage of the standard Dataverse list entity. Base entity schema is not replicated here.