Do you want to followup the behaviour of your customers through the right app? Or create segments based on behaviour? With this integration you can retrieve all email, push, in-app, inbox and SMS activities on customer level by using our REST API.
To start using the REST API you also need the Oauth 2.0 App to be able to authenticate with the REST API.
Installation in the store
In the store you can easily activate the app. This will ensure that the REST API will be available for the specific brand.
The wizard contains only 1 step which is giving the financial data for invoices from Deployteq.
Oauth 2.0 app configuration
The analytics event API demands Oauth2.0 authentication based on Client Credentials. This can be configured through the Oauth 2.0 app in the store. Go to integrations > Apps and create a new app:
This will open a dialogue for setting up a new app connection. Fill in the form and confirm.
After confirmation the Client ID and the client secret will be shown only once, this information is required to set up the API connection.
The Client Credentials can be used to request a token from https://auth.clang.cloud/oauth2/token. Below an example how this looks in Postman.
Analytics Events REST API
With the Analytics API it is possible to call events between a preset start and enddate. You will be able to retrieve data from march 1st 2022 and you can retrieve data from the past with a maximum of 12 months.
{
"total_count": 36,
"_links": {
"current": "https://api.canopydeploy.net/analytics-events/events?filter%5Bdate_from%5D=2023-01-24&filter%5Bdate_to%5D=2023-01-25&limit=100&offset=0"
},
"data": [
{
"bounce_category": null,
"bounce_code": null,
"bounce_type": null,
"brand_id": 54,
"brand_name": "Deployteq Testomgeving",
"broadcast_event_sub_type": "CAMPAIGN",
"broadcast_event_type": "EMAIL",
"broadcast_id": 6631,
"broadcast_manual_options": {
"CustomerCount": 10,
"data": "Campagne mail"
},
"broadcast_metadata": {
"language": "nl",
"selectionId": "623862315"
},
"broadcast_timestamp": "2023-01-28T11:31:41+01:00",
"broadcast_type": "MAIL",
"campaign_id": 17,
"campaign_name": "Daily send",
"campaign_object_id": 3,
"content_id": 593,
"content_name": "Wekelijkse nieuwsbrief",
"customer_email_address": "angelovanderkleij@deployteq.com",
"customer_id": 103,
"email_address": "angelovanderkleij@deployteq.com",
"email_address_override": 0,
"email_domain": "deployteq.com",
"external_id": "42560",
"ip_address": null,
"link_id": null,
"machine_generated": false,
"mailing_type": "promotional mail",
"metric": "broadcasts",
"metric_id": 0,
"metric_timestamp": "2023-01-28T11:31:41+01:00",
"original_content_id": 528,
"original_new_content_id": 378,
"portal_id": 1746,
"portal_name": "Deployteq",
"subject": "Test email 2023-01-24",
"test_mailing": 0,
"ua_brand": null,
"ua_clientinfo_engine": null,
"ua_clientinfo_engine_version": null,
"ua_clientinfo_name": null,
"ua_clientinfo_short_name": null,
"ua_clientinfo_type": null,
"ua_clientinfo_version": null,
"ua_device": null,
"ua_model": null,
"ua_osinfo_name": null,
"ua_osinfo_platform": null,
"ua_osinfo_short_name": null,
"ua_osinfo_version": null,
"url": null,
"url_unrendered": null,
"uuid": "148a0d9b-e138-4b9b-89e3-3c37a8f5d53b"
},
{
"bounce_category": null,
"bounce_code": null,
"bounce_type": null,
"brand_id": 54,
"brand_name": "Deployteq Testomgeving",
"broadcast_event_sub_type": "CAMPAIGN",
"broadcast_event_type": "EMAIL",
"broadcast_id": 6631,
"broadcast_manual_options": {
"CustomerCount": 10,
"data": "Campagne mail"
},
"broadcast_metadata": {
"language": "nl",
"selectionId": "623862315"
},
"broadcast_timestamp": "2023-01-28T11:31:41+01:00",
"broadcast_type": "MAIL",
"campaign_id": 17,
"campaign_name": "Daily send",
"campaign_object_id": 3,
"content_id": 593,
"content_name": "Wekelijkse nieuwsbrief",
"customer_email_address": "angelovanderkleij@deployteq.com",
"customer_id": 103,
"email_address": "angelovanderkleij@deployteq.com",
"email_address_override": 0,
"email_domain": "deployteq.com",
"external_id": "42560",
"ip_address": "45.118.251.216",
"link_id": 24964,
"machine_generated": false,
"mailing_type": "",
"metric": "clicks",
"metric_id": 1374,
"metric_timestamp": "2023-01-28T22:10:36+01:00",
"original_content_id": 528,
"original_new_content_id": 378,
"portal_id": 1746,
"portal_name": "Deployteq",
"subject": "Test email 2023-01-24",
"test_mailing": 0,
"ua_brand": "Apple",
"ua_clientinfo_engine": "Blink",
"ua_clientinfo_engine_version": "",
"ua_clientinfo_name": "Chrome",
"ua_clientinfo_short_name": "CH",
"ua_clientinfo_type": "browser",
"ua_clientinfo_version": "109.0",
"ua_device": "desktop",
"ua_model": "",
"ua_osinfo_name": "Mac",
"ua_osinfo_platform": "",
"ua_osinfo_short_name": "MAC",
"ua_osinfo_version": "10.15",
"url": "{{viewurl}}",
"url_unrendered": "{{viewurl}}",
"uuid": "bd6bf1cd-3a55-4f5b-9f98-a5ec341e52dd"
},
{
"bounce_category": null,
"bounce_code": null,
"bounce_type": null,
"brand_id": 54,
"brand_name": "Deployteq Testomgeving",
"broadcast_event_sub_type": "CAMPAIGN",
"broadcast_event_type": "EMAIL",
"broadcast_id": 6631,
"broadcast_manual_options": {
"CustomerCount": 10,
"data": "Campagne mail"
},
"broadcast_metadata": {
"language": "nl",
"selectionId": "623862315"
},
"broadcast_timestamp": "2023-01-28T11:31:41+01:00",
"broadcast_type": "MAIL",
"campaign_id": 17,
"campaign_name": "Daily send",
"campaign_object_id": 3,
"content_id": 593,
"content_name": "Wekelijkse nieuwsbrief",
"customer_email_address": "angelovanderkleij@deployteq.com",
"customer_id": 103,
"email_address": "angelovanderkleij@deployteq.com",
"email_address_override": 0,
"email_domain": "deployteq.com",
"external_id": "42560",
"ip_address": "45.118.251.216",
"link_id": null,
"machine_generated": false,
"mailing_type": "",
"metric": "opens",
"metric_id": 1487,
"metric_timestamp": "2023-01-28T22:10:36+01:00",
"original_content_id": 528,
"original_new_content_id": 378,
"portal_id": 1746,
"portal_name": "Deployteq",
"subject": "Test email 2023-01-24",
"test_mailing": 0,
"ua_brand": "Apple",
"ua_clientinfo_engine": "Blink",
"ua_clientinfo_engine_version": "",
"ua_clientinfo_name": "Chrome",
"ua_clientinfo_short_name": "CH",
"ua_clientinfo_type": "browser",
"ua_clientinfo_version": "109.0",
"ua_device": "desktop",
"ua_model": "",
"ua_osinfo_name": "Mac",
"ua_osinfo_platform": "",
"ua_osinfo_short_name": "MAC",
"ua_osinfo_version": "10.15",
"url": null,
"url_unrendered": null,
"uuid": "766ef52a-4b54-4c38-9fa8-d4bdf9127fa5"
}
]
}Parameters
The following query parameters are supported in the endpoint;
Param | Mandatory | Description |
|---|---|---|
| filter[date_from] | Yes | The startdate of the events you want to retrieve from the API, with a maximum of 1 year in the past. |
| filter[date_to] | Yes | The Enddate of the events that you want to retrieve from the API. Format: YYYY-mm-dd |
| filter[metric] | No | The possibility to limit the respons to a specific metric.
|
| limit | No | The maximum amount of events that are shown in a response. Maximum: 1.000 |
| offset | No | The offset of the events collection that is retrieved. Default: 0 |
Pagination
The response of the eventsAPI always sends a ‘total_count’ of the found results. In the event that there are more events available besides the chosen limit, the element ‘_Links’ will be added to the endpoint for the current, last and next endpoint.
See the example below:
{
"total_count": 466,
"_links": {
"current": "https://api.canopydeploy.net/analytics-events/events?filter[date_from]=2023-01-01&filter[date_to]=2023-01-25&limit=100&offset=0",
"last": "https://api.canopydeploy.net/analytics-events/events?filter[date_from]=2023-01-01&filter[date_to]=2023-01-25&limit=100&offset=400",
"next": "https://api.canopydeploy.net/analytics-events/events?filter[date_from]=2023-01-01&filter[date_to]=2023-01-25&limit=100&offset=100"
},
"data": []
}Data fields
Below you will find examples of the data fields in the response of the events API
Field name | Description | Examples |
|---|---|---|
| bounce_category | The bounce category in case of a bounces metric | |
| bounce_code | The bounce code in case of a bounces metric | |
| bounce_type | The bounce type in case of a bounces metric | |
| brand_id | Numeric value of the brandid for which the events are retrieved. This value is unique per portal. | 54 |
| brand_name | The name of the brand, as set in the application | Deployteq Testomgeving |
| broadcast_event_sub_type | Sub type:
| CAMPAIGN |
| broadcast_event_type | Event type:
| |
| broadcast_id | Unique identification per portal of a email broadcast | 6631 |
| broadcast_manual_options | Broadcast variables which are defined for the entire selection, these variables can be defined in the content. For example: {{manual fied="Example"}} | { "CustomerCount": 10, "data": "Campagne mail" } |
| broadcast_metadata | Personal broadcast variables, these variables can be defined in the content. For example: {{$metadata['key'] = 'value'}} | { } |
| broadcast_timestamp | The timestamp (date and time) of the broadcast: YYYY-mm-ddTHH:mm:ss+Timezone | 2023-01-28T11:31:41+01:00 |
| broadcast_type | Broadcast type:
| |
| campaign_id | Unique ID of the broadcasting campaign. | 17 |
| campaign_name | The campaign name within the application | Daily send |
| campaign_object_id | The campaign object which is responsible for the broadcast, in case of a SINGLEMAIL the value will be 0 | 3 |
| content_id | Unique content ID in Deployteq * In the case of an email content, we would advise to use 'original_new_content_id' field to group data per content. | 593 |
| content_name | The Name of the email content that is used in the broadcast | Weekly Newsletter |
| customer_email_address | The email address of the contact for which the email is rendered, this does not have to be the receiver of the email if an override is set | angelovanderkleij@deployteq.com |
| customer_id | Brand unique ID for the contactrecord in Deployteq | 103 |
| email_address | The email address of the receiver of the email | angelovanderkleij@deployteq.com |
| email_address_override | This parameter lets you know if an override was set for the broadcast. A override can be set to test a broadcast. The email is rendered based on the selected contact. The broadcast eventually will be to the email address which is set as an override. 0 → No override 1 → Yes, an override is set. | 0 |
| email_domain | The domain of the receiving email address | deployteq.com |
| external_id | The standard systemfield externalid in which for example your own CRM ID or GUID is stored in. | 42560 |
| ip_address | The IP-address in which an open or clicks metric has taken place, other metrics the value for this will be set to null | |
| link_id | The Unique ID of a link in the broadcast. This is only filled on a clicks metric. | |
| machine_generated | A Boolean in which the status of an opens metric by a ISP (Machine generated) or an actual open by humans.
| false |
| mailing_type | Per brand there are a couple of standard mailing types predefined, which can be expanded with more mailingtypes. Per Broadcasts a mailingtype can be selected to segment the broadcasts | promotional mail |
| metric | The Event metric output that can be limited with filters. Possible metrics;
| broadcasts |
| metric_id | 0 | |
| metric_timestamp | The date- and time of when the metric was registered; YYYY-mm-ddTHH:mm:ss+Timezone | 2023-01-28T11:31:41+01:00 |
| original_content_id | ||
| original_new_content_id | The unique ID of an email content, which is also used in the interface when the content is opened. This ID can be used in your own reports to group the data per send content. | |
| portal_id | Unique Identification of the portal | 1746 |
| portal_name | Unique name of the portal | Deployteq |
| subject | Subject of the broadcast | Test email 2023-01-24 |
| test_mailing | The status of the "Test" checkmark which can be sett during configuration of the broadcast.
| 0 |
| ua_brand | Information from the device, OS and browser in case of a opens or clicks metric | Apple |
| ua_clientinfo_engine | Information from the device, OS and browser in case of a opens or clicks metric | Bink |
| ua_clientinfo_engine_version | Information from the device, OS and browser in case of a opens or clicks metric | |
| ua_clientinfo_name | Information from the device, OS and browser in case of a opens or clicks metric | Chrome |
| ua_clientinfo_short_name | Information from the device, OS and browser in case of a opens or clicks metric | CH |
| ua_clientinfo_type | Information from the device, OS and browser in case of a opens or clicks metric | browser |
| ua_clientinfo_version | Information from the device, OS and browser in case of a opens or clicks metric | 109.0 |
| ua_device | Information from the device, OS and browser in case of a opens or clicks metric | desktop |
| ua_model | Information from the device, OS and browser in case of a opens or clicks metric | |
| ua_osinfo_name | Information from the device, OS and browser in case of a opens or clicks metric | Mac |
| ua_osinfo_platform | Information from the device, OS and browser in case of a opens or clicks metric | |
| ua_osinfo_short_name | Information from the device, OS and browser in case of a opens or clicks metric | MAC |
| ua_osinfo_version | Information from the device, OS and browser in case of a opens or clicks metric | 10.15 |
| url | In the possible event of a clicks metric a personalised URL will be shown. | |
| url_unrendered | In the event of a clicks metric, the not renderd URL will be shown, this will probably contain smarty tags | |
| uuid | Unique GUID for the event | 148a0d9b-e138-4b9b-89e3-3c37a8f5d53b |
Limitations
The API has been limited to 50.000 requests per day and per brand.
Responses
The following status can be returned in the API:
HTTP statuscode | HTTP message |
|---|---|
200 | Successful request |
400 | Bad request |
401 | Unauthorized |
| 403 | Forbidden |
404 | Not found |
429 | Too Many Requests |
500 | Internal Server Error |
Response 429 - additional information
To ensure the stability of our API, we have implemented additional rate limiting on our infrastructure. This rate limiting applies to the maximum number of calls per IP address or token.
For the REST API, there are two types of rate limiting, both of which are explained below. Rate limiting is used to regulate traffic from external systems and protect the Deployteq platform from heavy or sudden loads on the REST API and Deployteq systems.
Type: Number of Connections per IP
- An IP address is allowed to establish a maximum of 20 connections per Deployteq proxy. The 21st connection will simply be rejected. Currently, there are four Deployteq proxies in operation, which in practice means that a single IP can establish a maximum of (4 * 20) 80 connections simultaneously. This rate limit is rarely reached but is in place for additional security.
Type: Number of Calls per Token or IP Address
- A token is allowed to make a maximum of 25 simultaneous calls. This limit comes with a burst allowance, meaning that when the 25th call is reached, you can continue to send calls. An additional 100 requests beyond the initial 25 are accepted but processed at a rate of up to 25 at a time. If the number of calls in the queue exceeds 100, you will receive a 429 error. In addition to the 100, 400 calls can be submitted simultaneously. These are accepted but processed at a rate of up to 100 at a time.
Retrieving Checkpoint information
In addition to getting information regarding your broadcasts it is also possible to get information about checkpoint activity via the checkpoints endpoint.
{
"total_count": 1,
"_links": {
"current": "https://api.deployteq.net/analytics-events/checkpoints?filter%5Bcustomer_id%5D=1&filter%5Bdate_from%5D=2019-01-01&filter%5Bdate_to%5D=2019-01-02&limit=1&offset=0"
},
"data": [
{
"brand_id": 1,
"campaign_id": 1,
"checkpoint_name": "test",
"checkpoint_value": 1,
"customer_id": 1,
"portal_id": 1,
"timestamp": "2019-01-01T00:00:00+01:00",
"uuid": "417ddc5d-e556-4d27-95dd-a34d84e46a50"
}
]
}Checkpoint parameters
To further specify your results you have access to the following parameters:
| Param | Mandatory | Description |
|---|---|---|
| filter[date_from] | Yes | The startdate of the events you want to retrieve from the API, with a maximum of 1 year in the past. |
| filter[date_to] | Yes | The enddate of the events that you want to retrieve from the API. Format: YYYY-mm-dd |
| filter[checkpoint_name] | No | The name of the checkpoint as defined in the campaign object. |
| filter[campaign_id] | No | The ID of the campaign where the checkpoint is placed. |
| filter[customer_id] | No | The ID of the CRM record that passed through checkpoints. |
| filter[uuid] | No | The GUID for the triggering of the checkpoint |
Checkpoint data fields
In the checkpoints endpoint you will be able to retrieve the following data fields:
| Field name | Description | Example |
|---|---|---|
| brand_id | Numeric value of the Brand ID for which the events are retrieved. This value is unique per portal. | 1 |
| campaign_id | Unique ID of the campaign where the checkpoint is located. | 1 |
| checkpoint_name | The name of the checkpoint. | Succes |
| customer_id | When applicable, the ID of the customer that triggered the checkpoint. | 1 |
| portal_id | Unique Identification of the portal | 1 |
| timestamp | The date- and time of when the metric was registered; YYYY-mm-ddTHH:mm:ss+Timezone | 2024-03-04T00:00:00+01:00 |
| uuid | Unique GUID for the triggering of the checkpoint | 417ddc5d-e556-4d27-95dd-a34d84e46a50 |