Skip to content
Go to wickedreports.com
  • There are no suggestions because the search field is empty.

Wicked Reports API Documentation

Everything you need to know to integrate with Wicked Reports using our APIs.

How to get API Support

API Support Team

For help building your API, please email support@wickedreports.com. They will place you in contact with our API Support Team.

 Inbound API

Many of the most popular Ad Platforms, CRMs, and Shopping Carts are natively integrated with Wicked Reports. However, there are still some situations where you'll find a Native Integration is unavailable and you need an alternative option, such as our Inbound API, to integrate.

The Inbound API can be used to send Wicked Reports Clicks, Leads, Order, and Marketing Costs. To get started with the Inbound API, follow the steps below.
 

Want to use your reports before the API is complete? - Import CSV files.

While you're working on building your API connection, you can manually import your cost, contact, or order data using CSV files. This ensures your data stays up-to-date, without interruption, and allows you to start analyzing your reports today. The sooner you import, the sooner you can can analyze your performance.

 Step 1 - Generate Your API Key
  1. Go to the Authorizations Page inside of your Wicked Reports account.
  2. Enable the API widget to access your API Key.
    Note: You can use the Contact or Order API widget to generate the API Key, they are the same key.

  3. Use your API Key as the value for the apikey header.

Step 2 - Select your Inbound API Endpoints

  • Clicks API Endpoint
    This API Endpoint allows you to import any clicks, that you have manually tracked, directly into Wicked Reports. These are clicks that may help further define the customer's journey. You should only use this if you have additional clicks that Wicked isn't already tracking.
  • Contacts API Endpoint
    This API Endpoint allows you to import your contact data directly into Wicked Reports. This contact data may be currently stored in your CRM (contact management system), ESP (email service provider), or elsewhere.
  • Orders API Endpoints: 
    • Orders API Endpoint
      This API Endpoint allows you to import orders, order items, and order payments directly into Wicked Reports. This data may be stored in your CRM, shopping cart, or stored by your payment gateway.
    • Order Items API Endpoint
      This API Endpoint allows you to import order items after your order has already been created. If you want to view your products in your reports, then you'll need to include a product ID when inserting your order items. If this product ID matches a product that's been inserted, then you'll be able to see your product in the reports.
    • Products Data API Endpoint
      This API Endpoint allows you to import Product Data directly into Wicked Reports. To view your products within the reports, you'll need to make sure your products have been inserted. If this product matches a corresponding order item Product ID, then you'll be able to see this product within your reports.
    • Order Payments API Endpoint
      This API Endpoint allows you to import Order Payments. Order payments are necessary if you want to process additional information on the status of the order, such as whether or not it was approved, failed, refunded, or partially refunded. This will provide a more accurate picture of your Net Revenue within the reports.
  • Marketing API Endpoint (aka Other Marketing Costs)
    This API Endpoint allows you to import the marketing details of your ads, such as costs, clicks, and UTMs, directly into Wicked Reports. This marketing data may currently be stored in your Ad Platform.

Step 3 -  Build your API (Please follow the tips & tricks)

Please follow these Tips & Tricks:

  1. Only new, unique data
    Send only new, unique data to Wicked. Do not resend historic data to Wicked Reports. For example, if your API runs daily, send only yesterday’s data—not the last year of data each time. Sending duplicate data will cause performance issues (i.e. delayed processing).
  2. Limit to 1,000 rows per request (10MB)
    Limit to 1,000 rows per request (10MB) for all endpoints. Sending delayed and/or large requests will cause performance issues (i.e. delayed processing).
Optional: Wicked Inbound API SDK
Consider using the Wicked Inbound API SDK. It'll help speed up the Inbound API setup process and make it easier for us to support you. Our SDK includes a readme with instructions on how to install it into your project, how to authenticate, how to perform API calls, API call examples, unit tests, and how to easily convert time zones.

Step 4 - Test your API

Please run a test before enabling your API.
It's the fastest & easiest way to verify your data.

To run a test, please include the test header in each of your test API requests. This ensures the test data will not impact or be used in your reports.

All 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 the value of 1, then it would mean you are not sending real data but rather data for test purposes. This test data can then be viewed by using the API Verification Tool within your Wicked account. The API Verification Tool is where you can find and review all the data that you've passed through into Wicked Reports.
 

Step 5 - Verify Your Test Data

Our API Support Team can help you with this step. Please email support@wickedreports.com for assistance.

Order Data
If you're sending order data, then use the Order Validation Checklist as a helpful list for validating the accuracy of your data.

Contact Data
If you're sending contact data, then use the Contact Validation Checklist as a helpful list for validating the accuracy of your data. 

Step 6 - Go Live!

After testing and verifying your Inbound API data, and all tests pass, then you are ready to go live. Remove the test header to start sending real data into Wicked Reports!

Step 7 - Send a one-time, historic import (Last 365 Days)

Sending a one-time upload of the last 365 days of data allows Wicked Reports to accurately classify New vs. Repeat Customers and Leads, and gives you instant access to full LTV insights and Cohort Reports.

 

Outbound API

Wicked Reports has a wonderful data CSV export feature that allows you to pull channel data directly from your ROI & FunnelVision Reports. However, there are still some use cases where you may want to extract your data via API. That's where the Outbound API comes into play.

The Outbound API allows you to pull your data directly out of Wicked Reports and use it however you see fit. It can be used in Looker Studio, BigQuery, or any other platforms that can consume JSON files.

The Outbound API is used to retrieve Wicked Reports clicks, leads, and order data. However, it's most often used to retrieve the performance data, down to the ad level, of specific channels. 


Outbound API Setup Steps

The purpose of this section is to provide you with the high-level process to extracting your data from Wicked reports via API. 

  1. Generate your unique API Key in the Wicked Reports API connection box on the 
    Authorizations Tab by clicking Enable.
    Note:     Use your unique API Key as a value of the apikey header.
  2. Select the appropriate Outbound API Endpoint to retrieve data from.
  3. Create your API to match the required Key-Value pair.
    Note: For every API Endpoint, you will see the required and optional keys. At a minimum, you'll need to include the required keys for data to be extracted successfully. 
  4. If all the data passes through successfully, you're good to go!
    Note: If the data does not pass through correctly, then please reach out to us at support@wickedreports.com and we can assist you.

Outbound API Endpoints

  • Last Updated Date Endpoint

    This API Endpoint allows you to check the date when we last updated/processed your reports.

  • Clicks API Endpoint
    This API Endpoint allows you to retrieve all key-conversion clicks, associated with a contact, within a certain timeframe.
  • Contacts API Endpoint
    This API Endpoint allows you to retrieve all contacts from your account.
    Note: To receive data, you should always provide a time period.
  • Orders API Endpoint
    This API Endpoint allows you to retrieve all the orders available within a certain timeframe. 
  • Channel API Endpoint
    This API Endpoint allows you to retrieve a list of all channels and their performance for a provided date range. Using this endpoint, you can export data down to the ad level.
  • Get Views Endpoint
    This API Endpoint allows you to list your FunnelVision "views" names and corresponding IDs.
    Ex. Use this endpoint to extract a list of view names with their corresponding view ID. Then, through the FunnelVision Data Endpoint, you can extract the view data by it's ID.
  • FunnelVision Data Endpoint
    This API Endpoint allows you to retrieve various lists of FunnelVision data:

API FAQs

Q: Should I set up the rest of my account before or after I set up the API?
A: It would be best to set up the account, as far as, completing the Fast Setup, connecting your authorizations, and adding tracking to landing pages and URLs before the API has been set up.  It is recommended you complete your Setup Audit call within 1 week of signing up with Wicked Reports so we can verify we are tracking correctly.  If your account is set up while building the API, we can attribute clicks, leads, and sales historically when you start sending us contact/order data. Please contact support@wickedreports.com with questions about the API and attribution while it is being set up.

Q: Do I need Retry Logic for my API Calls to Wicked Reports?
A: We highly encourage you to use Retry Logic on your API Calls to Wicked Reports.  Wicked Reports cannot guarantee we will always receive your API Calls.  If an API call fails to connect to our Server, please be sure to have logic that will attempt the connection and call again.  If the call fails a handful of times, you are welcome to contact Wicked Reports and we will look into the matter.

Q: What is the uptime of the Wicked Reports API Gateway?
A: API Gateway up time for the past year has been 99.9%. We see an average of ten HTTP 500 Server Errors per approximately ten thousand calls. We recommend the implementation of an effective exception-handling scheme with appropriate error-catching and retry attempts to minimize the risk of failed transfers. With effective retry logic implemented in your custom API integration code, failures should not be a problem. 

Q: Can I delete Bad/Test API Data?
A: Currently, the only way to delete test API data is to contact support and request to have the data deleted.  You can contact support@wickedreports.com with the details of the API Data you would like to have cleared out. Within a couple of days, we can complete your request.
Remember that if you want to test the API, you can use the test header as described in the  Wicked Reports API Documentation so you can pass data in and not have it impact your reports.
Q: Why Don't I See Products?
A: Please verify that you have created the products using the API.  If you have not yet created a Product, the orders you create will not be able to associate with a product and will therefore not be shown in the reports.

Q: Is There A Way To Update Products?
A: Yes, if product information is passed into the API with the same ProductID, Wicked Reports will perform an update on the ProductName and ProductPrice values for that ProductID. 

Q: Will Contacts Be Updated If We Pass In The Same ContactID?
A: No, we do not update contact data via the API.  Duplicate ContactIDs are ignored.

Q: Will Wicked Reports filter out Duplicate contacts passed into the API?
A: Yes, we prevent email addresses from being added multiple times.  You will see the email will show up in the API Verification section multiple times but when we process the data into Wicked Reports, we only add it one time.

Q: When sending Orders via API, will Wicked Reports filter out duplicate orders passed into the API?
A: Yes, if your SourceSystem and SourceID key-value pairs are the same for recurring orders, then we will de-duplicate all recurring orders and only keep the original when reporting. 

Q: What Is SubscriptionID Of An Order?
A: The SubscriptionID represents a unique value for each customer's chain of subscription payments.  This SubscriptionID ties recurring subscription payments together.  Each payment for the same customer subscription should use the same subscription ID.  This allows us to populate MRR reports as well as help us determine the first payment in a subscription.

Q: Does SourceID sorting use Numeric sorting or Alpha-Numeric Sorting?
A: Wicked Reports will sort Alpha-Numerically because there are a number of systems that use Alpha-Numeric sorting.  So, we are not able to always sort numerically.  

Q: What Timezone Do I Pass in Dates With?
A: All contact and order date/time-related data submitted to API should be converted into UTC timezone (UTC-0). On the UI within Wicked, time is represented in EST. 

Q: How are Declined / Refunded Payments used in the Reports
A: When selecting Net (instead of Gross) in the reports, we attempt to remove all Declined, Refunded payments from the revenue.  By passing in Declined and Refunded Payments, you'll get a more accurate count of Revenue.

Q: Where Do I Get My API Key?
A:  Your API Key can be found by enabling API for Contacts and/or Orders on the  Authorizations Screen of Wicked Reports (http://my.wickedreports.com/auth/dashboard).  Until you enable the API, your calls will not be processed inside Wicked Reports.
 multi touch marketing attribution software

Q: How can I verify the data we've passed in via the API?
A: When using your Live API Key, you will be able to verify the data you are passing in via the API on the API Verification Tool of Wicked Reports.


Q: Are there any restrictions on the size of a request body on endpoints?
A: There is a 1,000 rows per request (10MB) limit for a request body on all endpoints. You must send unique data to Wicked on an immediate or daily basis. Sending duplicate data, delayed data, or large requests is likely to cause performance issues (i.e. delayed processing)

Q: Why are there two sets of Outbound API endpoints?
A: The original set of Outbound API endpoints was using synchronous APIs, whereas the new set of Outbound APIs uses asynchronous APIs. Asynchronous APIs allow you to stream data, send multiple requests at the same time, and manage communication intelligently between services, while the synchronous APIs required you to make a new request every time you needed data.

Q: When inserting clicks, can the TimeOffSet value be negative? 
A: Yes. Use a positive value, such as 3, to subtract 3 minutes from Date_Time. However, if you want to use a negative value such as -2, then that will work and it will add 2 minutes to Date_Time.

Q: Does the /clicks endpoint pull custom conversions?
A: No. The /clicks endpoint will only pull the clients latest First Click, First Opt-in, Re-Optin, and Last Click. It will not pull custom conversions.