Wicked Reports API Documentation

If you do not currently use any of our integrations for Contact and Order data, you are able to utilize the Wicked Reports API to pass Contact, Order and Product data into Wicked Reports.
 
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.
 
See our  current integration page for an updated list of current CRM/ESP integrations.

VISIT OUR API FAQ 

DOWNLOAD OUR API PHP SDK

Utilizing our API consists of 4 steps.
 
1.  Enable the Wicked Reports API in the  Authorizations Tab  (see video at bottom)
2.  Import your products into Wicked Reports
3.  Import historical contacts and orders into Wicked Reports.
 
 
******************************************************************************************************************************
It is important to know:  When importing historical Contacts and Orders into Wicked Reports, please be sure to FIRST import Contacts and then import Orders.  If you do not follow this process, we cannot guarantee that your data will be correct  
******************************************************************************************************************************

4.  Set up your API Calls to fire when a new contact is add to your CRM/ESP and when a new orders is created in your CRM/Shopping Cart

Note: API Gateway up time for the past year has been 99.9%. We seen 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.


Currently there are 6 endpoints:

  • 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
  • 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
  • To insert an array of orders into Wicked Reports. During one call, it is possible to insert from 1 up to 1000 orders
  • To insert an array of orders items into Wicked Reports. During one call, it is possible to insert from 1 up to 1000 order items
  • 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
  • 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: Each Wicked Reports customer has their own unique API KEY.  You can get this API Key from the Wicked Reports Authorizations section after you've Enabled the API (see video at bottom)

There is a 10MB limit for a request body on all endpoints

For testing 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  test header as described below in the each of your test API request. If you do this, passed via API data will not be used for ANY of your Wicked Reports.  When verifying your API calls in the API, you can view only your Test data
 

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). In 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:

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

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:
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"

2) Call to find out which was the latest added contact

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 paramters 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:

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

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 add orders items and related to orders payments in a single call

POST /orders
[{
     "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
},...]

POST /orders
[{
     "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 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

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
},...]

 

3) Call to insert 1 to 1000 order payments

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 ordr 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"
},...]

 

4) Call to insert 1 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
 

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//
},...]


Testing your Wicked Reports API can be done within Wicked Reports.

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.
 

VISIT OUR API FAQ


******************************************************************************************************************************
When you are ready to go live with your API integration,
please remove the test header from your API Calls.
******************************************************************************************************************************
 

API PHP SDK

 
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.  The SDK is for developers to user, but is not necessary