In This Section

Contact Activities (Events)

API Set Name: contactactivities

API Description and Functional Purpose:

The contactactivities collection contains all contact related activity such as opens, clicks, sends and any other user defined action. Contact activities are also referred to as "events".

Additional information:

  • Contactactivities are associated to the contact via the contact's primary key. The default primary key is the contact's email address.
  • A contact can have multiple contact activities documenting various action types.
  • Actions taken in an email or SMS message will automatically generate an activity record.
  • Users can also create custom event activities such as "browse", "order", "clicked", etc.
  • Custom event activities can be added and acted upon through contactactivities records in the Cordial database.
  • Contactactivity data will be stored for 18 months, after which it will be systematically purged.

Resource Associations:

The following resource collections are associated to this collection.

Collection Association
contacts Contacts are linked to their activities by their primary key.

POST /contactactivities

Method URI Path
POST /contactactivities
Creates a new contactactivity in the Cordial database using the appropriate JSON body.

Parameters

* Required

Parameter Type Description Example
*a string Defines an action such as an open or click, or any other defined action. The maximum length of the parameter is 40 characters.  browse
*email string Unique email address to identify and reference the contact. msmith@example.com
ats string The action timestamp for the action. If this is left blank the current date and time will be used. Date format is ISO 8601 standard.

2018-01-09 17:47:43
properties object An object to record additional attributes of an event.
Note that property keys consisting of numeric-only values (e.g. 57) or keys containing a "dot" (e.g. shoes.color) will be stripped.

{"propertyOne": 1,
"propertyTwo": 2}
Note: When a property value is passed, its data type (string, integer, etc.) will be recognized and searchable in the platform UI. If a different datatype is passed to an already recognized property, that new data will not be searchable in the UI. It is necessary to create a new property if the datatype is to be changed.

Example JSON Requests

The following will create a new contactactivities record for a user defined "browse" event.

{
	"a": "browse",
	"email": "msmith@example.com",
	"ats": "2018-01-09 17:47:43",
	"properties": {
		"category": "Shirts",
		"url": "http://example.com/shirts",
		"description": "A really cool khaki shirt.",
		"price": 9.99,
		"title": "Khaki Shirt"
	}
}

Example Request URIs

The following URI in conjunction with the JSON will perform the POST.

http://<path>/contactactivities

GET /contactactivities

Method URI Path
GET /contactactivities
Retrieves contactactivities from within the Cordial database.

It is possible to retrieve conactactivity records for all contacts or for a specific contact.

It is also possible to filter on the time period of the contactactivities, and by action, such as opens, clicks or any user defined actions. Options for time values include: lt, gt, lte, gte, between.start, between.end.

When retrieving a large amount of contactactivities in the response, it is also possible to apply per_page and page query string parameters to limit the count returned and page position.

GET v1/contactactivities is limited to retrieving a total of 10k records. If it necessary to retrieve more than 10k records, GET v2/contactactivities should be used. 

Parameters

* Required

Parameter Type Description Example
time string The action timestamp for the action. can be searched with modifiers (lt, gt, lte, gte, between.start, between.end). 2018-01-09 17:47:43
action string Can be click, open, message-sent, or any user defined actions. alarmTriggered
email string Unique email address to identify and reference the contact. msmith@example.com
sort_by string Column to sort by. ats
sort_dir string Direction to sort by, works in conjunction with sort_by. desc
page number Page number of results. 2
per_page number Number of results per page. 20
return_count boolean The number of records returned. The default is false. true

Note: Get /contactactivities can process a maximum of 10k records. For example, a request for 1k records per page will return records for pages 1 through 10 but it will not return records on the 11th page. If it is necessary to access more that 10k contact activity records, the POST /contactactivityexport API call should be used.

Example Request URIs

The following URI will retrieve all contactactivities.

http://<path>/contactactivities

The following URI will retrieve all contactactivities where the email is "msmith@example.com".

http://<path>/contactactivities?email=msmith%40example.com

The following URI will retrieve all contactactivities where the action is "browse".

http://<path>/contactactivities?action=browse

The following URI will retrieve all contactactivities where the action is "browse" and the email is "msmith@example.com".

http://<path>/contactactivities?action=browse&email=msmith%40example.com

The following URI will retrieve all contacts but only include the contactactivities that have occurred between a specified start date and end date.

http://<path>/contactactivities?time[between][start]=2018-01-01&time[between][end]=2018-01-03

The following URI will retrieve all contacts but only include the "open" contactactivities that have occurred between a specified start date and end date.

http://<path>/contactactivities?time[between][start]=2018-01-01&time[between][end]=2018-01-03&action=open

The following URI will retrieve all contactactivities starting from the third page grouping contactactivities by 10. For example, page 1 would have included the first 10, page 2 the second group of 10 and so on. Note: The default per_page value is 25.

http://<path>/contactactivities?page=3&per_page=10

The following URI will return a count of all contactactivities in the request:

http://<path>/contactactivities?return_count=true

 

Related articles

Comments

0 comments

Please sign in to leave a comment.