1. Help Center
  2. SETUP
  3. Setting Up Other Data Sources

Wicked Reports API Documentation

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

  1. About the Inbound API
  2. Outbound API
  3. Setup & Process
  4. Important Information for API Endpoint development
  5. Contact API Endpoint for Lead Conversions
  6. Get Last Contact Added API Endpoint
  7. Order API Endpoint for Sales Conversions
  8. Order Payments API Endpoint for Gross and Net revenue accuracy
  9. Products API Endpoint
  10. Clicks API Endpoint
  11. Testing
  12. Verify Wicked has your Order API call data
  13. Verify Wicked has your Contact API call data
  14. API PHP SDK
  15. 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, or 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

Outbound API

If you are looking for information on the Wicked Reports Outbound API, https://docs.wickedreports.com/.  This is a premium feature that must be enabled by Wicked's Customer Success team.

 
Wicked Clicks API 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.
 
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.

Setup & Process

  1. Generate your unique API Key in the Wicked Reports API connection box on the 
    Authorizations Tab by clicking Enable.
  2. Use our API test functionality to get the calls passing to the endpoints.
  3. Go live and verify new contacts and/or orders are arriving into Wicked.
  4. Import historical contact data.
  5. 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

Contact API End Points:

  • To insert an array of contacts into Wicked Reports. During one call, it is possible to insert from 1 up to 1000 contacts.
    • Notice: API does attempt to prevent duplicate inserts by email address.  If we find a contact with an email address already added, we ignore it

API URL: https://api.wickedreports.com

Custom header for each call

apikey:
test: 1  (if you want to pass test data)
 - Call to insert one to 1,000 contacts

- There is a 10MB limit for a request body

Endpoint: https://api.wickedreports.com
POST /contacts
[{
"SourceSystem": varchar(255), //REQUIRED//; name of the system where contacts coming from, may be any chosen string, must be used everywhere after, helps to identify source of contacts, (e.g. ‘ActiveCampaign’, ‘Shopify’, ‘MailChimp’)
"SourceID": varchar(500), //REQUIRED//; Unique ID of the contact in the original system
"CreateDate": datetime, should be UTC Timezone //REQUIRED//; date & time when contact was created in the original system, format: "YYYY-MM-DD HH:MM:SS" (Reminder, date must be in UTC TIME)
"Email": varchar(500), // REQUIRED//; email address of the contact
"FirstName": varchar(500),
"LastName": varchar(500),
"City": varchar(500), // not required, but needed for GEO and Predictive Behavior reports
"State": varchar(500), //not required, but needed for GEO and Predictive Behavior reports
"Country": varchar(500), //not required, but needed for GEO and Predictive Behavior reports
"Phone": varchar(255), // Phone of the contact
"IP_Address": varchar(500) // IP Address of the contact when they provided email address
},...]

Request example:

POST https://api.wickedreports.com/contacts

apikey: 1234567

test: 1  (if you want to pass test data)

Content-Type: application/json
[{
     "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"
}]
Response example:
200 OK
Content-Type:  application/json
Content-Length:  33
Connection:  keep-alive
Date:  Wed, 15 Jun 2016 13:09:25 GMT
x-amzn-RequestId:  614ce177-32fa-11e6-a1e0-87e23e650e41
X-Cache:  Miss from cloudfront
Via:  1.1 9e2316f9bf6c03b8640526708b3cdb00.cloudfront.net (CloudFront)
X-Amz-Cf-Id:  gL60g5UQdBKAiqRdFVoR7rPtt9qqB_Bnhpr8dzswHuYjVL6sv7FTSA==

"Successfully inserted 1 records"

Get Last Contact Added

  • 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
GET /latest?sourcesystem=[sourcesystem]&datatype=[datatype]&timezone=[UTCTimeZone]&sortby=[sortBy]&order=[order]
sourcesystem//REQUIRED//  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 - //REQUIRED//  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
timezone//REQUIRED//  Specifies the UTC timezone for which you want the return value to reflect. Should match the time zone of your CRM and be formatted like "UTC-5".
sortby - 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 - specified sort order of records to get latest; by default ‘desc’, possible ‘asc’
offset - possible values: 1 or 0; default: 0; if set to 1, the latest endpoint will return under the`offset` 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 - 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.)

call returns contact with the latest contact CreateDate (or importdate, depending on your sortby value)

Request example: 

GET https://api.wickedreports.com/latest?sourcesystem=ActiveCampaign&datatype=contacts

apikey: 1234567

Response example:
200 OK
Content-Type:  application/json
Content-Length:  291
Connection:  keep-alive
Date:  Wed, 15 Jun 2016 13:13:04 GMT
x-amzn-RequestId:  e27a097d-32fa-11e6-be28-ddb845a63fed
X-Cache:  Miss from cloudfront
Via:  1.1 ede9297e2bd56d0c4c812154e0ce4da2.cloudfront.net (CloudFront)
X-Amz-Cf-Id:  UiP4ftG44IM8Hkhv58ClqQxfcv0K_YryCAv4uhTRWviKprcZI1qy1Q==

{"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}

Order API Endpoints

  • To insert an array of orders into Wicked Reports. During one call, it is possible to insert from 1 up to 1000 orders
API URL:  https://api.wickedreports.com

Custom header for each call
apikey:
test: 1  (if you want to pass test data)

1) Call to Insert 1 to 1000 orders

It’s possible along with orders to add orders items and related to orders payments in a single call.

Endpoint: https://api.wickedreports.com
POST 
/orders (For sending just an order)
[{
"SourceSystem": varchar(255), //REQUIRED//; 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": varchar(500), //REQUIRED// Unique order id in the original system
"CreateDate": datetime, should be UTC Timezone //REQUIRED// order creation date and time, format: "YYYY-MM-DD HH:MM:SS" (Reminder, date must be in UTC TIME)
"ContactID": varchar(500), //REQUIRED// IF SourceSystem is the SAME as system used for contacts
"ContactEmail": varchar(500), //REQUIRED// IF SourceSystem is DIFFERENT than system used for contacts
"OrderTotal": decimal(18,2), //REQUIRED//
"OrderCurrency": varchar(3), // not required
"Country": varchar(255), // not required, but used in GEO reports, location info related to the customer of order
"City": varchar(255), // not required, but used in GEO reports , location info related to the customer of order
"State": varchar(255), // not required, but used in GEO reports, location info related to the customer of order
"SubscriptionID": varchar(500), // identification of subscription 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": varchar(500)
},...]
Endpoint: https://api.wickedreports.com
POST 
/orders (for sending order and order items in one call)
[{
"SourceSystem": varchar(255), //REQUIRED//; 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": varchar(500), //REQUIRED// Unique order id in the original system
"CreateDate": datetime, should be UTC Timezone //REQUIRED// order creation date and time, format: "YYYY-MM-DD HH:MM:SS" (Reminder, date must be in UTC TIME)
"ContactID": varchar(500), //REQUIRED// IF SourceSystem is the SAME as system used for contacts
"ContactEmail": varchar(500), //REQUIRED// IF SourceSystem is DIFFERENT than system used for contacts
"OrderTotal": decimal(18,2), //REQUIRED//
"OrderCurrency": varchar(3), // not required
"Country": varchar(255), // not required, but used in GEO reports, location info related to the customer of order
"City": varchar(255), // not required, but used in GEO reports , location info related to the customer of order
"State": varchar(255), // not required, but used in GEO reports, location info related to the customer of order
"SubscriptionID": varchar(500), // identification of subscription chain of orders.  This needs to be a UNIQUE ID for each customer to identify the chain of  subscription payments they make
"IP_Address": varchar(500),
"OrderItems": [{ //array of order items
"OrderItemID": varchar(500), //REQUIRED// ID of order item in the original system
  "ProductID": varchar(500), //ID of related product in the original system
  "Qty": int, //REQUIRED//
  "PPU": decimal(18,2) //REQUIRED// price per unit in the original system
},...],
"OrderPayments": [{ //array related to the order payment transactions
  "PaymentDate": datetime, should be UTC Timezone // REQUIRED// date and time of the payment, format: "YYYY-MM-DD HH:MM:SS" (Reminder, date must be in UTC TIME)
  "Amount": decimal(18,2), //REQUIRED// payment amount (amount should be positive, even if it's a REFUNDED payment)
  "Status": varchar(500) //REQUIRED// payment status, allowed values "APPROVED","FAILED","REFUNDED" if empty will be considered as "APPROVED"
},...]
},...]

2) Call to insert 1 to 1000 order items

Endpoint: https://api.wickedreports.com
POST 
/orderitems
[{ //json array of order items
"SourceSystem": varchar(255), //REQUIRED//; 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": varchar(500), //REQUIRED// order item id in the original system
"OrderID": varchar(500), //REQUIRED// ID of the related order in the original system
"ProductID": varchar(500), //ID of related product in the original system
"Qty": int, //REQUIRED// quantity of the product items
"PPU": decimal(18,2) //REQUIRED// price per product unit in the original system
},...]

Order Payments Endpoint

  • To insert an array of order payments into Wicked Reports. During one call, it is possible to insert from 1 up to 1000 order payments
Endpoint: https://api.wickedreports.com
POST 
/orderpayments
[{ //array of related to the order payment transactions
"SourceSystem": varchar(255), //REQUIRED//; 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": varchar(500), //REQUIRED// ID of related order in the original system
"PaymentDate": datetime, should be UTC Timezone // REQUIRED// date and time of the payment, format: "YYYY-MM-DD HH:MM:SS" (Reminder, date must be in UTC TIME)
"Amount": decimal(18,2), //REQUIRED// payment amount (amount should be positive, even if it's a REFUNDED payment)
"Status": varchar(500) // payment status, allowed values "APPROVED","FAILED","REFUNDED","PARTIALLY REFUNDED", if empty will be considered as "APPROVED"
},...]

Products Endpoint

  • To insert/update an array of products into Wicked Reports. During 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 
Endpoint: https://api.wickedreports.com
POST 
/products
[{ //array of products
"SourceSystem": varchar(255), //REQUIRED//; 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": varchar(500), //REQUIRED// product id in the original system
"ProductName": varchar(500), //REQUIRED//
"ProductPrice": decimal(18,2) //REQUIRED//
},...]

Clicks Endpoint

  • To insert/update an array of clicks into Wicked Reports. During one call, it is possible to insert from 1 up to 1000 clicks.  
Endpoint: https://api.wickedreports.com
POST /clicks
[{
"Email": varchar(255), //REQUIRED//; an email address of the executor of the click
"IP_Address": varchar(50), //REQUIRED//; the IP address where the click originated
"Date_Time": datetime, //REQUIRED except for NEW_LEAD and LAST_CLICK ConversionType
"Timezone": varchar(10), //REQUIRED//; format is UTC+/-5 or UTC+/-05:00
"TimeOffset": integer, //The number of minutes to subtract from Date_Time.
"Source": varchar(500), //The utm_source value that will be applied to the click
"Campaign": varchar(500), //The utm_campaign value that will be applied to the click
"Term": varchar(500), //The utm_term value that will be applied to the click
"Medium": varchar(500), //The utm_medium value that will be applied to the click
"Content": varchar(500), //The utm_content value that will be applied to the click
"OrderID": varchar(500), //Required only for LAST_CLICK ConversionType
"ConversionType": varchar(50), //REQUIRED// See more for each help doc. One of: LIVE_EVENT, NEW_LEAD, LAST_CLICK, REOPTIN, UNATTRIBUTED_CLICK, HUBSPOT_MEETING, MEETING, DOWNLOAD, WEBINAR, CHAT, LIVE_EVENT_DEMO, ATTRIBUTED_CLICK
"WickedId": varchar(100), //If WickedId or WickedSource has a value, both fields must be filled in.
"WickedSource": varchar(100) //If WickedId or WickedSource has a value, both fields must be filled in.
}, ...]

Testing

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.  

Select API Verification from the Extras Menu.
Screen Shot 2020-11-17 at 6.50.59 AM 
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]



API FAQ

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: 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 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: 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:
  1. Have you enabled the API for what you are trying to create (Contacts and/or Orders)
  2. Your date selection filter is correct.  The filter uses Data Added for filtering rows to show
  3. Are you on the correct tab?  If you are creating orders, make sure you are on the /ORDERS tab.