Contact methods

createList(List list, BaseEntity baseEntity)

Create a new empty list associated with the identified entity.

Input

• list: externalId and type required
• baseEntity: externalId or internalId (for Campaign, Account or Enterprise)

Response

List (D)

Availability

Engage 7.3.3, Insight 1.3

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Argument supplied is null
• ATTRIBUTE_INVALID_CHAR – Contact list name contains invalid characters
• ATTRIBUTE_NULL – Attribute supplied is null
• ATTRIBUTE_TRUNCATED – Description for contact list is too long
• OBJECT_EXISTS – Object '%s' already exists
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• SYSTEM_LIMIT_EXCEEDED – maximum number of active lists exceeded

Notes

• The maximum number of lists simultaneously available is 500.
• Currently the list name associated with Suppression groups will be ignored.

createListUsingRuleSetGroup(Org org, List templateList, List sourceList, RuleSetGroup ruleSetGroup)

This will be used for creating virtual list. Its primary use would be creating new virtual list based on templateList using ruleSetGroup(group of rule sets of type filter) on source list (existing physical list).

Input

• org: orgType and internalId
• templateList: externalId and type
• sourceList:internalId or externalId
• ruleSetGroup:internalId or externalId

Response

List (D)

Availability

Engage 11.12

Errors returned

• ARG_NULL – Argument supplied is null
• ATTRIBUTE_INVALID_TYPE - Attribute is invalid type
• ATTRIBUTE_INVALID_Data - Attribute has invalid data
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_EXISTS – Object '%s' already exists
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• SYSTEM_LIMIT_EXCEEDED – maximum number of active lists exceeded

deleteList(List list)

Deletes a list.

Input

list: internalId

Response

NONE

Availability

Engage 7.5.0, Insight 1.3

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

Delete list can be called on a non-empty list (a list with contacts), which deletes the list and the associated contacts.

showList(List list)

Retrieves information about the supplied List.

Input

list: internalId

Response

List (D)

Availability

Engage 7.5.0

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

listLists(BaseEntity baseEntity, List sample)

Lists lists associated with the identified entity.

Input

• baseEntity: externalId or internalId, and if baseEntity is an Org, type must also be specified.
• sample: optional list object to narrow the returned set.

Response

List[] (K)

Availability

Engage 7.5.0, Insight 1.3

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – One of externalId or internalId must be non-null on the baseEntity
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• RESULT_TOO_LARGE – Result returned would be too large

Notes

• The maximum number of items returned using this method is 1,000.
• Only the attributes on the core entity are matched if a sample is supplied.
• The supplied BaseEntity must be a valid Account, Enterprise, or Campaign.

changeList(List list)

Updates fields/attributes of the supplied list.

Input

list : internalId + any fields to be changed

Response

List (D): updated list

Availability

Engage 7.5.0, Insight 1.3

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_INVALID_CHAR – Contact list name contains invalid characters
• ATTRIBUTE_NULL – Attribute supplied is null
• ATTRIBUTE_TRUNCATED – List name or description for contact list is too long
• NOT_SUPPORTED – Attempt to change the baseEntity associated with the list
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

You cannot change the baseEntity associated with a list. If this is attempted a NOT_SUPPORTED error will be returned.

addToListUsingContacts(List list, Contact[] contacts)

Appends the supplied contacts to the identified list.

Input

• list: internalId or all of externalId, entity, and type
• contacts: The set of contacts to be added to the list.

Response

Contact[] (D)

Availability

Engage 7.6.4, Insight 1.3

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ARG_TOO_LARGE – Invalid Data, argument '%s' exceeds allowed size
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

• The maximum number of contacts supported using this method is 10,000.
• If contacts are appended to a Suppression list, then active suppression is applied to any new or existing contact list associated with a subcampaign which uses that Suppression list.

addToListUsingStream(List list, DataHandler dataHandler, string mappingSpecification)

Appends the contacts from the supplied dataHandler to the identified list optionally using the associated mapping specification.

Input

• list: internalId or all of externalId, entity, and type
• dataHandler: a data stream containing a set of contacts to be imported
• mappingSpecification: Name of the specification file (previously loaded) used to transform the input file into normalized contacts

Response

Job (D)

Availability

Engage 7.8.0

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

• The dataHandler represents a stream of raw data being passed using MTOM.
• If the mappingSpecification is the empty string then the list must have a standard header (see Standard Contact header).
• If contacts are appended to a Suppression list, then active suppression is applied to any new or existing contact list associated with a subcampaign which uses that Suppression list.

addToListUsingString(List list, string contacts, string mappingSpecification)

Appends the contacts in the supplied string to the identified list optionally using the associated mapping specification.

Input

• list: internalId or all of externalId, entity, and type
• contacts: string containing contacts to be imported
• mappingSpecification: Name of the specification file (previously loaded) used to transform the input file into normalized contacts.

Response

Job (D)

Availability

Engage 7.3.3

Errors returned

• ARG_INVALID – Argument is invalid – reason '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ARG_TOO_LARGE – Invalid Data, argument '%s' exceeds allowed size
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

• The maximum length (in bytes) supported for the contacts string is 10,000,000.
• If the mappingSpecification is the empty string then the supplied string must have a standard Contact header (See Standard Contact header in the Appendix).
• If contacts are appended to a Suppression list, then active suppression is applied to any new or existing contact list associated with a subcampaign which uses that Suppression list.

addToListUsingList(List target, List source, string specification)

Appends the contacts in the source list to the identified target list, optionally using the associated specification to determine selection and mapping rules.

Input

• target: internalId or all of externalId, entity, and type
• source: internalId or all of externalId, entity, and type
• specification: JSON encoded set of parameters (name/value pairs)

Response

Job (D)

Availability

Engage 10.3.0

Errors returned

• ARG_INVALID – Argument is invalid – reason '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

• Target list can only be a either a standard list or a suppression list.
• If the source externalId is null then the list is assumed to come from Insight.
• Specification will be a set of name value pairs, for example, {"event":"MortgageAlert","OptInStatus":"Double","LastCommunication":"<10days"}

addToListUsingStreamWithRuleSetGroup(List targetList, DataHandler dataHandler, RuleSetGroup ruleSetGroup)

This will be used for importing stream of contacts into existing list with RuleSetGroup provided. Its primary use is to add to existing list after applying ruleSetGroup of type ‘Sequence’.

Input

• targetList: internalId or externalId and baseEntity(Org Type ‘Account’ and internalId of account)
• dataHandler: stream can be txt, csv, xls, gpg and .zip
• ruleSetGroup: internalId or externalId

Response

Job (D)

Availability

Engage 11.12

Errors returned

• ARG_INVALID - Argument is invalid – reason '%s'
• ARG_INVALID_TYPE - Argument type is invalid.
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• INTERNAL_ERROR - Internal error occurred.
• NOT_SUPPORTED - Operation not supported.

analyzeListUsingStream(Org org, DataHandler dataHandler, string mappingSpecification)

Analyze the contacts from the supplied dataHandler using the associated mapping specification associated with Org.

Input

• Org: internalId and type
• dataHandler: a data stream containing a set of contacts to be analyzed
• mappingSpecification: Name of the specification file (previously loaded) used to transform the input file into normalized contacts.

Response

AnalysisResult

Availability

Future

Errors returned

• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

• The dataHandler represents a stream of raw data being passed using MTOM.
• If the mappingSpecification is the empty string then the list must have a standard Contact header (see Standard Contact header).

deleteFromListUsingContacts(List list, Contact[] contacts)

Deletes the supplied contacts from the identified list.

Input

• list: internalId or all of externalId, entity, and type
• contacts: The set of contacts to be deleted from the list.

Response

NONE

Availability

Engage 7.6.4, Insight 1.3

Errors returned

• ARG_TOO_LARGE – Invalid Data, argument '%s' exceeds allowed size
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

The maximum number of contacts supported using this method is 10,000.

deleteFromListUsingString(List list, string contacts, string mappingSpecification)

Deletes the supplied contacts from the identified list optionally using the associated mapping specification.

Input

• list: internalId or all of externalId, entity, and type
• contacts: string containing contacts to be imported
• mappingSpecification: specification file used to transform input file into normalized contacts.

Response

NONE

Availability

Future

Errors returned

• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• ARG_TOO_LARGE – Invalid Data, argument '%s' exceeds allowed size

Notes

• The maximum length supported for the contacts string is 250,000.
• If the mappingSpecification is the empty string then the list must have a standard Contact header (see Standard Contact header).

addDeviceToContact(Contact contact, Device device)

Adds the supplied device to the identified contact.

Input

• contact: internalId
• device: The device to be added to the contact object.

Response

NONE

Availability

Insight 1.4

Errors returned

• OBJECT_NOT_EXISTS – Returned if the specified Contact does not exist
• OBJECT_EXISTS – Returned when index parameter references an existing contact device
• ARG_INVALID – Returned if the index specifies an invalid Contact Device

changeDeviceForContact(Contact contact, Device device)

Adds the supplied device to the identified contact.

Input

• contact: internalId
• device: The device to be added to the contact object.

Response

NONE

Availability

Insight 1.4

Errors returned

• ARG_INVALID – Argument is invalid – reason '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_INVALID - Attribute is invalid – reason '%s'
• ATTRIBUTE_INVALID_DATA - Attribute contains invalid data '%s'
• ATTRIBUTE_INVALID_FORMAT - Attribute '%s' has an invalid format
• ATTRIBUTE_INVALID_TYPE - Attribute is of invalid type '%s'
• ATTRIBUTE_NULL - Attribute '%s' must be non-null
• ATTRIBUTE_TOO_LARGE - Attribute '%s' exceeds allowed size
• ATTRIBUTE_TRUNCATED - Supplied attribute value too long and truncated
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

deleteDeviceFromContact(Contact contact, Device device)

Removes the device from the identified contact.

Input

• contact: internalId
• device: The device to be removed from the contact object

Response

NONE

Availability

Insight 1.4

Errors returned

• OBJECT_NOT_EXISTS – Returned if the specified Contact does not exist
• ARG_INVALID – Returned if the index specifies an invalid Contact Device

importContactsWithRuleSetGroup(Org org, List templateList, DataHandler dataHandler, RuleSetGroup ruleSetGroup)

This API is used to import contacts via stream in the Org provided with given templateList after applying ruleSetGroup.It returns Job State and part of job is newly created list in response.

Input

• org: internalId or externalId and type
• templateList: externalId and type
• dataHandler: stream can be txt, csv, xls, gpg and .zip
• ruleSetGroup: internalId or externalId

Response

Job (D)

Availability

Engage 11.12

Errors returned

• ARG_INVALID - Argument is invalid – reason '%s'
• ARG_INVALID_TYPE - Argument type is invalid.
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• INTERNAL_ERROR - Internal error occurred.
• NOT_SUPPORTED - Operation not supported.

importContactsUsingStream(Org org, List templateList, String mappingSpecification, DataHandler dataHandler)

This API imports contacts using stream as well as creates the list to which this stream needs to be imported to. It uses templateList to create list.

Input

• org: internalId or externalId
• templateList: externalId, type, baseEntity
• mappingSpecification: name of the specification
• dataHandler: stream

Response

Job[] (D)

Availability

Engage 11.12

Errors returned

• ARG_INVALID - Argument is invalid – reason '%s'
• ARG_INVALID_TYPE - Argument type is invalid.
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• ATTRIBUTE_TRUNCATED - Attribute provided is truncated.
• ATTRIBUTE_INVALID_CHAR - Attribute provided is invalid.
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• SYSTEM_LIMIT_EXCEEDED - Limit of number of entities within an account exceeded.
• OBJECT_EXISTS - Referenced object '%s' exist
• INTERNAL_ERROR - Internal error occurred.

listContactsAsContacts(List list, Contact sample)

Retrieves a list of contacts optionally matching the supplied Contact.

Input

• list: internalId or (externalId, parent, type).
• sample: Either externalId of contact or externalId of device[0] on contact or otherX attribute of contact.

Response

Contact[](D)

Availability

Engage 9.2

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• RESULT_TOO_LARGE – Result returned would be too large

Notes

• If sample is null – all contacts within List will be returned (subject to size constraint below).
• Only one attribute is searchable on the contact per invocation.
• Only non-deleted contacts will be searched/returned.
• The maximum number of items returned using this method is 1,000.

listContactsAsStream(List list)

Retrieves a list of contacts.

Input

list: internalId or (externalId, parent, type)

Response

MTOM streamed attachment

Availability

Engage 10.X

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• RESULT_TOO_LARGE – Result returned would be too large

Notes

• Only one attribute is searchable on the contact per invocation.
• Only non-deleted contacts will be searched/returned.

listContactsUsingContact(BaseEntity baseEntity, Contact sample)

Retrieves a list of contacts optionally matching the supplied Contact.

Input

• baseEntity: externalId or internalId, and if baseEntity is an Org, type must also be specified.
• sample: Either externalId of contact or externalId of device[0] on contact or otherX attribute of contact.

Response

Contact[](D)

Availability

Insight 1.3, Engage 10.1

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• RESULT_TOO_LARGE – Result returned would be too large

Notes

• If sample is null – all contact within List will be returned (subject to size constraint below).
• Only one attribute is searchable on the contact per invocation.
• Only non-deleted contacts will be searched/returned.
• The supplied BaseEntity must be a valid List, Enterprise or Account.
• The maximum number of items returned using this method is 1,000.

showContacts(Contact[] contacts)

Retrieves information about supplied contacts.

Input

contacts : internalID for each contact for which information is being sought

Response

Contact[] (D)

Availability

Insight 1.3

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ARG_TOO_LARGE – Invalid Data, argument '%s' exceeds allowed size
• ARG_INVALID – Argument is invalid – reason '%s'

Notes

The maximum number of contacts supported using this method is 100.

showDevices(Device[] devices)

Retrieves information about supplied devices.

Input

devices: externalID for each device for which information is being sought

Response

Device[] (D)

Availability

Engage 8.0

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ARG_TOO_LARGE – Invalid Data, argument '%s' exceeds allowed size
• ATTRIBUTE_INVALID_DATA – Invalid Data '%s
• ATTRIBUTE_NULL – Attribute supplied is null

Notes

The maximum number of devices supported using this method is 100.

addSubscriptionsToDevice(Contact contact, Device device, Subscription[] subscriptions

Creates new subscriptions associated with the specified device.

Input

• contact: internalId or externalId
• device: externalId
• subscriptions: event, channel, and subscriptionState (event: internalId or (externalId and owner))

Response

Subscription[] (D) ZZZZ

Availability

Insight 1.4

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_INVALID - Attribute is invalid – reason '%s'
• ATTRIBUTE_NULL - Attribute '%s' must be non-null

Notes

• This call is intended to support the Opt-in use-case. As such, allowed values for subscriptionState will be limited to Opted-In or Pending.
• Selected channel must be in list of supportedChannels of the event.
• Contact and Event must be associated with the same Org.
• Device must already be associated with the specified contact.
• subscriptionStateDate will be honored if it is provided. Otherwise, subscriptionStateDate will be set to the current system date.
• If externalId is used for contact, the Org will be inferred based on the owning Org of the subscription event.

deleteSubscriptionsFromDevice(Contact contact, Device device, Subscriptions[] subscriptions)

Deletes the supplied subscriptions from the specified device.

Input

• contact: internalId or externalId
• device: externalId
• subscriptions: internalId or (event and channel) for subscriptions to be deleted + subscriptionState, (event: internalId or (externalId and owner))

Response

NONE

Availability

Insight 1.4

Errors returned

• ARG_INVALID - Argument is invalid – reason '%s'
• ARG_NULL – Argument supplied is null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

• This call is intended to support the Opted-Out or Deactivated use-cases. As such, allowed values for subscriptionState will be limited to Opted-Out or Deactivated.
• Deletion is always a soft delete.
• If an existing subscription record does not exist, a new one will be created with the corresponding subscriptionState specified (this is necessary to support an explicit opt-out request).
• Contact and Event must be associated with the same Org.
• Device must already be associated with the specified contact.

subscriptionStateDate will be honored if it is provided. Otherwise, subscriptionStateDate will be set to the current system date.

• If externalId is used for contact, the Org will be inferred based on the owning Org of the subscription event.

changeSubscriptionForDevice(Contact contact, Device device, Subscription subscription)

Changes an existing subscription for the specified device.

Input

• contact: internalId or externalId
• device: externalId
• subscription: internalId or (event and channel) + any fields to be changed, (event: internalId or (externalId and owner))

Response

Subscription (D) Updated Subscription

Availability

Insight 1.4

Errors returned

• ARG_INVALID - Argument is invalid – reason '%s'
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• ATTRIBUTE_INVALID – Attribute is not valid
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

• This API call is primarily intended to support the second step in the double Opt-In use-case. As such, the only allowed value for subscriptionState will be Opted-In.
• The existing subscription record must have a current subscriptionState of Pending or Opted-In.
• Contact and Event must be associated with the same Org.
• Device must already be associated with the specified contact.
• subscriptionStateDate will be honored if it is provided and subscriptionState is changing from Pending to Opted-In. Otherwise, subscriptionStateDate will not be changed.
• If externalId is used for contact, the Org will be inferred based on the owning Org of the subscription event.
• Event and channel are considered immutable and cannot be changed using this API method.

listSubscriptions(Contact contact, Device device, Subscription sample)

Retrieves subscription information associated with the specified device, optionally matching the supplied subscription.

Input

• contact: internalId or externalId
• device: externalId
• sample: optional object to restrict the returned set. Only core attributes will be considered.

Response

Subscription[] (D)

Availability

Insight 1.4

Errors returned

• ARG_INVALID - Argument is invalid – reason '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

• Contact and Event must be associated with the same Org.
• Device must already be associated with the specified contact.

listSpecifications(Org org, MappingSpecification sampleSpec)

This API lists specification within an Org (Account or Enterprise). If sampleSpec provides a type, it will pull sepcifications of the type within an org.

Input

• org: internalId or externalId and type
• sampleSpec: type

Response

MappingSpecification[] (D)

Availability

Engage 11.12

Errors returned

• ARG_INVALID - Argument is invalid – reason '%s'
• ARG_INVALID_TYPE - Argument type is invalid.
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• INTERNAL_ERROR - Internal error occurred.

showContactsUsingRuleSetGroup(List sourceList, RuleSetGroup ruleSetGroup)

Primary purpose of this API is to preview contacts of physical list after ruleSetGroup applied through pagination.

Input

• sourceList:internalId or externalId and baseEntity(Org Type ‘Account’ and internalId of account)
• ruleSetGroup: internalId or externalId

Response

Contact[] (D)

Availability

Engage 11.12

Errors returned

• ARG_INVALID - Argument is invalid – reason '%s'
• ARG_INVALID_TYPE - Argument type is invalid.
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL – Attribute supplied is null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• INTERNAL_ERROR - Internal error occurred.

listUploadRequests (Org org, List sample)

Lists all upload requests within an account.Results should be filtered on the basis of sample list’s internal/externalId, type

Input

• org : internalId or (externalId, parent, type)
• sample: internalId or externalId and/or type

Response

UploadRequest (D)

Availability

Engage 12.4.0

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type ‘%s’
• ARG_NULL – Invalid Data, argument ‘%s’ must be non-null
• OBJECT_NOT_EXISTS – Referenced object ‘%s’ does not exist
• SYSTEM_LIMIT_EXCEEDED – maximum number of uploadRequest that can be fetched

showUploadRequestAsStream (UploadRequest uploadRequest, String uploadRequestArtifact)

Returns uploaded list artifact using given uploadRequest, artifact type like OriginalFile, RejectFile, MessageFile. This API returns data handler.

Input

• uploadRequest : internalId
• uploadRequestArtifact: Refer to enumeration UploadRequestArtifacts

Response

DataHandler

Availability

Engage 12.4.0

Errors returned

• ATTRIBUTE_INVALID_DATA – Attribute contains invalid data:‘%s’
• ATTRIBUTE_NULL – Attribute '%s' must be non-null
• ARG_NULL – Invalid Data, argument ‘%s’ must be non-null
• OBJECT_NOT_EXISTS – Referenced object ‘%s’ does not exist