Named Account Lists

Named Account Lists Endpoint Reference

Named Account Lists in Marketo represent collections of named accounts.  They can be used for a wide variety of cases, including categorization, data enrichment, and smart campaign filtering.  The Named Account List APIs allow for remote management of these list assets and their membership.

Permissions

To query Named Account Lists, the Read-Only Named Account List or the Read-Write Named Account List permission is required.  To Create, Update, or Delete Lists, the Read-Write Named Account List permission is required.  Querying list membership requires the Read-Only Named Account or Read-Write Named Account permissions, while managing membership requires the Read-Write Named Account Permissions.

Model

Named Account Lists have a very limited number of standard fields, and are not extensible with custom fields.

Named Account List Fields

Name Data Type Updateable Notes
marketoGUID String False Unique string identifier of the named account list.  This field is system managed, and is not permitted as a field when creating a new record.  Field used by “dedupeBy”:”idField” when performing a create or update.
name String True Name of the list.  Field used by “dedupeBy”:”dedupeFields” when performing a create or update.
createdAt Datetime False Datetime of the creation of the list.  This field is system managed, and is not permitted as a field when creating or updating a record.
updatedAt Datetime False Datetime of the most recent update to the list.  This field is system managed, and is not permitted as a field when creating or updating a record.
type String False Type of the list.  May have a value of either “default” or “external”.  External lists are those created by CRM Account View.

Query

Querying account lists is simple and easy.  Currently, there are only two valid filterTypes for querying named account lists: “marketoGUID” and “name”.  The field to filter on is set in the “filterType” parameter of the query, and the values are set in “filterValues” as a comma-separated list.  The nextPageToken and batchSize filters are also optional parameters.

Create and Update

Creating and updating named account list records follows the established patterns for other Lead Database create and update operations.  Keep in mind that named account lists only have one updateable field, “name.”  The endpoint permits the three standard action types, “createOrUpdate,” “createOnly,” and “updateOnly.”  The “action” defaults to “createOrUpdate.”  The optional “dedupeBy” parameter permits the values “dedupeFields,” corresponding to “name,” or “idField,” corresponding to “marketoGUID.”  In createOrUpdate and createOnly modes, only “name” is permitted as the dedupeBy field.  You can submit up to 300 records at a time.

Delete

Deletion of Named Account Lists is simple, and can be done based on either the name, or the marketoGUID of the list.  To select the key you wish to use, pass either “dedupeFields” for name, or “idField” for marketoGUID in the deleteBy member of your request.  If unset, this will default to dedupeFields.  You can delete up to 300 records at a time.

In the case that a record cannot be found for a given key, the corresponding result item will have a status of “skipped” and a reason with a code and message describing the failure, as shown in the above example.

Managing Membership

Query Membership

Querying the membership of a named account list is simple, requiring only the id of the account list.  Optional parameters are:

  • “fields” a comma-separated list of fields to include in the response records
  • “nextPageToken” for paging through the result set
  • “batchSize” for specifying the number of records to return

If “fields” is unset, then “marketoGUID,” “name,” “createdAt”, and “updatedAt” will be returned.  “batchSize” has a maximum and default value of 300.

Add Members

Named accounts can easily be added to a Named Account List.  Accounts may only be added using their marketoGUID.  You can add up to 300 records at a time.

Remove Members

Removing records from an account list has a different path, but the same interface, requiring a marketoGUID for each record that you want to delete.  You can remove up to 300 records at a time.