Wicked Reports API
API Endpoint
https://api.wickedreports.comThe Wicked Reports API allows you to import or retrieve data stored into Wicked Reports.
Retrieving data could be useful for analysis and/or visualization in your own interface.
Getting Started ¶
Inserting data via the API’s is free for all Wicked Reports customers. However, in order to start using the Wicked Reports outbound API endpoint for data retrieval, you need to contact us so we can enable it for your account.
If the outbound API endpoints are not enabled for your account you are going to receive a 401 response with the following body:
{
"status": "error",
"message": "Outbound API not enabled for client."
}
Authorization
In order to authorize with the Wicked Reports Outbound API, you need to provide a header named apikey
having your API key
as a value.
Getting an API key
You can receive an API key by enabling the API for contact and/or orders in the "Authorizations" page of your dashboard. You will get a valid API key to use with the outbound API regardless of which API you decide to enable on the Authorizations screen.
After you have enabled either the contacts or the orders API, go on and copy the string below “Your API key” in the API card and provide it as a value of the apikey
header.
Here’s an example header:
apikey: HhpTUGLq9qM5CKzaOnYpO1fU1BItrCHg
Throttling
The Wicked Reports Outbound API will by default be throttling your requests to 120 requests per minute. In the response, you are going to find the following headers that will help you control your requests:
-
x-ratelimit-limit
- The total number of requests you can make. -
x-ratelimit-remaining
- The number of requests you have remaining. -
x-ratelimit-reset
- The time when your limit resets.
Inbound API endpoints
The inbound endpoints in the WickedReports API are used to insert new tracking data for analysis. These are available to all Wicked Reports customers but should be enabled first from the Authorization screen in the Wicked Reports dashboard. Read more in the “Authorization” section of this documentation.
When sending new data, have in mind that it might taked up to 30 minutes for new API data to appear inside the API Validator tool in the Wicked Reports dashboard.
Outbound API endpoints
The outbound API endpoints (the ones that are used to retrieve data) are available only to certain Wicked Reports customers who have them enabled.
This is a premium feature that must be enabled by Wicked’s Customer Success team.
Testing
Any of the inbound API endpoints accept a special header test
which accepts only 2 values - 0 or 1. If the test
header is present and with value of 1, it would mean you are not sending real data but rather one for test purposes.
If you want to run test calls, which will not affect you reporting but can be reviewed in the API Verification section of our application https://my.wickedreports.com/extras/api, you may include the test header as described below in the each of your test API request. If you do this, data passed via API will not be used by ANY reports inside your Wicked Reports account.
Contacts ¶
With the endpoints for contacts, you can retrieve information about your contacts in Wicked Reports.
List all contacts ¶
Headers
Content-Type: application/json
Body
{
"status": "success",
"results": [
{
"id": "AB-1234567",
"sourceId": "someIdInSourceSystem",
"sourceSystem": "test",
"email": "test@example.com",
"firstName": "Test",
"lastName": "Contact",
"LTV": 0,
"createDate": "2020-07-15T00:10:17.000Z",
"firstClick": {
"date": "2020-07-28T20:48:21.000Z",
"source": "some-source",
"medium": "some-medium",
"campaign": "some-campaign",
"content": "some-content",
"term": "some-term"
},
"firstOptin": {
"date": "2020-07-28T20:48:21.000Z",
"source": "some-source",
"medium": "some-medium",
"campaign": "some-campaign",
"content": "some-content",
"term": "some-term"
},
"reOptin": {
"date": "2020-07-30T00:01:43.000Z",
"source": "Email",
"medium": "email",
"campaign": "test-campaign",
"content": "test-content",
"term": "test-term"
},
"urlWicked": "https://my.wickedreports.com/extras/customerltv?report=newlead&id=AB-1234567",
"links": {
"clicks": {
"href": "/contacts/AB-1234567/clicks"
},
"orders": {
"href": "/contacts/AB-1234567/orders"
}
}
}
],
"page": 1,
"totalPages": 10,
"total": 1575,
"next": "9c783c753b7db667d9a5c96375514040"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"error"
],
"description": "The status of the request"
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"sourceSystem": {
"type": "string",
"description": "Source system of the contact or unknown in case the source cannot be determined."
},
"email": {
"type": "string"
},
"firstName": {
"type": [
"string",
"null"
]
},
"lastName": {
"type": [
"string",
"null"
]
},
"LTV": {
"type": "number"
},
"createDate": {
"type": [
"string",
"null"
]
},
"firstClick": {
"type": "object",
"properties": {
"date": {
"type": [
"string",
"null"
]
},
"source": {
"type": "string"
},
"medium": {
"type": "string"
},
"campaign": {
"type": "string"
},
"content": {
"type": "string"
},
"term": {
"type": "string"
}
}
},
"firstOptin": {
"type": "object",
"properties": {
"date": {
"type": [
"string",
"null"
]
},
"source": {
"type": "string"
},
"medium": {
"type": "string"
},
"campaign": {
"type": "string"
},
"content": {
"type": "string"
},
"term": {
"type": "string"
}
}
},
"reOptin": {
"type": "object",
"properties": {
"date": {
"type": [
"string",
"null"
],
"default": "null"
},
"source": {
"type": "string"
},
"medium": {
"type": "string"
},
"campaign": {
"type": "string"
},
"content": {
"type": "string"
},
"term": {
"type": "string"
}
},
"required": [
"date"
]
},
"urlWicked": {
"type": "string"
},
"links": {
"type": "object",
"properties": {
"clicks": {
"type": "object",
"properties": {
"href": {
"type": "string"
}
}
},
"orders": {
"type": "object",
"properties": {
"href": {
"type": "string"
}
}
}
},
"description": "Can be an empty object if the contact doesn't have any clicks"
}
},
"required": [
"id",
"sourceId",
"email",
"urlWicked"
]
}
},
"page": {
"type": "number"
},
"totalPages": {
"type": "number"
},
"total": {
"type": "number"
},
"next": {
"type": "string"
}
}
}
Headers
Content-Type: application/json
Body
{
"status": "error",
"message": "There was some problem with your request. You should review the parameters and try again."
}
List all contactsGET/contacts{?from,to,limit,next}
The contacts endpoint allows you to retrieve all contacts from your account. Note that you should always provide a time period in order to receive any data.
The links field in the response will contain an empty object, if the contact doesn’t have any clicks.
- from
string
(required) Example: 2020-07-01The start date to look for contacts. Format: YYYY-MM-DD
- to
string
(required) Example: 2020-07-02Date until which to look for contacts. Format: YYYY-MM-DD
- limit
number
(optional) Default: 100 Example: 1Number of contacts to return with a single call (max: 1000).
- next
string
(optional) Example: 9c783c753b7db667d9a5c96375514040A hash key for the next page of records. You can retrieve this key from the
next
value in the response of your first request.
Retrieve a single contact ¶
Headers
Content-Type: application/json
Body
{
"status": "success",
"result": {
"id": "AB-1234567",
"sourceId": "someIdInSourceSystem",
"sourceSystem": "test",
"email": "test@example.com",
"firstName": "Test",
"lastName": "Contact",
"LTV": 0,
"createDate": "2020-07-15T00:10:17.000Z",
"firstClick": {
"date": "2020-07-28T20:48:21.000Z",
"source": "some-source",
"medium": "some-medium",
"campaign": "some-campaign",
"content": "some-content",
"term": "some-term"
},
"firstOptin": {
"date": "2020-07-28T20:48:21.000Z",
"source": "some-source",
"medium": "some-medium",
"campaign": "some-campaign",
"content": "some-content",
"term": "some-term"
},
"reOptin": {
"date": "2020-07-30T00:01:43.000Z",
"source": "Email",
"medium": "email",
"campaign": "test-campaign",
"content": "test-content",
"term": "test-term"
},
"urlWicked": "https://my.wickedreports.com/extras/customerltv?report=newlead&id=AB-1234567",
"links": {
"clicks": {
"href": "/contacts/AB-1234567/clicks"
},
"orders": {
"href": "/contacts/AB-1234567/orders"
}
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"error"
]
},
"result": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"sourceSystem": {
"type": "string",
"description": "Source system of the contact or unknown in case the source cannot be determined."
},
"email": {
"type": "string"
},
"firstName": {
"type": [
"string",
"null"
]
},
"lastName": {
"type": [
"string",
"null"
]
},
"LTV": {
"type": "number"
},
"createDate": {
"type": [
"string",
"null"
]
},
"firstClick": {
"type": "object",
"properties": {
"date": {
"type": [
"string",
"null"
]
},
"source": {
"type": "string"
},
"medium": {
"type": "string"
},
"campaign": {
"type": "string"
},
"content": {
"type": "string"
},
"term": {
"type": "string"
}
}
},
"firstOptin": {
"type": "object",
"properties": {
"date": {
"type": [
"string",
"null"
]
},
"source": {
"type": "string"
},
"medium": {
"type": "string"
},
"campaign": {
"type": "string"
},
"content": {
"type": "string"
},
"term": {
"type": "string"
}
}
},
"reOptin": {
"type": "object",
"properties": {
"date": {
"type": [
"string",
"null"
],
"default": "null"
},
"source": {
"type": "string"
},
"medium": {
"type": "string"
},
"campaign": {
"type": "string"
},
"content": {
"type": "string"
},
"term": {
"type": "string"
}
},
"required": [
"date"
]
},
"urlWicked": {
"type": "string"
},
"links": {
"type": "object",
"properties": {
"clicks": {
"type": "object",
"properties": {
"href": {
"type": "string"
}
}
},
"orders": {
"type": "object",
"properties": {
"href": {
"type": "string"
}
}
}
},
"description": "Can be an empty object if the contact doesn't have any clicks"
}
},
"required": [
"id",
"sourceId",
"email",
"urlWicked"
]
}
}
}
Headers
Content-Type: application/json
Body
{
"status": "error",
"message": "Contact with id AB-1234567 not found."
}
Retrieve a single contactGET/contacts/{contactId}
You can also look for a contact using their email with this endpoint. Simply provide the email in the contactId
parameter like this: /contacts/test@example.com
.
The links field in the response will contain an empty object, if the contact doesn’t have any clicks.
- contactId
string
(required) Example: AB-1234567The id of the contact to retrieve. This could be either the internal id of the contact that you can find under the
id
property or thesourceId
which is the id in your source system. You can also use an email for this parameter.
Insert contacts ¶
Headers
Content-Type: application/json
Body
[
{
"SourceSystem": "ActiveCampaign",
"SourceID": 1234,
"CreateDate": "2016-06-15 10:12:13",
"Email": "test@example.com",
"FirstName": "John",
"LastName": "Doe",
"City": "Exampleville",
"State": "AZ",
"Country": "USA",
"IP_Address": "127.0.0.0",
"Phone": "00000000"
}
]
Headers
Content-Type: application/json
Body
{
"success": "Successfully inserted 1 / 1 records.",
"records": 1,
"totalRecords": 1,
"errors": []
}
Insert contactsPOST/contacts
This endpoint allows you to import your contact/lead data directly into Wicked Reports. This contact data may be currently stored in your CRM (contact management system), ESP (email service provider), or elsewhere.
You can insert from 1 to 1000 contacts with a single HTTP request.
The API does attempt to prevent duplicate inserts by email address. If we find a contact with an email address already added, we will ignore it.
The limit for the request body is 10 MB.
Contact object attributes
This endpoint accepts data sent as a JSON array of contacts with each contact having the following attributes:
Key | Type (max length) | Required | Description |
---|---|---|---|
SourceSystem | string(255) | yes | The name identifier of the source system where this contact came from. |
SourceID | string(500) | yes | Unique ID of the contact in the original system. |
CreateDate | datetime string | yes | Date & time when contact was created in the original system converted into UTC+0 timezone. (Format: “YYYY-MM-DD HH:MM:SS”) |
string(500) | yes | The email address of the contact. | |
FirstName | string(500) | no | First name of the lead/contact. |
LastName | string(500) | no | Last name of the lead/contact. |
City | string(500) | no | City of the contact. Even though, not required it’s important for the GEO and Predictive Behavior reports so you may want to supply it. |
State | string(500) | no | State from the address of the contact. Same as with city, needed for the GEO and Predictive Behavior reports. |
Country | string(500) | no | The country of the contacts. Required for GEO and Predictive Behavior reports. |
Phone | string(255) | no | A phone number of the contact. |
IP_Address | string(500) | no | The IP address of the contact when the email address was provided. |
Headers
Apart from the authorization apikey
header, the POST /contacts
endpoint also accepts the following headers:
Header | Description | Default |
---|---|---|
test |
Whether the inserted data is for test purposes only and it shouldn’t be taken into account. | 0 |
Clicks ¶
Retrieve the processed clicks from Wicked Reports.
List all clicks ¶
Headers
Content-Type: application/json
Body
{
"status": "success",
"results": [
{
"contactId": "test-contact-id",
"contactSourceId": "test-contact-source-id",
"date": "2020-07-01T00:01:43.000Z",
"email": "test@example.com",
"isFirstClick": false,
"isFirstOptin": false,
"isLastClick": false,
"isReOptin": true,
"source": "hubspot",
"utms": {
"source": "Email",
"medium": "email",
"campaign": "test-campaign",
"content": "test-content",
"term": "test-term"
},
"wickedid": "1234567",
"wickedsource": "test",
"trackingUrl": "https://example.com/tracking/url",
"links": {
"contact": {
"href": "/contacts/AB-1234567"
}
}
}
],
"page": 1,
"totalPages": 1,
"total": 1,
"next": "9c783c753b7db667d9a5c96375514040"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"error"
]
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"contactId": {
"type": "string",
"description": "The id of the contact in Wicked Reports."
},
"contactSourceId": {
"type": "string",
"description": "The id of the contact in your source system."
},
"date": {
"type": "string",
"description": "The date and time of the click."
},
"email": {
"type": [
"string",
"null"
],
"description": "The email of the contact this clicks belong to."
},
"isFirstClick": {
"type": "boolean"
},
"isFirstOptin": {
"type": "boolean"
},
"isLastClick": {
"type": "boolean"
},
"isReOptin": {
"type": "boolean"
},
"source": {
"type": "string"
},
"utms": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"medium": {
"type": "string"
},
"campaign": {
"type": "string"
},
"content": {
"type": "string"
},
"term": {
"type": "string"
}
}
},
"wickedid": {
"type": [
"string",
"null"
]
},
"wickedsource": {
"type": [
"string",
"null"
]
},
"trackingUrl": {
"type": "string"
},
"links": {
"type": "object",
"properties": {
"contact": {
"type": "object",
"properties": {
"href": {
"type": "string"
}
}
}
}
}
},
"required": [
"contactId",
"date"
]
}
},
"page": {
"type": "number"
},
"totalPages": {
"type": "number"
},
"total": {
"type": "number"
},
"next": {
"type": "string"
}
}
}
Headers
Content-Type: application/json
Body
{
"status": "error",
"message": "There was some problem with your request. You should review the parameters and try again."
}
List all clicksGET/clicks{?from,to,limit,next}
You can use this endpoint to retrieve all clicks associated with a contact within a certain timeframe. This endpoint will not be providing all clicks tracked, only clicks tracked to a specific contact.
The difference between parameters from
and to
cannot exceed 30 days.
Clicks that you’ve just submitted to the Wicked Reports API will not be returned by this endpoint. It might take up to 24 hours for these to appear in the response. You can use the API Verification tool in the Wicked Reports dashboard to validate data that you’ve recently sent.
- from
string
(required) Example: 2020-07-01The start date to look for clicks. Format: YYYY-MM-DD
- to
string
(required) Example: 2020-07-02The end date to look for clicks. Format: YYYY-MM-DD
- limit
integer
(optional) Default: 100 Example: 1Number of contacts to return with a single call (max: 1000).
- next
string
(optional) Example: 9c783c753b7db667d9a5c96375514040A hash key for the next page of records. You can retrieve this key from the
next
value in the response of your first request.
Retrieve the clicks of a specific contact ¶
Headers
Content-Type: application/json
Body
{
"status": "success",
"results": [
{
"contactId": "test-contact-id",
"contactSourceId": "test-contact-source-id",
"date": "2020-07-01T00:01:43.000Z",
"email": "test@example.com",
"isFirstClick": false,
"isFirstOptin": false,
"isLastClick": false,
"isReOptin": true,
"source": "hubspot",
"utms": {
"source": "Email",
"medium": "email",
"campaign": "test-campaign",
"content": "test-content",
"term": "test-term"
},
"wickedid": "1234567",
"wickedsource": "test",
"trackingUrl": "https://example.com/tracking/url",
"links": {
"contact": {
"href": "/contacts/AB-1234567"
}
}
}
],
"page": 1,
"totalPages": 1,
"total": 1,
"next": "9c783c753b7db667d9a5c96375514040"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"error"
]
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"contactId": {
"type": "string",
"description": "The id of the contact in Wicked Reports."
},
"contactSourceId": {
"type": "string",
"description": "The id of the contact in your source system."
},
"date": {
"type": "string",
"description": "The date and time of the click."
},
"email": {
"type": [
"string",
"null"
],
"description": "The email of the contact this clicks belong to."
},
"isFirstClick": {
"type": "boolean"
},
"isFirstOptin": {
"type": "boolean"
},
"isLastClick": {
"type": "boolean"
},
"isReOptin": {
"type": "boolean"
},
"source": {
"type": "string"
},
"utms": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"medium": {
"type": "string"
},
"campaign": {
"type": "string"
},
"content": {
"type": "string"
},
"term": {
"type": "string"
}
}
},
"wickedid": {
"type": [
"string",
"null"
]
},
"wickedsource": {
"type": [
"string",
"null"
]
},
"trackingUrl": {
"type": "string"
},
"links": {
"type": "object",
"properties": {
"contact": {
"type": "object",
"properties": {
"href": {
"type": "string"
}
}
}
}
}
},
"required": [
"contactId",
"date"
]
}
},
"page": {
"type": "number"
},
"totalPages": {
"type": "number"
},
"total": {
"type": "number"
},
"next": {
"type": "string"
}
}
}
Headers
Content-Type: application/json
Body
{
"status": "error",
"message": "There was some problem with your request. You should review the parameters and try again."
}
Retrieve the clicks of a specific contactGET/contacts/{contactId}/clicks{?from,to,limit,next}
contactId
- in this case is the unique ContactID generated by Wicked Reports and will not match the contactID from your CRM. This value can be seen in the contact history within the Customer LTV Report
You can use this endpoint to retrieve all clicks of a single contact within a specified time frame. The result will be a raw dataset of clicks. Wicked Reports uses proprietary logic and technology to determine which clicks are shown and reported inside our platform. Clicks returned from this endpoint will likely not match clicks displayed for this contact inside Wicked Reports.
The first 10,000 clicks of a single contact will be returned paginated. If the contact has more, you will have to use the from
and to
parameters to retrieve any clicks after the 10,000th. The difference between the parameters from
and to
cannot exceed 180 days in this case.
You can look for the orders of a single contact using their Wicked Reports Contact id
, sourceId
(contactID from your CRM) or email
with this endpoint. Simply provide the value in the contactId
parameter. An example with the email would be: /contacts/test@example.com/clicks
.
- contactId
string
(required) Example: test-contact-idThe id of the contact whose clicks you would like to receive. This could be either the internal id of the contact that you can find under the
contactId
property or thecontactSourceId
which is the id in your source system. You can also use an email for this parameter.- from
string
(optional) Example: 2020-07-01The start date to look for clicks. Format: YYYY-MM-DD
- to
string
(optional) Example: 2020-07-30The end date to look for clicks. Format: YYYY-MM-DD
- limit
number
(optional) Default: 100 Example: 100Maximum number of clicks to retrieve per page. (max: 1000)
- next
string
(optional) Example: 9c783c753b7db667d9a5c96375514040A hash key for the next page of records. You can retrieve this key from the
next
value in the response of your first request.
Insert clicks ¶
Headers
Content-Type: application/json
Body
[
{
"Email": "test@example.com",
"IP_Address": "127.0.0.1",
"Date_Time": "2021-05-17 00:15:23.123",
"Timezone": "UTC-0",
"TimeOffset": 3,
"Source": "docs",
"Campaign": "docs",
"Term": "docks-clicks-example",
"Medium": "docks-clicks",
"Content": "docks-clicks-request-body",
"OrderID": "test-order-id-1",
"ConversionType": "LAST_CLICK",
"WickedId": "",
"WickedSource": ""
}
]
Headers
Content-Type: application/json
Body
{
"success": "Successfully inserted 1 / 1 records.",
"records": 1,
"totalRecords": 1,
"errors": []
}
Headers
Content-Type: application/json
Body
[{
"Email": "test@example.com",
"IP_Address": "127.0.0.1",
"Date_Time": "",
"Timezone": "UTC-0",
"ConversionType": "LIVE_EVENT",
}]
Headers
Content-Type: application/json
Body
{
"success": "Successfully inserted 0 / 1 records.",
"records": 0,
"totalRecords": 1,
"errors": [
{
"item": {
"Email": "test@example.com",
"IP_Address": "127.0.0.1",
"Date_Time": "",
"Timezone": "UTC-0",
"ConversionType": "LIVE_EVENT",
},
"error": "Please provide a valid date and time or NOW. Valid datetime format: mm/dd/yyyy hh:mm am/pm"
}
]
}
Insert clicksPOST/clicks
The clicks endpoint allows you to import clicks you may have tracked yourself, directly into Wicked Reports. The clicks may help further define the customers journey that Wicked doesn’t already track using the widget. You should only use this if you have additional clicks that Wicked isn’t already tracking.
With 1 API call you can insert from 1 to 1000 click records at once.
Click object attributes The endpoint accepts a JSON array of clicks object, each with the following properties:
Key | Type (max length) | Required | Description |
---|---|---|---|
string(255) | yes | The email address of the executor of the click. | |
IP_Address | string(50) | no | The IP address where the click originated. |
Date_Time | datetime string | conditional | Date and time of the clicks. Required unless ConversionType value is NEW_LEAD or LAST_CLICK . |
Timezone | string(10) | yes | The timezone of the date time you’ve provided. Format: UTC+/-5 or UTC+/-05:00. |
TimeOffset | integer | no | The number of minutes to subtract from Date_Time. For example, if we know the clicks was tracked with a delay. |
Source | string(500) | no | The utm_source value that will be applied to the click. |
Campaign | string(500) | no | The utm_campaign value that will be applied to the click. |
Term | string(500) | no | The utm_term value that will be applied to the click. |
Medium | string(500) | no | The utm_medium value that will be applied to the click. |
Content | string(500) | no | The utm_content value that will be applied to the click. |
OrderID | string(500) | conditional | Required only for LAST_CLICK ConversionType. |
ConversionType | string(50) | yes | One of: LIVE_EVENT, NEW_LEAD, LAST_CLICK, REOPTIN, UNATTRIBUTED_CLICK, HUBSPOT_MEETING, MEETING, DOWNLOAD, WEBINAR, CHAT, LIVE_EVENT_DEMO, ATTRIBUTED_CLICK. You can learn more about each one here. |
WickedId | string(100) | conditional | If WickedId or WickedSource has a value, both fields must be filled in. |
WickedSource | string(100) | conditional | If WickedId or WickedSource has a value, both fields must be filled in. |
Orders ¶
Insert new data or retrieve existing data tracked orders by WickedReports.
The Wicked Reports API inbound orders endpoints allow you to import order, order items and product data directly into Wicked Reports. This data may be stored in your CRM (contact management system), shopping cart processed or stored by your payment gateway. Again, you should only use our Order API if we do not already directly integrate with your CRM or shopping cart currently.
List all orders ¶
Headers
Content-Type: application/json
Body
{
"status": "success",
"results": [
{
"id": "WR-order-id",
"sourceId": "test-source-order-id",
"sourceSystem": "stripe",
"date": "2020-06-18T06:00:27.000Z",
"attributions": {
"firstClick": {
"date": "2020-06-18T02:00:27",
"source": "direct",
"medium": "direct",
"campaign": "direct",
"content": "direct",
"term": "direct"
},
"firstOptin": {
"date": "2020-06-18T02:00:27",
"source": "direct",
"medium": "direct",
"campaign": "direct",
"content": "direct",
"term": "direct"
},
"reOptin": {
"date": "2020-06-18T02:00:27",
"source": "direct",
"medium": "direct",
"campaign": "direct",
"content": "direct",
"term": "direct"
},
"lastClick": {
"date": "2020-06-18T02:00:27",
"source": "direct",
"medium": "direct",
"campaign": "direct",
"content": "direct",
"term": "direct"
}
},
"contact": {
"id": "AB-1234567",
"sourceId": "test-source-contact-id",
"sourceSystem": "unknown",
"email": "test@example.com"
},
"products": [
{
"id": "test-product-id",
"name": "Awesome Subscription Plan",
"qty": 1,
"PPU": 79
}
],
"payments": [
{
"date": "2020-06-18T02:00:27",
"status": "APPROVED",
"amount": 79
}
],
"amount": 79,
"currency": "USD",
"subscriptionId": "test-subscription-1234567",
"links": {
"contact": {
"href": "/contacts/AB-1234567"
},
"clicks": {
"href": "/contacts/AB-1234567/clicks"
}
}
}
],
"page": 1,
"totalPages": 1,
"total": 1,
"next": "9c783c753b7db667d9a5c96375514040"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"error"
]
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"sourceSystem": {
"type": [
"string",
"null"
]
},
"date": {
"type": "string"
},
"attributions": {
"type": "object",
"properties": {
"firstClick": {
"type": "object",
"properties": {
"date": {
"type": "string",
"default": "null"
},
"source": {
"type": [
"string",
"null"
]
},
"medium": {
"type": [
"string",
"null"
]
},
"campaign": {
"type": [
"string",
"null"
]
},
"content": {
"type": [
"string",
"null"
]
},
"term": {
"type": [
"string",
"null"
]
}
}
},
"firstOptin": {
"type": "object",
"properties": {
"date": {
"type": "string",
"default": "null"
},
"source": {
"type": [
"string",
"null"
]
},
"medium": {
"type": [
"string",
"null"
]
},
"campaign": {
"type": [
"string",
"null"
]
},
"content": {
"type": [
"string",
"null"
]
},
"term": {
"type": [
"string",
"null"
]
}
}
},
"reOptin": {
"type": "object",
"properties": {
"date": {
"type": "string",
"default": "null"
},
"source": {
"type": [
"string",
"null"
]
},
"medium": {
"type": [
"string",
"null"
]
},
"campaign": {
"type": [
"string",
"null"
]
},
"content": {
"type": [
"string",
"null"
]
},
"term": {
"type": [
"string",
"null"
]
}
}
},
"lastClick": {
"type": "object",
"properties": {
"date": {
"type": "string",
"default": "null"
},
"source": {
"type": [
"string",
"null"
]
},
"medium": {
"type": [
"string",
"null"
]
},
"campaign": {
"type": [
"string",
"null"
]
},
"content": {
"type": [
"string",
"null"
]
},
"term": {
"type": [
"string",
"null"
]
}
}
}
}
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"sourceSystem": {
"type": "string"
},
"email": {
"type": "string"
}
},
"required": [
"id",
"sourceId"
]
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"qty": {
"type": "number"
},
"PPU": {
"type": "number"
}
}
}
},
"payments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"APPROVED",
"FAILED",
"REFUNDED",
"Partially Refunded",
"MANUAL"
]
},
"amount": {
"type": "number"
}
}
}
},
"amount": {
"type": "number"
},
"currency": {
"type": "string"
},
"subscriptionId": {
"type": "string"
},
"links": {
"type": "object",
"properties": {
"contact": {
"type": "object",
"properties": {
"href": {
"type": "string"
}
}
},
"clicks": {
"type": "object",
"properties": {
"href": {
"type": "string"
}
}
}
}
}
},
"required": [
"id",
"sourceId",
"date"
]
}
},
"page": {
"type": "number"
},
"totalPages": {
"type": "number"
},
"total": {
"type": "number"
},
"next": {
"type": "string"
}
}
}
List all ordersGET/orders{?from,to,limit,next}
Get all orders within a certain time frame.
- from
string
(required) Example: 2020-07-01The start date to look for orders. Format: YYYY-MM-DD
- to
string
(required) Example: 2020-07-02Date until which to look for orders. Format: YYYY-MM-DD
- limit
number
(optional) Default: 100 Example: 1Number of orders to return with a single call (max: 1000).
- next
string
(optional) Example: 9c783c753b7db667d9a5c96375514040A hash key for the next page of records. You can retrieve this key from the
next
value in the response of your first request.
Retrieve the orders of a single contact ¶
Headers
Content-Type: application/json
Body
{
"status": "success",
"results": [
{
"id": "WR-order-id",
"sourceId": "test-source-order-id",
"sourceSystem": "stripe",
"date": "2020-06-18T06:00:27.000Z",
"attributions": {
"firstClick": {
"date": "2020-06-18T02:00:27",
"source": "direct",
"medium": "direct",
"campaign": "direct",
"content": "direct",
"term": "direct"
},
"firstOptin": {
"date": "2020-06-18T02:00:27",
"source": "direct",
"medium": "direct",
"campaign": "direct",
"content": "direct",
"term": "direct"
},
"reOptin": {
"date": "2020-06-18T02:00:27",
"source": "direct",
"medium": "direct",
"campaign": "direct",
"content": "direct",
"term": "direct"
},
"lastClick": {
"date": "2020-06-18T02:00:27",
"source": "direct",
"medium": "direct",
"campaign": "direct",
"content": "direct",
"term": "direct"
}
},
"products": [
{
"id": "test-product-id",
"name": "Awesome Subscription Plan",
"qty": 1,
"PPU": 79
}
],
"payments": [
{
"date": "2020-06-18T02:00:27",
"status": "APPROVED",
"amount": 79
}
],
"amount": 79,
"currency": "USD",
"subscriptionId": "test-subscription-1234567",
"links": {
"contact": {
"href": "/contacts/AB-1234567"
},
"clicks": {
"href": "/contacts/AB-1234567/clicks"
}
}
}
],
"page": 1,
"totalPages": 1,
"total": 1,
"next": "9c783c753b7db667d9a5c96375514040"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"error"
]
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"sourceSystem": {
"type": [
"string",
"null"
]
},
"date": {
"type": "string"
},
"attributions": {
"type": "object",
"properties": {
"firstClick": {
"type": "object",
"properties": {
"date": {
"type": "string",
"default": "null"
},
"source": {
"type": [
"string",
"null"
]
},
"medium": {
"type": [
"string",
"null"
]
},
"campaign": {
"type": [
"string",
"null"
]
},
"content": {
"type": [
"string",
"null"
]
},
"term": {
"type": [
"string",
"null"
]
}
}
},
"firstOptin": {
"type": "object",
"properties": {
"date": {
"type": "string",
"default": "null"
},
"source": {
"type": [
"string",
"null"
]
},
"medium": {
"type": [
"string",
"null"
]
},
"campaign": {
"type": [
"string",
"null"
]
},
"content": {
"type": [
"string",
"null"
]
},
"term": {
"type": [
"string",
"null"
]
}
}
},
"reOptin": {
"type": "object",
"properties": {
"date": {
"type": "string",
"default": "null"
},
"source": {
"type": [
"string",
"null"
]
},
"medium": {
"type": [
"string",
"null"
]
},
"campaign": {
"type": [
"string",
"null"
]
},
"content": {
"type": [
"string",
"null"
]
},
"term": {
"type": [
"string",
"null"
]
}
}
},
"lastClick": {
"type": "object",
"properties": {
"date": {
"type": "string",
"default": "null"
},
"source": {
"type": [
"string",
"null"
]
},
"medium": {
"type": [
"string",
"null"
]
},
"campaign": {
"type": [
"string",
"null"
]
},
"content": {
"type": [
"string",
"null"
]
},
"term": {
"type": [
"string",
"null"
]
}
}
}
}
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"qty": {
"type": "number"
},
"PPU": {
"type": "number"
}
}
}
},
"payments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"APPROVED",
"FAILED",
"REFUNDED",
"Partially Refunded",
"MANUAL"
]
},
"amount": {
"type": "number"
}
}
}
},
"amount": {
"type": "number"
},
"currency": {
"type": "string"
},
"subscriptionId": {
"type": "string"
},
"links": {
"type": "object",
"properties": {
"contact": {
"type": "object",
"properties": {
"href": {
"type": "string"
}
}
},
"clicks": {
"type": "object",
"properties": {
"href": {
"type": "string"
}
}
}
}
}
},
"required": [
"id",
"sourceId",
"date"
]
}
},
"page": {
"type": "number"
},
"totalPages": {
"type": "number"
},
"total": {
"type": "number"
},
"next": {
"type": "string"
}
}
}
Retrieve the orders of a single contactGET/contacts/{contactId}/orders{?from,to,limit,next}
contactId
- in this case is the unique ContactID generated by Wicked Reports and will not match the contactID from your CRM. This value can be seen in the contact history within the Customer LTV Report
You can use this endpoint to request the orders of a single contact. The response format will be
similar to the one when getting all of the orders except that it will contain only the ones belonging to the
contact id specified and won’t have information about the contact. If you need detailed information about the contact
whose orders you are requesting, please check the contacts/{contactId}
endpoint above.
You can look for the orders of a single contact using their Wicked Reports Contact id
, sourceId
(contactID from your CRM) or email
with this endpoint. Simply provide the value in the contactId
parameter. An example with the email would be: /contacts/test@example.com/orders
.
Note that when you request the orders of a specific contact, each order object won’t contain information about the contact as it is with the listing of all orders.
- contactId
string
(required) Example: AB-1234567The id of the contact whose orders you would like to receive.
- from
string
(required) Example: 2020-07-01The start date to look for orders. Format: YYYY-MM-DD
- to
string
(required) Example: 2020-07-02Date until which to look for orders. Format: YYYY-MM-DD
- limit
number
(optional) Default: 100 Example: 1Number of orders to return with a single call (max: 1000).
- next
string
(optional) Example: 9c783c753b7db667d9a5c96375514040A hash key for the next page of records. You can retrieve this key from the
next
value in the response of your first request.
Insert orders ¶
Headers
Content-Type: application/json
Body
[{
"SourceSystem": "TestCart",
"SourceID": "test-order-id",
"CreateDate": "2021-05-17 15:28:33",
"ContactID": "test-contact",
"OrderTotal": 1099,
"Country": "US",
"City": "New York",
"State": "NY",
"IP_Address": "127.0.0.1",
"OrderItems": [{
OrderItemID: "test-order-item",
ProductID: "test-product-id",
Qty: 1,
PPU: 1099
}]
}]
Headers
Content-Type: application/json
Body
{
"success": "Successfully inserted 1 / 1 records",
"records": 1,
"totalRecords": 1,
"errors": []
}
Headers
Content-Type: application/json
Body
[
{
"SourceSystem": "TestCart",
"SourceID": "test-order-id",
"CreateDate": "2021-05-17 15:28:33",
"ContactID": "test-contact",
"OrderTotal": 1099,
"Country": "US",
"City": "New York",
"State": "NY",
"IP_Address": "127.0.0.1",
"OrderItems": [
{
"OrderItemID": "some-item-id",
"ProductID": "awesome-product",
"Qty": 1,
"PPU": 1099
}
],
"OrderPayments": [
{
"PaymentDate": "2021-05-17 15:28:33",
"Amount": 1099,
"Status": "APPROVED"
}
]
}
]
Headers
Content-Type: application/json
Body
{
"success": "Successfully inserted 1 / 1 records",
"records": 1,
"totalRecords": 1,
"errors": []
}
Insert ordersPOST/orders
Insert orders data into Wicked Reports. With this endpoint you can insert order information only or you can insert order items and order payment together with the order.
Warning: When inserting order items as part of an orders request as opposed to a separate /orderitems
call, the SourceID
attribute on order items needs to be substituted with the key OrderItemID
. Please refer to the “Insert orders with order items and payments” example request on the right.
Key | Type (max length) | Required | Description |
---|---|---|---|
SourceSystem | string(255) | yes | Name of the system where orders are coming from, may be any chosen string, must be used everywhere after, helps to identify source of orders, (e.g. ‘SamCart’, ‘Ultracart’, etc.) |
SourceID | string(500) | yes | Unique order id in the original system. |
CreateDate | string datetime | yes | order creation date and time converted into UTC+0 timezone. (Format: “YYYY-MM-DD HH:MM:SS”) |
ContactEmail | string(500) | conditional | RECOMMENDED over ContactID. Required IF SourceSystem is DIFFERENT than the system used for contacts. Should be sent if the order is to be sent to Facebook CAPI. |
ContactID | string(500) | conditional | Only used IF SourceSystem is the SAME as the system used for contacts. |
OrderTotal | decimal(18,2) | yes | Total amount of the order. |
OrderCurrency | string(3) | no | Three letter code of the currency if it’s different than USD. |
Country | string(255) | no | Country where the order originated from. Used in GEO reports, location info related to the customer of order. |
City | string(255) | no | City where the order originated from. Used in GEO reports, location info related to the customer of order. |
State | string(255) | no | If applicable, state where the order originated. Again, used in GEO reports, location info related to the customer of order. |
SubscriptionID | string(500) | no | Identifier of a subscription if the order is part of a recurring chain of orders. This needs to be a UNIQUE ID for each subscription to identify the chain of subscription payments made - including the initial order and all rebills. |
IP_Address | string(500) | no | The IP address from which the order originated. |
OrderItems | array[OrderItem] | no | An array of order items to associate with this order. The properties of an OrderItem are almost the same as described in the /orderitems call except for SourceID. SourceID is expected as OrderItemID with this request (SourceID -> OrderItemID). Please note the warning above and make sure to use OrderItemID instead of SourceID. |
OrderPayments | array[OrderPayment] | no | An array of order payments to associate with this order. |
Insert order items ¶
Headers
Content-Type: application/json
Body
[
{
"SourceSystem": "TestCart",
"SourceID": "some-item-id",
"OrderID": "test-order-id",
"ProductID": "awesome-product",
"Qty": 1,
"PPU": 1099
}
]
Headers
Content-Type: application/json
Body
{
"success": "Successfully inserted 1 / 1 records",
"records": 1,
"totalRecords": 1,
"errors": []
}
Insert order itemsPOST/orderitems
Add order items for a certain order to WickedReports.
Key | Type (max length) | Required | Description |
---|---|---|---|
SourceSystem | string(255) | yes | Name of the system where orders are coming from, may be any chosen string, must be used everywhere after, helps to identify source of orders, (e.g. ‘SamCart’, ‘Ultracart’, etc.) |
SourceID | string(500) | yes | Order item id in the original system. |
OrderID | string(500) | yes | ID of the related order in the original system. |
ProductID | string(500) | no | ID of related product in the original system, required if there is a need to connect the product with an order. |
Qty | integer | yes | Quantity of the order items. |
PPU | decimal(18,2) | yes | Price per product unit in the original system. |
Insert order payments ¶
Headers
Content-Type: application/json
Body
[
{
"SourceSystem": "TestCart",
"OrderID": "test-order-id",
"PaymentDate": "2021-05-17 15:28:33",
"Amount": 1099,
"Status": "APPROVED"
}
]
Headers
Content-Type: application/json
Body
{
"success": "Successfully inserted 1 / 1 records",
"records": 1,
"totalRecords": 1,
"errors": []
}
Insert order paymentsPOST/orderpayments
Use this endpoint to insert an array of order payments into Wicked Reports.
With one call, it is possible to insert from 1 up to 1000 order payments.
Key | Type (max length) | Required | Description |
---|---|---|---|
SourceSystem | string(255) | yes | name of the system where orders are coming from, may be any chosen string, must be used everywhere after, helps to identify source of orders, (e.g. SamCart , Ultracart , etc.) |
OrderID | string(100) | yes | ID of related order in the original system. |
PaymentDate | datetime string | yes | date and time of the payment, format: “YYYY-MM-DD HH:MM:SS” (Reminder, date must be in UTC TIME) |
Amount | decimal(18,2) | yes | Payment amount (amount should be positive, even if it’s a REFUNDED payment). |
Status | string | no | Payment status, allowed values APPROVED , FAILED , REFUNDED , PARTIALLY REFUNDED , if empty will be considered as APPROVED |
Insert products data ¶
Headers
Content-Type: application/json
Body
[
{
"SourceSystem": "TestCart",
"SourceID": "awesome-product",
"ProductName": "An Awesome Product to Buy",
"ProductPrice": 1099
}
]
Headers
Content-Type: application/json
Body
{
"success": "Successfully inserted 1 / 1 records",
"records": 1,
"totalRecords": 1,
"errors": []
}
Insert products dataPOST/products
Use this endpoint to insert/update an array of products into Wicked Reports.
With one call, it is possible to insert from 1 up to 1000 products.
NOTE: If an existing SourceID is passed in, we will perform an UPDATE on the ProductName and ProductPrice values in Wicked Reports
Key | Type (max length) | Required | Description |
---|---|---|---|
SourceSystem | string(255) | yes | name of the system where orders are coming from, may be any chosen string, must be used everywhere after, helps to identify source of orders, (e.g. ‘SamCart’, ‘Ultracart’, etc.) |
SourceID | string(500) | yes | product id in the original system |
ProductName | string(500) | yes | Name of the product. |
ProductPrice | decimal(18,2) | yes | Price of the product. |
Channels ¶
Retrieve channels from WickedReports.
List all channels ¶
Headers
Content-Type: application/json
Body
{
"status": "success",
"results": [
{
"channel": "Facebook",
"source": "",
"medium": "",
"campaignId": "",
"campaign": "",
"content": "",
"adGroupId": "",
"adId": "",
"term": "",
"adSetId": "",
"creativeId": "",
"ROAS": 0,
"avgOrderValue": "",
"date": "2021-05-01",
"costs": 757.58,
"revenue": 69114.02,
"attributedROI": 92.23,
"clicks": 136,
"newLeads": 1,
"reEngagedLeads": 1,
"subscriptionSales": 0,
"nonsubscriptionSales": 100,
"sales": 100,
"subscriptionRevenue": 0,
"nonSubscriptionRevenue": 0,
"newCustomerCount": 691,
"repeatCustomerCount": 0,
"customers": 691,
"totalCustomers": 691,
"CPL": 757.58,
"CPA": 757.58,
"CAC": 0,
"LTV": 0
}
],
"page": "1",
"totalPages": "1",
"total": "1",
"next": "9c783c753b7db667d9a5c96375514040"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"error"
]
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"channel": {
"type": "string"
},
"source": {
"type": "string"
},
"medium": {
"type": "string"
},
"campaignId": {
"type": "string"
},
"campaign": {
"type": "string"
},
"content": {
"type": "string"
},
"adGroupId": {
"type": "string"
},
"adId": {
"type": "string"
},
"term": {
"type": "string"
},
"adSetId": {
"type": "string"
},
"creativeId": {
"type": "string"
},
"ROAS": {
"type": "number"
},
"avgOrderValue": {
"type": "string"
},
"date": {
"type": "string"
},
"costs": {
"type": "number"
},
"revenue": {
"type": "number"
},
"attributedROI": {
"type": "number"
},
"clicks": {
"type": "number"
},
"newLeads": {
"type": "number"
},
"reEngagedLeads": {
"type": "number"
},
"subscriptionSales": {
"type": "number"
},
"nonsubscriptionSales": {
"type": "number"
},
"sales": {
"type": "number"
},
"subscriptionRevenue": {
"type": "number"
},
"nonSubscriptionRevenue": {
"type": "number"
},
"newCustomerCount": {
"type": "number"
},
"repeatCustomerCount": {
"type": "number"
},
"customers": {
"type": "number"
},
"totalCustomers": {
"type": "number"
},
"CPL": {
"type": "number"
},
"CPA": {
"type": "number"
},
"CAC": {
"type": "number"
},
"LTV": {
"type": "number"
}
},
"required": [
"channel",
"date"
]
}
},
"page": {
"type": "string"
},
"totalPages": {
"type": "string"
},
"total": {
"type": "string"
},
"next": {
"type": "string"
}
}
}
List all channelsGET/channels{?from,to,limit,next,level,rev,attr_model,channel,source,medium,campaign,content,term,campaignid,adsetid,adgroupid,async}
You can use this endpoint to get a list of all channels and their performance for a provided date range.
- from
string
(required) Example: 2021-05-01The start date of the channels data period. Format: YYYY-MM-DD
- to
string
(required) Example: 2021-05-02The end date of the channels data period. Format: YYYY-MM-DD
- limit
number
(optional) Default: 100 Example: 30Number of channels to return with a single call (max: 1000).
- next
string
(optional) Example: 9c783c753b7db667d9a5c96375514040A hash key for the next page of records. You can retrieve this key from the
next
value in the response of your first request.- Note that for the same set of parameters, the value of the
next
key would always be the same. However, every time you pass it in your request, you will get the next page of records.
- Note that for the same set of parameters, the value of the
- level
сhannel, сampaign, adset/adgroup, adname/keyword
(optional) Example: channellevel of data granularity, how data is grouped
- rev
gross, net
(optional) Default: net Example: gross- attr_model
linear, `full_impact`, `first_click`, `first_optin`, `reoptin`, `last_click`
(optional) Default: linear Example: linear- channel
'overall', 'google', 'facebook', 'ads', 'organic', 'tiktok', 'pinterest', 'snapchat', 'sms', 'etc.'
(optional) Example: overalloptional filter to show data only for specific channel
- source
string
(optional) Example: testoptional filter to show data only for specific utm_source
- medium
string
(optional) Example: ppcoptional filter to show data only for specific utm_medium
- campaign
string
(optional) Example: testoptional filter to show data only for specific utm_campaign
- content
string
(optional) Example: testoptional filter to show data only for specific utm_content
- term
string
(optional) Example: testoptional filter to show data only for specific term
- campaignid
string
(optional) Example: 12345678901111optional filter to show data only for specific campaign ID (applicable for Google Ads and Facebook Ads campaigns)
- adsetid
string
(optional) Example: 1234567890846optional filter to show data only for specific adset ID (applicable for Facebook Ads adsets)
- adgroupid
string
(optional) Example: 12345678951optional filter to show data only for specific adset ID (applicable for Google Ads adgroups)
- async
number
(optional) Example: 1optional parameter to remove the time restriction of an API. If provided, it’s value should be 1.
Marketing Data ¶
If you have marketing costs that you’d like entered into Wicked Reports that Wicked doesn’t have an integration with (SnapChat, Twitter, Bing, etc), you can send these costs using this endpoint.
Insert marketing data ¶
Headers
Content-Type: application/json
Body
[
{
"Date_Time": "2021-05-17 00:00:00",
"Source": "test_source",
"Medium": "test_medium",
"Campaign": "test_campaign",
"Content": "test_content",
"Term": "test_term",
"Clicks": 315,
"Cost": 95.37,
"AdId": "1234567",
"AccountId": "12345689abc-1",
"SourceSystem": "SourceSystem",
"LastUpdatedDate": "2021-05-17 23:15:23",
"ConversionCount": 5,
"ConversionValue": 200,
"AdStatus": "active",
"CampaignStatus": "active",
"AdGroupStatus": "active",
"AdSetStatus": "active",
"AdType": "Video",
"CampaignId": "123",
"AdGroupId": "test_group"
}
]
Headers
Content-Type: application/json
Body
{
"success": "Successfully inserted 1 / 1 records.",
"records": 1,
"totalRecords": 1,
"errors": []
}
Insert marketing dataPOST/marketing
Send marketing data to Wicked Reports.
Key | Type (max length) | Required | Description |
---|---|---|---|
Date_Time | datetime string | yes | The date time of the marketing data information. Format: YYYY-MM-DD 00:00:00. Please match timezone with your CRM/Shopping cart data timezone data if possible |
Source | string(500) | yes | The utm_source value. |
Medium | string(500) | no | The utm_medium value. |
Campaign | string(500) | no | The utm_campaign value. |
Content | string(500) | no | The utm_content value. |
Term | string(500) | no | The utm_term value. |
Clicks | integer | yes | The number of clicks that this marketing activity got. |
Cost | decimal(18,2) | yes | The cost associated with this marketing data. |
AdId | string | yes | The ad ID associated with this marketing data. |
AccountId | string | yes | The account ID associated with this marketing data. |
SourceSystem | string | no | System source value. |
LastUpdatedDate | datetime string | no | The latest date time of the update of marketing data information. |
ConversionCount | integer | no | How many conversions does the platform think this ad received. |
ConversionValue | integer | no | What is the conversion value the platform think this ad received. |
AdStatus | string | no | Ad status value (active/paused/etc). |
CampaignStatus | string | no | Campaign status (active/paused/etc). |
AdGroupStatus | string | no | Ad group status value (exclusive with AdSetStatus) (active/paused/etc). |
AdSetStatus | string | no | Ad set status value (exclusive with AdGroupStatus) (active/paused/etc). |
AdType | string | no | Ad type value (Video, Image). |
CampaignId | string | no | Campaign ID value. |
AdGroupId | string | no | Ad group ID value. |
Async outbound API endpoints ¶
For fetching output for the request check /results endpoint.
List all contacts ¶
Headers
Content-Type: application/json
Body
{
"status": "success",
"resultId": "cf0e618"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"error"
]
},
"resultId": {
"type": "string"
}
}
}
Headers
Content-Type: application/json
Body
{
"status": "error",
"message": "There was some problem with your request. You should review the parameters and try again."
}
List all contactsGET/async/contacts{?from,to}
The contacts endpoint allows you to retrieve all contacts from your account. Note that you should always provide a time period in order to receive any data.
The links field in the response will contain an empty object, if the contact doesn’t have any clicks.
- from
string
(required) Example: 2020-07-01The start date to look for contacts. Format: YYYY-MM-DD
- to
string
(required) Example: 2020-07-02Date until which to look for contacts. Format: YYYY-MM-DD
Retrieve a single contact ¶
Headers
Content-Type: application/json
Body
{
"status": "success",
"result": {
"id": "AB-1234567",
"sourceId": "someIdInSourceSystem",
"sourceSystem": "test",
"email": "test@example.com",
"firstName": "Test",
"lastName": "Contact",
"LTV": 0,
"createDate": "2020-07-15T00:10:17.000Z",
"firstClick": {
"date": "2020-07-28T20:48:21.000Z",
"source": "some-source",
"medium": "some-medium",
"campaign": "some-campaign",
"content": "some-content",
"term": "some-term"
},
"firstOptin": {
"date": "2020-07-28T20:48:21.000Z",
"source": "some-source",
"medium": "some-medium",
"campaign": "some-campaign",
"content": "some-content",
"term": "some-term"
},
"reOptin": {
"date": "2020-07-30T00:01:43.000Z",
"source": "Email",
"medium": "email",
"campaign": "test-campaign",
"content": "test-content",
"term": "test-term"
},
"urlWicked": "https://my.wickedreports.com/extras/customerltv?report=newlead&id=AB-1234567",
"links": {
"clicks": {
"href": "/contacts/AB-1234567/clicks"
},
"orders": {
"href": "/contacts/AB-1234567/orders"
}
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"error"
]
},
"result": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"sourceSystem": {
"type": "string",
"description": "Source system of the contact or unknown in case the source cannot be determined."
},
"email": {
"type": "string"
},
"firstName": {
"type": [
"string",
"null"
]
},
"lastName": {
"type": [
"string",
"null"
]
},
"LTV": {
"type": "number"
},
"createDate": {
"type": [
"string",
"null"
]
},
"firstClick": {
"type": "object",
"properties": {
"date": {
"type": [
"string",
"null"
]
},
"source": {
"type": "string"
},
"medium": {
"type": "string"
},
"campaign": {
"type": "string"
},
"content": {
"type": "string"
},
"term": {
"type": "string"
}
}
},
"firstOptin": {
"type": "object",
"properties": {
"date": {
"type": [
"string",
"null"
]
},
"source": {
"type": "string"
},
"medium": {
"type": "string"
},
"campaign": {
"type": "string"
},
"content": {
"type": "string"
},
"term": {
"type": "string"
}
}
},
"reOptin": {
"type": "object",
"properties": {
"date": {
"type": [
"string",
"null"
],
"default": "null"
},
"source": {
"type": "string"
},
"medium": {
"type": "string"
},
"campaign": {
"type": "string"
},
"content": {
"type": "string"
},
"term": {
"type": "string"
}
},
"required": [
"date"
]
},
"urlWicked": {
"type": "string"
},
"links": {
"type": "object",
"properties": {
"clicks": {
"type": "object",
"properties": {
"href": {
"type": "string"
}
}
},
"orders": {
"type": "object",
"properties": {
"href": {
"type": "string"
}
}
}
},
"description": "Can be an empty object if the contact doesn't have any clicks"
}
},
"required": [
"id",
"sourceId",
"email",
"urlWicked"
]
}
}
}
Headers
Content-Type: application/json
Body
{
"status": "error",
"message": "Contact with id AB-1234567 not found."
}
Retrieve a single contactGET/async/contacts/{contactId}
You can also look for a contact using their email with this endpoint. Simply provide the email in the contactId
parameter like this: /async/contacts/test@example.com
.
The links field in the response will contain an empty object, if the contact doesn’t have any clicks.
- contactId
string
(required) Example: AB-1234567The id of the contact to retrieve. This could be either the internal id of the contact that you can find under the
id
property or thesourceId
which is the id in your source system. You can also use an email for this parameter.
List all clicks ¶
Headers
Content-Type: application/json
Body
{
"status": "success",
"resultId": "cf0e618"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"error"
]
},
"resultId": {
"type": "string"
}
}
}
Headers
Content-Type: application/json
Body
{
"status": "error",
"message": "There was some problem with your request. You should review the parameters and try again."
}
List all clicksGET/async/clicks{?from,to}
You can use this endpoint to retrieve all clicks associated with a contact within a certain timeframe. This endpoint will not be providing all clicks tracked, only clicks tracked to a specific contact.
The difference between parameters from
and to
cannot exceed 30 days.
Clicks that you’ve just submitted to the Wicked Reports API will not be returned by this endpoint. It might take up to 24 hours for these to appear in the response. You can use the API Verification tool in the Wicked Reports dashboard to validate data that you’ve recently sent.
- from
string
(required) Example: 2020-07-01The start date to look for clicks. Format: YYYY-MM-DD
- to
string
(required) Example: 2020-07-02The end date to look for clicks. Format: YYYY-MM-DD
Retrieve the clicks of a specific contact ¶
Headers
Content-Type: application/json
Body
{
"status": "success",
"resultId": "cf0e618"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"error"
]
},
"resultId": {
"type": "string"
}
}
}
Headers
Content-Type: application/json
Body
{
"status": "error",
"message": "There was some problem with your request. You should review the parameters and try again."
}
Retrieve the clicks of a specific contactGET/async/clicks/{contactId}{?from,to}
contactId
- in this case is the unique ContactID generated by Wicked Reports and will not match the contactID from your CRM. This value can be seen in the contact history within the Customer LTV Report
You can use this endpoint to retrieve all clicks of a single contact within a specified time frame. The result will be a raw dataset of clicks. Wicked Reports uses proprietary logic and technology to determine which clicks are shown and reported inside our platform. Clicks returned from this endpoint will likely not match clicks displayed for this contact inside Wicked Reports.
The first 10,000 clicks of a single contact will be returned paginated. If the contact has more, you will have to use the from
and to
parameters to retrieve any clicks after the 10,000th. The difference between the parameters from
and to
cannot exceed 180 days in this case.
You can look for the orders of a single contact using their Wicked Reports Contact id
, sourceId
(contactID from your CRM) or email
with this endpoint. Simply provide the value in the contactId
parameter. An example with the email would be: /async/clicks/test@example.com
.
- contactId
string
(required) Example: test-contact-idThe id of the contact whose clicks you would like to receive. This could be either the internal id of the contact that you can find under the
contactId
property or thecontactSourceId
which is the id in your source system. You can also use an email for this parameter.- from
string
(optional) Example: 2020-07-01The start date to look for clicks. Format: YYYY-MM-DD
- to
string
(optional) Example: 2020-07-30The end date to look for clicks. Format: YYYY-MM-DD
List all orders ¶
Headers
Content-Type: application/json
Body
{
"status": "success",
"resultId": "cf0e618"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"error"
]
},
"resultId": {
"type": "string"
}
}
}
List all ordersGET/async/orders{?from,to}
Get all orders within a certain time frame.
- from
string
(required) Example: 2020-07-01The start date to look for orders. Format: YYYY-MM-DD
- to
string
(required) Example: 2020-07-02Date until which to look for orders. Format: YYYY-MM-DD
Retrieve the orders of a single contact ¶
Headers
Content-Type: application/json
Body
{
"status": "success",
"resultId": "cf0e618"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"error"
]
},
"resultId": {
"type": "string"
}
}
}
Retrieve the orders of a single contactGET/async/orders{contactId}{?from,to}
contactId
- in this case is the unique ContactID generated by Wicked Reports and will not match the contactID from your CRM. This value can be seen in the contact history within the Customer LTV Report
You can use this endpoint to request the orders of a single contact. The response format will be
similar to the one when getting all of the orders except that it will contain only the ones belonging to the
contact id specified and won’t have information about the contact. If you need detailed information about the contact
whose orders you are requesting, please check the /async/contacts/{contactId}
endpoint above.
You can look for the orders of a single contact using their Wicked Reports Contact id
, sourceId
(contactID from your CRM) or email
with this endpoint. Simply provide the value in the contactId
parameter. An example with the email would be: /async/orders/test@example.com
.
Note that when you request the orders of a specific contact, each order object won’t contain information about the contact as it is with the listing of all orders.
- contactId
string
(required) Example: AB-1234567The id of the contact whose orders you would like to receive.
- from
string
(required) Example: 2020-07-01The start date to look for orders. Format: YYYY-MM-DD
- to
string
(required) Example: 2020-07-02Date until which to look for orders. Format: YYYY-MM-DD
List all channels ¶
Headers
Content-Type: application/json
Body
{
"status": "success",
"resultId": "cf0e618"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"error"
]
},
"resultId": {
"type": "string"
}
}
}
List all channelsGET/async/channels{?from,to,level,rev,attr_model,channel,source,medium,campaign,content,term,campaignid,adsetid,adgroupid}
You can use this endpoint to get a list of all channels and their performance for a provided date range.
- from
string
(required) Example: 2021-05-01The start date of the channels data period. Format: YYYY-MM-DD
- to
string
(required) Example: 2021-05-02The end date of the channels data period. Format: YYYY-MM-DD
- level
сhannel, сampaign, adset/adgroup, adname/keyword
(optional) Example: channellevel of data granularity, how data is grouped
- rev
gross, net
(optional) Default: net Example: gross- attr_model
linear, `full_impact`, `first_click`, `first_optin`, `reoptin`, `last_click`
(optional) Default: linear Example: linear- channel
'overall', 'google', 'facebook', 'ads', 'organic', 'tiktok', 'pinterest', 'snapchat', 'sms', 'etc.'
(optional) Example: overalloptional filter to show data only for specific channel
- source
string
(optional) Example: testoptional filter to show data only for specific utm_source
- medium
string
(optional) Example: ppcoptional filter to show data only for specific utm_medium
- campaign
string
(optional) Example: testoptional filter to show data only for specific utm_campaign
- content
string
(optional) Example: testoptional filter to show data only for specific utm_content
- term
string
(optional) Example: testoptional filter to show data only for specific term
- campaignid
string
(optional) Example: 12345678901111optional filter to show data only for specific campaign ID (applicable for Google Ads and Facebook Ads campaigns)
- adsetid
string
(optional) Example: 1234567890846optional filter to show data only for specific adset ID (applicable for Facebook Ads adsets)
- adgroupid
string
(optional) Example: 12345678951optional filter to show data only for specific adset ID (applicable for Google Ads adgroups)
Get FunnelVision data ¶
Headers
Content-Type: application/json
Body
{
"status": "success",
"resultId": "cf0e618"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"error"
]
},
"resultId": {
"type": "string"
}
}
}
Get FunnelVision dataGET/async/funnelvision{?from,to,channel,source,medium,campaign,campaignId,content,term,adSetId,adGroupId,level,rev,ignoreOrganicClicks,revenueBreakdownMode,topOfFunnelWindowDefinition,middleOfFunnelDays,bottomOfFunnelDays,fbConfidenceScore}
You can use this endpoint to pull FunnelVision data for a provided date range.
- from
string
(required) Example: 2021-05-01The start date of the FunnelVision data period. Format: YYYY-MM-DD
- to
string
(required) Example: 2021-05-02The end date of the FunnelVision data period. Format: YYYY-MM-DD
- level
сhannel, сampaign, adset/adgroup, adname/keyword
(optional) Example: channellevel of data granularity, how data is grouped
- rev
gross, net
(optional) Default: net Example: gross- channel
'overall', 'google', 'facebook', 'ads', 'organic', 'tiktok', 'pinterest', 'snapchat', 'sms', 'etc.'
(optional) Example: overalloptional filter to show data only for specific channel
- source
string
(optional) Example: testoptional filter to show data only for specific utm_source
- medium
string
(optional) Example: ppcoptional filter to show data only for specific utm_medium
- campaign
string
(optional) Example: testoptional filter to show data only for specific utm_campaign
- content
string
(optional) Example: testoptional filter to show data only for specific utm_content
- term
string
(optional) Example: testoptional filter to show data only for specific term
- campaignId
string
(optional) Example: 12345678901111optional filter to show data only for specific campaign ID (applicable for Google Ads and Facebook Ads campaigns)
- adSetId
string
(optional) Example: 1234567890846optional filter to show data only for specific adset ID (applicable for Facebook Ads adsets)
- adGroupId
string
(optional) Example: 12345678951optional filter to show data only for specific adset ID (applicable for Google Ads adgroups)
- ignoreOrganicClicks
yes, no
(optional) Example: yesoptional filter to ignore organic clicks
- revenueBreakdownMode
full, linear
(optional) Example: fullrevenue breakdown mode value
- topOfFunnelWindowDefinition
contactCreation, firstClick
(optional) Example: contactCreationtop of funnel window definition value
- middleOfFunnelDays
number
(optional) Example: 20middle of funnel window definition value
- bottomOfFunnelDays
number
(optional) Example: 5bottom of funnel window definition value
- fbConfidenceScore
number
(optional) Example: 20facebook confidence score value
Fetch response for specific request ¶
Headers
Content-Type: application/json
Body
{
"status": "success",
"meta": {
"page": "2",
"pageResults": "1000",
"limit": "1000",
"next": true
},
"results": {
"id": "cf0e618",
"data": [
{
"channel": "Facebook",
"source": "",
"medium": "",
"campaignId": "",
"campaign": "",
"content": "",
"adGroupId": "",
"adId": "",
"term": "",
"adSetId": "",
"creativeId": "",
"ROAS": 0,
"avgOrderValue": "",
"date": "2021-05-01",
"costs": 757.58,
"revenue": 69114.02,
"attributedROI": 92.23,
"clicks": 136,
"newLeads": 1,
"reEngagedLeads": 1,
"subscriptionSales": 0,
"nonsubscriptionSales": 100,
"sales": 100,
"subscriptionRevenue": 0,
"nonSubscriptionRevenue": 0,
"newCustomerCount": 691,
"repeatCustomerCount": 0,
"customers": 691,
"totalCustomers": 691,
"CPL": 757.58,
"CPA": 757.58,
"CAC": 0,
"LTV": 0
}
]
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"error"
]
},
"meta": {
"type": "object",
"properties": {
"page": {
"type": "string"
},
"pageResults": {
"type": "string"
},
"limit": {
"type": "string"
},
"next": {
"type": "boolean"
}
}
},
"results": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"channel": {
"type": "string"
},
"source": {
"type": "string"
},
"medium": {
"type": "string"
},
"campaignId": {
"type": "string"
},
"campaign": {
"type": "string"
},
"content": {
"type": "string"
},
"adGroupId": {
"type": "string"
},
"adId": {
"type": "string"
},
"term": {
"type": "string"
},
"adSetId": {
"type": "string"
},
"creativeId": {
"type": "string"
},
"ROAS": {
"type": "number"
},
"avgOrderValue": {
"type": "string"
},
"date": {
"type": "string"
},
"costs": {
"type": "number"
},
"revenue": {
"type": "number"
},
"attributedROI": {
"type": "number"
},
"clicks": {
"type": "number"
},
"newLeads": {
"type": "number"
},
"reEngagedLeads": {
"type": "number"
},
"subscriptionSales": {
"type": "number"
},
"nonsubscriptionSales": {
"type": "number"
},
"sales": {
"type": "number"
},
"subscriptionRevenue": {
"type": "number"
},
"nonSubscriptionRevenue": {
"type": "number"
},
"newCustomerCount": {
"type": "number"
},
"repeatCustomerCount": {
"type": "number"
},
"customers": {
"type": "number"
},
"totalCustomers": {
"type": "number"
},
"CPL": {
"type": "number"
},
"CPA": {
"type": "number"
},
"CAC": {
"type": "number"
},
"LTV": {
"type": "number"
}
},
"required": [
"channel",
"date"
]
}
}
}
}
}
}
Fetch response for specific requestGET/results/{resultId}{?limit,next}
You can use this endpoint to get a list of all channels and their performance for a provided date range.
- resultId
string
(required) Example: cf0e618The id of the result to retrieve. This could be received from any outbound endpoint.
- limit
number
(optional) Default: 1000 Example: 1Number of orders to return with a single call (max: 1000).
- next
0, 1
(optional) Example: 1A number indicating whether you need to go to the next page or to the very first page. Pass 1 if you need the next page, and 0 if you do not need next. Passing 0 and omitting this field causes the same behaviour.
Generated by aglio on 29 Sep 2023