API Set Name: contactactivities
API Description and Functional Purpose:
The contactactivities collection contains all contact related activity such as opens, clicks, sends or 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 |
| 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, |
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: When retrieving a large amount of contactactivities in the response, it is also possible to apply 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 |
| 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
Comments
0 comments
Please sign in to leave a comment.