How can we help?

Overview

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.

API set name: contactactivities

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 your 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.

Authentication

Cordial's core APIs use https Basic Authentication (BA). From within the Cordial platform, you can generate an encoded API key for your account and use it for authorization.

• Learn more about Cordial API authentication here

Resource associations

The following resource collections are associated to this collection.

Methods, parameters, examples

• POST/v2/contactactivities
• GET/v2/contactivities

POST/v2/contactactivities

• Parameters
• Example JSON request
• Example request URL

* Required

The following will create a new contact activity record for a user-defined "browse" event.

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

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

httpss://<path>/v2/contactactivities

GET/v2/contactactivities

• Parameters
• Retrieval limits
• Example request URLs

* Required

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 URL with the paging token to query the next batch. The paging URL will appear as the first JSON object in your results when there are more records to show.

"paging": {
    "token": "5bbbbb56c4605038b4567",
    "next": "https://<path>/v2/contactactivities?per_page=10000&return_count=false&__paging_token=5bbbbb56c4605038b4567"
  }

The paging token is not compatible with GET/v2/contactactivities endpoint. To page through more than 10,000 records using GET/v2/contactactivities, multiple queries must be made with manually adjusted parameters for each.

We recommend using POST/v2/contactactivityexport for exporting larger batches of contact activities.

The following URL will retrieve all contact activities.

httpss://<path>/v2/contactactivities

The following URL will retrieve all contact activities where the email address msmith@example.com is the contact identifier.

httpss://<path>/v2/contactactivities?email=msmith@example.com

The following URL will retrieve all contact activities where the action is browse.

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

The following URL will retrieve all contact activities where the action is browse and email address mrsmith@example.com is the contact identifier.

httpss://<path>/v2/contactactivities?action=browse&email=msmith@example.com

The following URL will retrieve all contacts but only include the contact activities that have occurred between the specified start date and end date.

httpss://<path>/v2/contactactivities?time[between][start]=2025-01-01&time[between][end]=2025-01-03

The following URL will retrieve all contacts but only include the open contact activities that have occurred between the specified start date and end date.

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

The following URL will retrieve all contact activities starting from the third 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.

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

The following URL will return a count of all contact activities in the request:

httpss://<path>/v2/contactactivities?return_count=true

Error responses

The Cordial API will return an error object with an errorKey and message if there is a problem with an API call. Below is a list of errors specific to the Contact Activities API endpoint, along with suggested modifications to resolve each error. If you receive an error from the Jobs API endpoint that is not listed in this table, it is likely recorded within the Global API error responses page.