API Set Name: contactactivities
API Description and Functional Purpose:
The contact activities collection contains all contact-related activities such as opens, clicks, sends and any other custom actions you create. Contact activities are also referred to as "events".
Additional information:
- Contact activities are associated to the contact via the contact's primary or secondary identifier keys. Default primary and secondary contact identifier keys can be configured uniquely for each Cordial account based on the client's data infrastructure.
- A contact can have multiple contact activities documenting various action types.
- Actions taken within a message (reserved actions) will automatically generate an activity record. These include:
- message-sent
- open
- click
- optout
- bounce
- complaint
- pageview
- message-stopped
- You can also create custom event activities such as "browse", "order", "cart", etc.
- Custom event activities can be added and acted upon through contact activities records in the Cordial database.
- Contact activity 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 or secondary identifier key(s). |
POST /contactactivities
Method | URI Path |
---|---|
POST | /contactactivities |
Creates a new contact activity in the Cordial database using the appropriate JSON body. |
Parameters
* Required
Parameter | Type | Description | Example |
---|---|---|---|
*a | string | Defines a custom action you wish to create such as browse, order, cart, or any other custom action. The maximum length of the parameter is 40 characters. Note: reserved actions cannot be added via the POST method. | browse |
*contact identifier | string | Unique primary or secondary contact identifier key/value pair to look up and reference the contact. | email@example.com, ID1234, 16198880000 |
ats | string | Action timestamp. If undefined, the current date and time will be used. Date format is ISO 8601 standard. |
2018-01-09 17:47:43 |
properties | object | An object of additional event attributes. The default maximum number of properties an event can have is 1,000. 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, |
Example JSON requests
The following will create a new contact activity 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 contact activities from the Cordial database.
It is possible to retrieve contact activity records for all contacts or a specific contact. It is also possible to filter based on date and time the contact activity occurred and by action names such as opens, clicks or any user-defined action. Options for time values include: When retrieving a large number of contact activities, it is possible to apply |
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 |
contact identifier | string | Unique contact identifier value to look up and reference the contact. | email@example.com, ID1234, 16198880000 |
sort_by | string | Column to sort by. | ats |
sort_dir | string | Direction to sort by. Works in conjunction with sort_by. | desc |
page | number | Specify the page number. | 2 |
per_page | number | Number of results per page. | 20 |
return_count | boolean | The number of records returned. Default is false. | true |
Paging and retrieval limits
The GET /contactactivities endpoint can retrieve up to 10,000 records at a time. You can request all 10,000 records on a single page and use the provided URI with the paging token to query the next batch. The paging URI will appear as the first JSON object in your results when there are more records to show.
"paging": { "token": "5bbbbb56c4605038b4567", "next": "http://<path>/v2/contactactivities?per_page=10000&return_count=false&__paging_token=5bbbbb56c4605038b4567" }
Example request URIs
The following URI will retrieve all contact activities.
http://<path>/contactactivities
The following URI will retrieve all contact activities where the email address "msmith@example.com" is the contact identifier.
http://<path>/contactactivities?email=msmith@example.com
The following URI will retrieve all contact activities where the action is "browse".
http://<path>/contactactivities?action=browse
The following URI will retrieve all contact activities where the action is "browse" and email address "msmith@example.com" is the contact identifier.
http://<path>/contactactivities?action=browse&email=msmith@example.com
The following URI will retrieve all contacts but only include the contact activities that have occurred between the 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" contact activities that have occurred between the 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 contact activities starting from the 3rd page and grouping contact activities by 10 per page. 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 contact activities in the request:
http://<path>/contactactivities?return_count=true
Comments
1 comment
This is for version one of the API, as the example has param: page=3; In v2 that is replace with the '__paging_token=########'
It would be great if you clearly showed which version of API is documented on this page somewhere.
Article is closed for comments.