Setting Up Other Data Sources
      Back to home
      1. Wicked Help Center
      2. 1. SETUP
      3. Setting Up Other Data Sources

      Wicked Reports API Documentation

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

      Introduction to Wicked Reports APIs

      Welcome to the Wicked Reports API documentation help article. This article is designed to introduce you to Wicked Reports APIs, how to set them up, and how to test & verify they're working. In addition, we've also included some frequently asked questions to ensure you have a successful experience setting up your API. 
      • For everything you need to know about the Inbound API, read here.
      • For everything you need to know about the Outbound API, read here.
      • For developers who want to jump right into the technical documentation, then you can do so by visiting this URL, https://docs.wickedreports.com/.

      Start Analyzing Today

      Still waiting on your API to be built? No problem! 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. We recommend using the CSV import immediately - the sooner you import, the sooner you can can analyze your performance.

      Inbound API

      Many of the most popular Ad Platforms, CRMs, and Shopping Carts are natively integrated with Wicked Reports. That means Wicked Reports can automatically detect ad costs, ad clicks, lead clicks, lead conversions, and sale conversions. 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 data.
       
      Inbound API Setup:

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

      1. Generate your unique API Key in the Wicked Reports API widget on the 
        Authorizations Tab by clicking "Enable". Note: Use your unique API Key as a value of the apikey header.
      2. Pick the appropriate Inbound API Endpoint for your build
      3. Build your API and format your Body to match the required Key-Value pairs:
        1. Send unique data to Wicked on an immediate or daily basis. Limit to 1,000 rows per request (10MB) for all endpoints. Sending duplicate data, delayed data, or large requests is likely to cause performance issues (i.e. delayed processing)
        2. Prior to getting started, review the Inbound API Verification Steps for tips & tricks on how to build your API. Every API Endpoint has required and optional keys. Bare minimum, you need the required keys for data to be inserted successfully. Please ensure accurate formatting.
        3. 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.
      4. Test your API
      5. Verify your API Data
      6. Go Live!

      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.
      • Inbound Orders: 
        • 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
        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.

      Inbound API Testing: 

      If you want to run test calls that will not affect your reporting, then include the test header in each of your test API requests.

      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. 

      Inbound API Verification Steps:

      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. 

      Inbound API 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!

      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:

      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:

      • 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.
      • 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 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.
      • 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?
      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.