Everything you need to know to integrate with Wicked Reports using our APIs.
- About the Inbound API
- Outbound API
- Setup & Process
- Important Information for API Endpoint development
- API Endpoints
- Verify Wicked has your Order API call data
- Verify Wicked has your Contact API call data
- API PHP SDK
- API FAQ
About the Inbound API
Wicked Reports has Inbound and Outbound APIs. This document covers the Inbound API for sending Wicked Reports clicks, leads, and sales conversion data. Inbound API, Zapier
, or HTTP post
, is necessary when you do not use any of our native integrations.
Many of the most popular CRM, Shopping Cart, and ad platforms are natively integrated with Wicked Reports. This means Wicked Reports can automatically detect lead conversions, sale conversions, auto-tag email clicks, auto-tag ad clicks, auto-retrieve ad costs, and auto-calculate ROI and LTV for many integrations!
Our list of integrations can be found here: https://www.wickedreports.com/wicked-reports-integrations
Wicked Clicks API allows you to import clicks you may have tracked yourself, directly into Wicked Reports. The clicks may help further define the customer's 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.
Wicked Contacts API 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. Again, you should only use our Contact API if we do not already directly integrate with your CRM or ESP currently.
Wicked Orders API allows 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.
If you are looking for documentation on the Wicked Reports Outbound API, please visit https://docs.wickedreports.com/. To use this feature, you must enable the API in your Authorizations screen.
The Outbound API allows you to pull data out of Wicked Reports and use it however you see fit. It can be used in Google Data Studio. It can also be used to automate other services.
If you are not a technical person or a programmer and still want access to our data via the API, you can use an initially FREE tool called SyncWith.
Watch this video and learn to pull Wicked Reports data into Google Sheets using SyncWith
- All GET calls to Retrieve channels data from WickedReports should be Asynchronous calls.
- GET https://api.wickedreports.com/channels?channel=facebook&level=adname&limit=5&from=2020-01-01&to=2020-01-31&attr_model=last_click&rev=net&async=1
Setup & Process
- Generate your unique API Key in the Wicked Reports API connection box on the
Authorizations Tab by clicking Enable.
- Use our API test functionality to get the calls passing to the endpoints.
- Go live and verify new contacts and/or orders are arriving into Wicked.
- Import historical contact data.
- Import historical order data.
Note: 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 implementation of an effective exception handling scheme with appropriate error catching and retry attempts to minimize the risk of failed transfers.
Important Information to be aware of
- Each API call should include “apikey” custom header parameter as described below.
- All date/time-related data submitted to API should be converted into UTC timezone (UTC-0). On the UI, time is represented in EST.
- Please be sure to include Retry Logic for your API Calls to ensure that every call you make is received by Wicked Reports. If your Retry Logic fails more than a handful of times, you can contact Wicked Reports to look into the matter.
- There is a 10MB limit for a request body on all endpoints
If you want to run test calls, which will not affect your 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 each of your test API requests. If you do this, data passed via API will not be used by ANY reports inside your Wicked Reports account.
Select API Verification from the Extras Menu.
You will find 5 tabs for verifying that your API calls were received by Wicked Reports
- /CONTACTS: All calls made to the /Contacts Endpoint when adding Contacts to Wicked Reports. You can verify that that all the fields were accepted and received as you expected
- You will be able to also filter your calls by Date of the API (Date Added) call and Email
- /ORDERS: All calls made to the /Orders Endpoint when adding Orders to Wicked Reports. You can verify that that all the fields were accepted and received as you expected
- You will be able to also filter your calls by Date of the API (Date Added) call and Email
- /ORDERITEMS: All calls made to the /OrderItems Endpoint when adding Order Items to Wicked Reports. You can verify that that all the fields were accepted and received as you expected
- /ORDERPAYMENTS: All calls made to the /OrderPayments Endpoint when adding Order Payments to Wicked Reports. You can verify that that all the fields were accepted and received as you expected
- /PRODUCTS: All calls made to the /Products Endpoint when adding Products to Wicked Reports. You can verify that that all the fields were accepted and received as you expected
It may take up to 30 minutes for new data to appear on this screen. After it gets there, please make sure that all the fields are populated correctly. If they are not, that likely means the data was not sent properly.
** NOTE: The data you send through the API will be processed on a daily basis and will not be reflected in your reports until the following day **
Once again, please be sure to include Retry Logic into your API Code. Wicked Reports cannot guarantee that every call made to the API will be received. If your connection and call fails, please be sure that your code is set up to Retry the call. If the call fails a handful of times, please contact Wicked Reports so we can look into the matter.
When you are ready to go live with your API integration, please remove the test header from your API Calls.
API PHP SDK
Our SDK is publicly accessible on Github
It includes a readme with instructions how to install it into your project, how to authenticate and how to perform api calls. The SDK also includes API call examples, unit tests and tips on how to easily convert time zones when doing API calls.
[DOWNLOAD SDK HERE]
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 firstname.lastname@example.org with questions about the API and attribution while it is being set up.
Q: What is the up time of the Wicked Reports API Gateway?
A: API Gateway up time for the past year has been 99.9%. We seen an average of ten HTTP 500 per approximately ten thousand calls. 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 email@example.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: 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 which 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: Why Don't I See Products?
A: Please verify that you have created the products using the API. If you have not yet created Product, the orders you create will not be able to associate to 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: What Is SubscriptionID Of An Order?
A: The SubscriptionID represents a unique value for each customers 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: Date fields in the API should always be passed in with UTC-0 time.
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.
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
Screen of Wicked Reports ( http://my.wickedreports.com/extras/api
). Each tab on this screen is related to one of the API Endpoints and allows for limited filtering.
Q: Is there a delay from when I call the API until is shows up in API Verification?
A: No, once the API call is made, it can take up to 30 minutes to show in API Verification. If you still are not seeing the data you passed in, please verify the following:
- Have you enabled the API for what you are trying to create (Contacts and/or Orders)
- Your date selection filter is correct. The filter uses Data Added for filtering rows to show
- Are you on the correct tab? If you are creating orders, make sure you are on the /ORDERS tab.