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.

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



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: <API Key Provided by Wicked Reports>
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
     "
IP_Address": varchar(500) // IP Address of the contact when they provided email address
},...]

Request example:

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

apikey: <API Key Provided by Wicked Reports>
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]&sortby=[sortBy]&order=[order]

  • sourcesystem -  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 - 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
  • 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’

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: <API Key Provided by Wicked Reports>

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: <API Key Provided by Wicked Reports>
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//
    ,"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
},...]

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//
    ,"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
The data in this screen is Real-Time and if you made an successful API Call, it should show up in here immediately.  Please make sure that all the fields are populated correctly.  If they are not, that likely means the data was not sent properly.


** NOTE: Even though the API Data will appear here in Real-Time, it will still 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