Wicked Reports API

API Endpoint
https://api.wickedreports.com

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

You can find additional instructions on enabling the API as a data source in the video at the bottom of this help article.

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 Auhtorization 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

GET https://api.wickedreports.com/contacts?from=2020-07-01&to=2020-07-02&limit=1&next=9c783c753b7db667d9a5c96375514040
Responses200400
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 contacts
GET/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.

URI Parameters
HideShow
from
string (required) Example: 2020-07-01

The start date to look for contacts. Format: YYYY-MM-DD

to
string (required) Example: 2020-07-02

Date until which to look for contacts. Format: YYYY-MM-DD

limit
number (optional) Default: 100 Example: 1

Number of contacts to return with a single call (max: 1000).

next
string (optional) Example: 9c783c753b7db667d9a5c96375514040

A 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

GET https://api.wickedreports.com/contacts/AB-1234567
Responses200404
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 contact
GET/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.

URI Parameters
HideShow
contactId
string (required) Example: AB-1234567

The 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 the sourceId which is the id in your source system. You can also use an email for this parameter.

Insert contacts

POST https://api.wickedreports.com/contacts
RequestsInsert new contacts with JSON
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"
  }
]
Responses200
Headers
Content-Type: application/json
Body
{
  "success": "Successfully inserted 1 / 1 records.",
  "records": 1,
  "totalRecords": 1,
  "errors": []
}

Insert contacts
POST/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 in UTC timezone. (Format: “YYYY-MM-DD HH:MM:SS”)
Email 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 autorization 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

GET https://api.wickedreports.com/clicks?from=2020-07-01&to=2020-07-02&limit=1&next=9c783c753b7db667d9a5c96375514040
Responses200400
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 clicks
GET/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.

URI Parameters
HideShow
from
string (required) Example: 2020-07-01

The start date to look for clicks. Format: YYYY-MM-DD

to
string (required) Example: 2020-07-02

The end date to look for clicks. Format: YYYY-MM-DD

limit
integer (optional) Default: 100 Example: 1

Number of contacts to return with a single call (max: 1000).

next
string (optional) Example: 9c783c753b7db667d9a5c96375514040

A 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

GET https://api.wickedreports.com/contacts/test-contact-id/clicks?from=2020-07-01&to=2020-07-30&limit=100&next=9c783c753b7db667d9a5c96375514040
Responses200400
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 contact
GET/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.

URI Parameters
HideShow
contactId
string (required) Example: test-contact-id

The 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 the contactSourceId which is the id in your source system. You can also use an email for this parameter.

from
string (optional) Example: 2020-07-01

The start date to look for clicks. Format: YYYY-MM-DD

to
string (optional) Example: 2020-07-30

The end date to look for clicks. Format: YYYY-MM-DD

limit
number (optional) Default: 100 Example: 100

Maximum number of clicks to retrieve per page. (max: 1000)

next
string (optional) Example: 9c783c753b7db667d9a5c96375514040

A 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

POST https://api.wickedreports.com/clicks
RequestsInsert clickTry inserting click with invalid data
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": ""
  }
]
Responses200
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",
}]
Responses200
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 clicks
POST/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
Email string(255) yes The email address of the executor of the click.
IP_Address string(50) yes 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

GET https://api.wickedreports.com/orders?from=2020-07-01&to=2020-07-02&limit=1&next=9c783c753b7db667d9a5c96375514040
Responses200
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 orders
GET/orders{?from,to,limit,next}

Get all orders within a certain time frame.

URI Parameters
HideShow
from
string (required) Example: 2020-07-01

The start date to look for orders. Format: YYYY-MM-DD

to
string (required) Example: 2020-07-02

Date until which to look for orders. Format: YYYY-MM-DD

limit
number (optional) Default: 100 Example: 1

Number of orders to return with a single call (max: 1000).

next
string (optional) Example: 9c783c753b7db667d9a5c96375514040

A 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

GET https://api.wickedreports.com/contacts/AB-1234567/orders?from=2020-07-01&to=2020-07-02&limit=1&next=9c783c753b7db667d9a5c96375514040
Responses200
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 contact
GET/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.

URI Parameters
HideShow
contactId
string (required) Example: AB-1234567

The id of the contact whose orders you would like to receive.

from
string (required) Example: 2020-07-01

The start date to look for orders. Format: YYYY-MM-DD

to
string (required) Example: 2020-07-02

Date until which to look for orders. Format: YYYY-MM-DD

limit
number (optional) Default: 100 Example: 1

Number of orders to return with a single call (max: 1000).

next
string (optional) Example: 9c783c753b7db667d9a5c96375514040

A 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

POST https://api.wickedreports.com/orders
RequestsInsert orders only with JSONInsert orders with order items and payments
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
    }]
}]
Responses200
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"
      }
    ]
  }
]
Responses200
Headers
Content-Type: application/json
Body
{
  "success": "Successfully inserted 1 / 1 records",
  "records": 1,
  "totalRecords": 1,
  "errors": []
}

Insert orders
POST/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, format: “YYYY-MM-DD HH:MM:SS” (Reminder, date must be in UTC TIME)
ContactID string(500) conditional IF SourceSystem is the SAME as system used for contacts.
ContactEmail string(500) conditional IF SourceSystem is DIFFERENT than 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

POST https://api.wickedreports.com/orderitems
RequestsInsert order item
Headers
Content-Type: application/json
Body
[
  {
    "SourceSystem": "TestCart",
    "SourceID": "some-item-id",
    "OrderID": "test-order-id",
    "ProductID": "awesome-product",
    "Qty": 1,
    "PPU": 1099
  }
]
Responses200
Headers
Content-Type: application/json
Body
{
  "success": "Successfully inserted 1 / 1 records",
  "records": 1,
  "totalRecords": 1,
  "errors": []
}

Insert order items
POST/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.
Qty integer yes Quantity of the order items.
PPU decimal(18,2) yes Price per product unit in the original system.

Insert order payments

POST https://api.wickedreports.com/orderpayments
RequestsInsert order payment
Headers
Content-Type: application/json
Body
[
  {
    "SourceSystem": "TestCart",
    "OrderID": "test-order-id",
    "PaymentDate": "2021-05-17 15:28:33",
    "Amount": 1099,
    "Status": "APPROVED"
  }
]
Responses200
Headers
Content-Type: application/json
Body
{
  "success": "Successfully inserted 1 / 1 records",
  "records": 1,
  "totalRecords": 1,
  "errors": []
}

Insert order payments
POST/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

POST https://api.wickedreports.com/products
RequestsInsert product
Headers
Content-Type: application/json
Body
[
  {
    "SourceSystem": "TestCart",
    "SourceID": "awesome-product",
    "ProductName": "An Awesome Product to Buy",
    "ProductPrice": 1099
  }
]
Responses200
Headers
Content-Type: application/json
Body
{
  "success": "Successfully inserted 1 / 1 records",
  "records": 1,
  "totalRecords": 1,
  "errors": []
}

Insert products data
POST/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

GET https://api.wickedreports.com/channels?from=2021-05-01&to=2021-05-02&limit=30&next=9c783c753b7db667d9a5c96375514040&level=channel&rev=gross&attr_model=linear&channel=overall&source=test&medium=ppc&campaign=test&content=test&term=test&campaignid=12345678901111&adsetid=1234567890846&adgroupid=12345678951
Responses200
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 channels
GET/channels{?from,to,limit,next,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.

URI Parameters
HideShow
from
string (required) Example: 2021-05-01

The start date of the channels data period. Format: YYYY-MM-DD

to
string (required) Example: 2021-05-02

The end date of the channels data period. Format: YYYY-MM-DD

limit
number (optional) Default: 100 Example: 30

Number of channels to return with a single call (max: 1000).

next
string (optional) Example: 9c783c753b7db667d9a5c96375514040

A 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.
level
сhannel, сampaign, adset/adgroup, adname/keyword (optional) Example: channel

level 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

Attribution model

channel
'overall', 'google', 'facebook', 'ads', 'organic', 'tiktok', 'pinterest', 'snapchat', 'etc.' (optional) Example: overall

optional filter to show data only for specific channel

source
string (optional) Example: test

optional filter to show data only for specific utm_source

medium
string (optional) Example: ppc

optional filter to show data only for specific utm_medium

campaign
string (optional) Example: test

optional filter to show data only for specific utm_campaign

content
string (optional) Example: test

optional filter to show data only for specific utm_content

term
string (optional) Example: test

optional filter to show data only for specific term

campaignid
string (optional) Example: 12345678901111

optional filter to show data only for specific campaign ID (applicable for Google Ads and Facebook Ads campaigns)

adsetid
string (optional) Example: 1234567890846

optional filter to show data only for specific adset ID (applicable for Facebook Ads adsets)

adgroupid
string (optional) Example: 12345678951

optional filter to show data only for specific adset ID (applicable for Google Ads adgroups)

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

POST https://api.wickedreports.com/marketing
RequestsSubmit marketing data to Wicked Reports.
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"
  }
]
Responses200
Headers
Content-Type: application/json
Body
{
  "success": "Successfully inserted 1 / 1 records.",
  "records": 1,
  "totalRecords": 1,
  "errors": []
}

Insert marketing data
POST/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) no 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.

Latest

Get latest inserted record

GET https://api.wickedreports.com/latest?sourcesystem=ActiveCampaign&datatype=contacts&sortby=createdate&order=desc&offset=&like=
Responses200
Headers
Content-Type: application/json
Body
{
  "SourceSystem": "ActiveCampaign",
  "SourceID": "1234",
  "LoadDate": "2016-06-15T13:09:24.166Z",
  "CreateDate": "2016-06-15T10:12:13.000Z",
  "Email": "test@example.com",
  "FirstName": "John",
  "LastName": "Doe",
  "City": "Exampleville",
  "State": "AZ",
  "Country": "USA",
  "IP_Address": "127.0.0.0",
  "LatestOptinDate": null
}

Get latest inserted record
GET/latest{?sourcesystem,datatype,sortby,order,offset,like}

The /latest endpoint in Wicked Reports API is used together with the inbound API endpoints to check for what was the last inserted contact/order/orderitem/payment/product to understand from where to continue import if it was discrete in time.

The call returns the request object (contact, order, etc.) with the latest object CreateDate (or importdate, depending on your sortby value).

URI Parameters
HideShow
sourcesystem
string (required) Example: ActiveCampaign

As indicated above, the SourceSystem helps Wicked Reports know where this data is stored. You will need to match the exact text you used on import.

datatype
string (required) Example: contacts

To get last contact inserted should be contacts, to get last order should be orders,To get last orderitem should be orderitems; to get last payment should be payments; to get last product should be products.

sortby
createdate, importdate (optional) Example: createdate

Specifies sorting of records to get latest, ONLY valid values are ‘createdate’ and ‘importdate’. Default is ‘createdate’. For products, we sort by ‘createdate’ and “SourceID”.

order
asc,desc (optional) Example: desc

Specified sort order of records to get latest; by default desc, possible asc

offset
boolean (optional) Default: 0 

Possible values: 1 or 0; default: 0; if set to 1, the latest endpoint will return under theoffset field in a JSON format the number of unique records that have already been sent to the API for the specified sourcesystem and datatype; with offset set to 1, timezone, sortby and order parameters are ignored.

like
boolean (optional) Default: 0 

Possible values are 0 and 1; default: 0; instructs the API to use wildcard query for the sourcesystem and match any source system that starts with the specified sourcesystem. (e.g. with like=1 and sourceystem=AWeber, the /latest query will search for records with any source system that starts with AWeber such as AWeber-123, AWeberTest, etc.).

Generated by aglio on 30 Jun 2022