Wicked Reports API

API Endpoint
https://api.wickedreports.com

The Wicked Reports API allows you to import or retrieve data stored into Wicked Reports.

Retrieving data could be useful for analysis and/or visualization in your own interface.

Getting Started

Inserting data via the API’s is free for all Wicked Reports customers. However, in order to start using the Wicked Reports outbound API endpoint for data retrieval, you need to contact us so we can enable it for your account.

If the outbound API endpoints are not enabled for your account you are going to receive a 401 response with the following body:

{
    "status": "error",
    "message": "Outbound API not enabled for client."
}

Authorization

In order to authorize with the Wicked Reports Outbound API, you need to provide a header named apikey having your API key as a value.

Getting an API key

You can receive an API key by enabling the API for contact and/or orders in the "Authorizations" page of your dashboard. You will get a valid API key to use with the outbound API regardless of which API you decide to enable on the Authorizations screen.

After you have enabled either the contacts or the orders API, go on and copy the string below “Your API key” in the API card and provide it as a value of the apikey header.

Here’s an example header:

apikey: HhpTUGLq9qM5CKzaOnYpO1fU1BItrCHg

Throttling

The Wicked Reports Outbound API will by default be throttling your requests to 120 requests per minute. In the response, you are going to find the following headers that will help you control your requests:

  • x-ratelimit-limit - The total number of requests you can make.

  • x-ratelimit-remaining - The number of requests you have remaining.

  • x-ratelimit-reset - The time when your limit resets.

Inbound API endpoints

The inbound endpoints in the WickedReports API are used to insert new tracking data for analysis. These are available to all Wicked Reports customers but should be enabled first from the Authorization screen in the Wicked Reports dashboard. Read more in the “Authorization” section of this documentation.

When sending new data, have in mind that it might taked up to 30 minutes for new API data to appear inside the API Validator tool in the Wicked Reports dashboard.

Outbound API endpoints

The outbound API endpoints (the ones that are used to retrieve data) are available only to certain Wicked Reports customers who have them enabled.

This is a premium feature that must be enabled by Wicked’s Customer Success team.

Testing

Any 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 value of 1, it would mean you are not sending real data but rather one for test 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 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.

Inbound Contacts

With the endpoints for contacts, you can insert information about your contacts to Wicked Reports.

Insert contacts

POST https://api.wickedreports.com/contacts
RequestsInsert new contacts with JSON
Headers
Content-Type: application/json
Body
[
  {
    "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",
    "Phone": "00000000"
  }
]
Responses200
Headers
Content-Type: application/json
Body
{
  "success": "Successfully inserted 1 / 1 records.",
  "records": 1,
  "totalRecords": 1,
  "errors": []
}

Insert contacts
POST/contacts

This endpoint 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.

You can insert from 1 to 1000 contacts with a single HTTP request.

The API does attempt to prevent duplicate inserts by email address. If we find a contact with an email address already added, we will ignore it.

The limit for the request body is 10 MB.

Contact object attributes

This endpoint accepts data sent as a JSON array of contacts with each contact having the following attributes:

Key Type (max length) Required Description
SourceSystem string(255) yes The name identifier of the source system where this contact came from.
SourceID string(500) yes Unique ID of the contact in the original system.
CreateDate datetime string yes Date & time when contact was created in the original system converted into UTC+0 timezone. (Format: “YYYY-MM-DD HH:MM:SS”)
Email string(500) yes The email address of the contact. Must be valid if the contact is to send to Facebook CAPI.
FirstName string(500) no First name of the lead/contact.
LastName string(500) no Last name of the lead/contact.
City string(500) no City of the contact. Even though, not required it’s important for the GEO and Predictive Behavior reports so you may want to supply it.
State string(500) no State from the address of the contact. Same as with city, needed for the GEO and Predictive Behavior reports.
Country string(500) no The country of the contacts. Required for GEO and Predictive Behavior reports.
Phone string(255) no A phone number of the contact.
IP_Address string(500) no The IP address of the contact when the email address was provided.

Headers

Apart from the authorization apikey header, the POST /contacts endpoint also accepts the following headers:

Header Description Default
test Whether the inserted data is for test purposes only and it shouldn’t be taken into account. 0

Inbound Clicks

Insert clicks

POST https://api.wickedreports.com/clicks
RequestsInsert clickTry inserting click with invalid data
Headers
Content-Type: application/json
Body
[
  {
    "Email": "test@example.com",
    "IP_Address": "127.0.0.1",
    "Date_Time": "2021-05-17 00:15:23.123",
    "Timezone": "UTC-0",
    "TimeOffset": 3,
    "Source": "docs",
    "Campaign": "docs",
    "Term": "docks-clicks-example",
    "Medium": "docks-clicks",
    "Content": "docks-clicks-request-body",
    "OrderID": "test-order-id-1",
    "ConversionType": "LAST_CLICK",
    "WickedId": "",
    "WickedSource": ""
  }
]
Responses200
Headers
Content-Type: application/json
Body
{
  "success": "Successfully inserted 1 / 1 records.",
  "records": 1,
  "totalRecords": 1,
  "errors": []
}
Headers
Content-Type: application/json
Body
[{
    "Email": "test@example.com",
    "IP_Address": "127.0.0.1",
    "Date_Time": "",
    "Timezone": "UTC-0",
    "ConversionType": "LIVE_EVENT",
}]
Responses200
Headers
Content-Type: application/json
Body
{
    "success": "Successfully inserted 0 / 1 records.",
    "records": 0,
    "totalRecords": 1,
    "errors": [
        {
            "item": {
                "Email": "test@example.com",
                "IP_Address": "127.0.0.1",
                "Date_Time": "",
                "Timezone": "UTC-0",
                "ConversionType": "LIVE_EVENT",
            },
            "error": "Please provide a valid date and time or NOW. Valid datetime format: mm/dd/yyyy hh:mm am/pm"
        }
    ]
}

Insert clicks
POST/clicks

The clicks endpoint 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.

With 1 API call you can insert from 1 to 1000 click records at once.

Click object attributes The endpoint accepts a JSON array of clicks object, each with the following properties:

Key Type (max length) Required Description
Email string(255) yes The email address of the executor of the click.
IP_Address string(50) no The IP address where the click originated.
Date_Time datetime string conditional Date and time of the clicks. Required unless ConversionType value is NEW_LEAD or LAST_CLICK.
Timezone string(10) yes The timezone of the date time you’ve provided. Format: UTC+/-5 or UTC+/-05:00.
TimeOffset integer no The number of minutes to subtract from Date_Time. For example, if we know the clicks was tracked with a delay.
Source string(500) no The utm_source value that will be applied to the click.
Campaign string(500) no The utm_campaign value that will be applied to the click.
Term string(500) no The utm_term value that will be applied to the click.
Medium string(500) no The utm_medium value that will be applied to the click.
Content string(500) no The utm_content value that will be applied to the click.
OrderID string(500) conditional Required only for LAST_CLICK ConversionType.
ConversionType string(50) yes One of: LIVE_EVENT, NEW_LEAD, LAST_CLICK, REOPTIN, UNATTRIBUTED_CLICK, HUBSPOT_MEETING, MEETING, DOWNLOAD, WEBINAR, CHAT, LIVE_EVENT_DEMO, ATTRIBUTED_CLICK. You can learn more about each one here.
WickedId string(100) conditional If WickedId or WickedSource has a value, both fields must be filled in.
WickedSource string(100) conditional If WickedId or WickedSource has a value, both fields must be filled in.

Inbound Orders

Insert new data into WickedReports.

The Wicked Reports API inbound orders endpoints allow 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.

Insert orders

POST https://api.wickedreports.com/orders
RequestsInsert orders only with JSONInsert orders with order items and payments
Headers
Content-Type: application/json
Body
[{
    "SourceSystem": "TestCart",
    "SourceID": "test-order-id",
    "CreateDate": "2021-05-17 15:28:33",
    "ContactID": "test-contact",
    "OrderTotal": 1099,
    "Country": "US",
    "City": "New York",
    "State": "NY",
    "IP_Address": "127.0.0.1",
    "OrderItems": [{
        OrderItemID: "test-order-item",
        ProductID: "test-product-id",
        Qty: 1,
        PPU: 1099
    }]
}]
Responses200
Headers
Content-Type: application/json
Body
{
  "success": "Successfully inserted 1 / 1 records",
  "records": 1,
  "totalRecords": 1,
  "errors": []
}
Headers
Content-Type: application/json
Body
[
  {
    "SourceSystem": "TestCart",
    "SourceID": "test-order-id",
    "CreateDate": "2021-05-17 15:28:33",
    "ContactID": "test-contact",
    "OrderTotal": 1099,
    "Country": "US",
    "City": "New York",
    "State": "NY",
    "IP_Address": "127.0.0.1",
    "OrderItems": [
      {
        "OrderItemID": "some-item-id",
        "ProductID": "awesome-product",
        "Qty": 1,
        "PPU": 1099
      }
    ],
    "OrderPayments": [
      {
        "PaymentDate": "2021-05-17 15:28:33",
        "Amount": 1099,
        "Status": "APPROVED"
      }
    ]
  }
]
Responses200
Headers
Content-Type: application/json
Body
{
  "success": "Successfully inserted 1 / 1 records",
  "records": 1,
  "totalRecords": 1,
  "errors": []
}

Insert orders
POST/orders

Insert orders data into Wicked Reports. With this endpoint you can insert order information only or you can insert order items and order payment together with the order.

Warning: When inserting order items as part of an orders request as opposed to a separate /orderitems call, the SourceID attribute on order items needs to be substituted with the key OrderItemID. Please refer to the “Insert orders with order items and payments” example request on the right.

Key Type (max length) Required Description
SourceSystem string(255) yes 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 string(500) yes Unique order id in the original system.
CreateDate string datetime yes order creation date and time converted into UTC+0 timezone. (Format: “YYYY-MM-DD HH:MM:SS”)
ContactEmail string(500) conditional RECOMMENDED over ContactID. Required IF SourceSystem is DIFFERENT than the system used for contacts. Should be sent and valid if the order is to be sent to Facebook CAPI.
ContactID string(500) conditional Only used IF SourceSystem is the SAME as the system used for contacts.
OrderTotal decimal(18,2) yes Total amount of the order.
OrderCurrency string(3) no Three letter code of the currency if it’s different than USD.
Country string(255) no Country where the order originated from. Used in GEO reports, location info related to the customer of order.
City string(255) no City where the order originated from. Used in GEO reports, location info related to the customer of order.
State string(255) no If applicable, state where the order originated. Again, used in GEO reports, location info related to the customer of order.
SubscriptionID string(500) no Identifier of a subscription if the order is part of a recurring 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 string(500) no The IP address from which the order originated.
OrderItems array[OrderItem] no An array of order items to associate with this order. The properties of an OrderItem are almost the same as described in the /orderitems call except for SourceID. SourceID is expected as OrderItemID with this request (SourceID -> OrderItemID). Please note the warning above and make sure to use OrderItemID instead of SourceID.
OrderPayments array[OrderPayment] no An array of order payments to associate with this order.

Insert order items

POST https://api.wickedreports.com/orderitems
RequestsInsert order item
Headers
Content-Type: application/json
Body
[
  {
    "SourceSystem": "TestCart",
    "SourceID": "some-item-id",
    "OrderID": "test-order-id",
    "ProductID": "awesome-product",
    "Qty": 1,
    "PPU": 1099
  }
]
Responses200
Headers
Content-Type: application/json
Body
{
  "success": "Successfully inserted 1 / 1 records",
  "records": 1,
  "totalRecords": 1,
  "errors": []
}

Insert order items
POST/orderitems

Add order items for a certain order to WickedReports.

Key Type (max length) Required Description
SourceSystem string(255) yes 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 string(500) yes Order item id in the original system.
OrderID string(500) yes ID of the related order in the original system.
ProductID string(500) no ID of related product in the original system, required if there is a need to connect the product with an order.
Qty integer yes Quantity of the order items.
PPU decimal(18,2) yes Price per product unit in the original system.

Insert order payments

POST https://api.wickedreports.com/orderpayments
RequestsInsert order payment
Headers
Content-Type: application/json
Body
[
  {
    "SourceSystem": "TestCart",
    "OrderID": "test-order-id",
    "PaymentDate": "2021-05-17 15:28:33",
    "Amount": 1099,
    "Currency": "USD",
    "Status": "APPROVED"
  }
]
Responses200
Headers
Content-Type: application/json
Body
{
  "success": "Successfully inserted 1 / 1 records",
  "records": 1,
  "totalRecords": 1,
  "errors": []
}

Insert order payments
POST/orderpayments

Use this endpoint to insert an array of order payments into Wicked Reports.

With one call, it is possible to insert from 1 up to 1000 order payments.

Key Type (max length) Required Description
SourceSystem string(255) yes 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 string(100) yes ID of related order in the original system.
PaymentDate datetime string yes date and time of the payment, format: “YYYY-MM-DD HH:MM:SS” (Reminder, date must be in UTC TIME)
Amount decimal(18,2) yes Payment amount (amount should be positive, even if it’s a REFUNDED payment).
Currency string(3) no Currency of the payment.
Status string no Payment status, allowed values APPROVED, FAILED, REFUNDED, PARTIALLY REFUNDED, if empty will be considered as APPROVED

Insert products data

POST https://api.wickedreports.com/products
RequestsInsert product
Headers
Content-Type: application/json
Body
[
  {
    "SourceSystem": "TestCart",
    "SourceID": "awesome-product",
    "ProductName": "An Awesome Product to Buy",
    "ProductPrice": 1099
  }
]
Responses200
Headers
Content-Type: application/json
Body
{
  "success": "Successfully inserted 1 / 1 records",
  "records": 1,
  "totalRecords": 1,
  "errors": []
}

Insert products data
POST/products

Use this endpoint to insert/update an array of products into Wicked Reports.

With 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

Key Type (max length) Required Description
SourceSystem string(255) yes 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 string(500) yes product id in the original system
ProductName string(500) yes Name of the product.
ProductPrice decimal(18,2) yes Price of the product.

Inbound Marketing Data

If you have marketing costs that you’d like entered into Wicked Reports that Wicked doesn’t have an integration with (SnapChat, Twitter, Bing, etc), you can send these costs using this endpoint.

Insert marketing data

POST https://api.wickedreports.com/marketing
RequestsSubmit marketing data to Wicked Reports.
Headers
Content-Type: application/json
Body
[
  {
    "Date_Time": "2021-05-17 00:00:00",
    "Source": "test_source",
    "Medium": "test_medium",
    "Campaign": "test_campaign",
    "Content": "test_content",
    "Term": "test_term",
    "Clicks": 315,
    "Cost": 95.37,
    "AdId": "1234567",
    "AccountId": "12345689abc-1",
    "SourceSystem": "SourceSystem",
    "LastUpdatedDate": "2021-05-17 23:15:23",
    "ConversionCount": 5,
    "ConversionValue": 200,
    "AdStatus": "active",
    "CampaignStatus": "active",
    "AdGroupStatus": "active",
    "AdSetStatus": "active",
    "AdType": "Video",
    "CampaignId": "123",
    "AdGroupId": "test_group"
  }
]
Responses200
Headers
Content-Type: application/json
Body
{
  "success": "Successfully inserted 1 / 1 records.",
  "records": 1,
  "totalRecords": 1,
  "errors": []
}

Insert marketing data
POST/marketing

Send marketing data to Wicked Reports.

Key Type (max length) Required Description
Date_Time datetime string yes The date time of the marketing data information. Format: YYYY-MM-DD 00:00:00. Please match timezone with your CRM/Shopping cart data timezone data if possible
Source string(500) yes The utm_source value.
Medium string(500) no The utm_medium value.
Campaign string(500) no The utm_campaign value.
Content string(500) no The utm_content value.
Term string(500) no The utm_term value.
Clicks integer yes The number of clicks that this marketing activity got.
Cost decimal(18,2) yes The cost associated with this marketing data.
AdId string yes The ad ID associated with this marketing data.
AccountId string yes The account ID associated with this marketing data.
SourceSystem string no System source value.
LastUpdatedDate datetime string no The latest date time of the update of marketing data information.
ConversionCount integer no How many conversions does the platform think this ad received.
ConversionValue integer no What is the conversion value the platform think this ad received.
AdStatus string no Ad status value (active/paused/etc).
CampaignStatus string no Campaign status (active/paused/etc).
AdGroupStatus string no Ad group status value (exclusive with AdSetStatus) (active/paused/etc).
AdSetStatus string no Ad set status value (exclusive with AdGroupStatus) (active/paused/etc).
AdType string no Ad type value (Video, Image).
CampaignId string no Campaign ID value.
AdGroupId string no Ad group ID value.

Outbound Async Contacts

With the endpoints for contacts, you can retrieve information about your contacts in Wicked Reports.

List all contacts

GET https://api.wickedreports.com/async/contacts?from=2020-07-01&to=2020-07-02
Responses200400
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "resultId": "cf0e618"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "error"
      ]
    },
    "resultId": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "status": "error",
  "message": "There was some problem with your request. You should review the parameters and try again."
}

List all contacts
GET/async/contacts{?from,to}

The contacts endpoint allows you to retrieve all contacts from your account. Note that you should always provide a time period in order to receive any data.

The links field in the response will contain an empty object, if the contact doesn’t have any clicks.

URI Parameters
HideShow
from
string (required) Example: 2020-07-01

The start date to look for contacts. Format: YYYY-MM-DD

to
string (required) Example: 2020-07-02

Date until which to look for contacts. Format: YYYY-MM-DD

Retrieve a single contact

GET https://api.wickedreports.com/async/contacts/AB-1234567
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "resultId": "cf0e618"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "error"
      ]
    },
    "resultId": {
      "type": "string"
    }
  }
}

Retrieve a single contact
GET/async/contacts/{contactId}

You can also look for a contact using their email with this endpoint. Simply provide the email in the contactId parameter like this: /async/contacts/test@example.com.

The links field in the response will contain an empty object, if the contact doesn’t have any clicks.

URI Parameters
HideShow
contactId
string (required) Example: AB-1234567

The id of the contact to retrieve. This could be either the internal id of the contact that you can find under the id property or the sourceId which is the id in your source system. You can also use an email for this parameter.

Fetch response for specific request

GET https://api.wickedreports.com/async/results/cf0e618?limit=1&next=1
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "results": {
    "id": "2374d95",
    "data": [
      {
        "id": "AB-1234567",
        "sourceId": "someIdInSourceSystem",
        "sourceSystem": "test",
        "email": "test@example.com",
        "firstName": "Test",
        "lastName": "Contact",
        "LTV": 0,
        "createDate": "2020-07-15T00:10:17.000Z",
        "firstClick": {
          "date": "2020-07-28T20:48:21.000Z",
          "source": "some-source",
          "medium": "some-medium",
          "campaign": "some-campaign",
          "content": "some-content",
          "term": "some-term"
        },
        "firstOptin": {
          "date": "2020-07-28T20:48:21.000Z",
          "source": "some-source",
          "medium": "some-medium",
          "campaign": "some-campaign",
          "content": "some-content",
          "term": "some-term"
        },
        "reOptin": {
          "date": "2020-07-30T00:01:43.000Z",
          "source": "Email",
          "medium": "email",
          "campaign": "test-campaign",
          "content": "test-content",
          "term": "test-term"
        },
        "urlWicked": "https://my.wickedreports.com/extras/customerltv?report=newlead&id=AB-1234567",
        "links": {
          "clicks": {
            "href": "/contacts/AB-1234567/clicks"
          },
          "orders": {
            "href": "/contacts/AB-1234567/orders"
          }
        }
      }
    ]
  },
  "meta": {
    "page": "2",
    "limit": "1000",
    "pageResults": "1000",
    "next": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "error"
      ]
    },
    "results": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "sourceId": {
                "type": "string"
              },
              "sourceSystem": {
                "type": "string",
                "description": "Source system of the contact or unknown in case the source cannot be determined."
              },
              "email": {
                "type": "string"
              },
              "firstName": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "lastName": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "LTV": {
                "type": "number"
              },
              "createDate": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "firstClick": {
                "type": "object",
                "properties": {
                  "date": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "source": {
                    "type": "string"
                  },
                  "medium": {
                    "type": "string"
                  },
                  "campaign": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "term": {
                    "type": "string"
                  }
                }
              },
              "firstOptin": {
                "type": "object",
                "properties": {
                  "date": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "source": {
                    "type": "string"
                  },
                  "medium": {
                    "type": "string"
                  },
                  "campaign": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "term": {
                    "type": "string"
                  }
                }
              },
              "reOptin": {
                "type": "object",
                "properties": {
                  "date": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "default": "null"
                  },
                  "source": {
                    "type": "string"
                  },
                  "medium": {
                    "type": "string"
                  },
                  "campaign": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "term": {
                    "type": "string"
                  }
                },
                "required": [
                  "date"
                ]
              },
              "urlWicked": {
                "type": "string"
              },
              "links": {
                "type": "object",
                "properties": {
                  "clicks": {
                    "type": "object",
                    "properties": {
                      "href": {
                        "type": "string"
                      }
                    }
                  },
                  "orders": {
                    "type": "object",
                    "properties": {
                      "href": {
                        "type": "string"
                      }
                    }
                  }
                },
                "description": "Can be an empty object if the contact doesn't have any clicks"
              }
            },
            "required": [
              "id",
              "sourceId",
              "email",
              "urlWicked"
            ]
          }
        }
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "page": {
          "type": "string"
        },
        "limit": {
          "type": "string"
        },
        "pageResults": {
          "type": "string"
        },
        "next": {
          "type": "boolean"
        }
      }
    }
  }
}

Fetch response for specific request
GET/async/results/{resultId}{?limit,next}

You can use this endpoint to get a result for request to /async/contacts and /async/contacts/{contactId} endpoint.

URI Parameters
HideShow
resultId
string (required) Example: cf0e618

The id of the result to retrieve. This could be received from any outbound endpoint.

limit
number (optional) Default: 1000 Example: 1

Number of orders to return with a single call (max: 1000).

next
0, 1 (optional) Example: 1

A number indicating whether you need to go to the next page or to the very first page. Pass 1 if you need the next page, and 0 if you do not need next. Passing 0 and omitting this field causes the same behaviour.

Outbound Async Clicks

Retrieve the processed clicks from Wicked Reports.

List all clicks

GET https://api.wickedreports.com/async/clicks?from=2020-07-01&to=2020-07-02
Responses200400
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "resultId": "cf0e618"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "error"
      ]
    },
    "resultId": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "status": "error",
  "message": "There was some problem with your request. You should review the parameters and try again."
}

List all clicks
GET/async/clicks{?from,to}

You can use this endpoint to retrieve all clicks associated with a contact within a certain timeframe. This endpoint will not be providing all clicks tracked, only clicks tracked to a specific contact.

The difference between parameters from and to cannot exceed 30 days.

Clicks that you’ve just submitted to the Wicked Reports API will not be returned by this endpoint. It might take up to 24 hours for these to appear in the response. You can use the API Verification tool in the Wicked Reports dashboard to validate data that you’ve recently sent.

URI Parameters
HideShow
from
string (required) Example: 2020-07-01

The start date to look for clicks. Format: YYYY-MM-DD

to
string (required) Example: 2020-07-02

The end date to look for clicks. Format: YYYY-MM-DD

Retrieve the clicks of a specific contact

GET https://api.wickedreports.com/async/clicks/test-contact-id?from=2020-07-01&to=2020-07-30
Responses200400
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "resultId": "cf0e618"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "error"
      ]
    },
    "resultId": {
      "type": "string"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "status": "error",
  "message": "There was some problem with your request. You should review the parameters and try again."
}

Retrieve the clicks of a specific contact
GET/async/clicks/{contactId}{?from,to}

contactId - in this case is the unique ContactID generated by Wicked Reports and will not match the contactID from your CRM. This value can be seen in the contact history within the Customer LTV Report

You can use this endpoint to retrieve all clicks of a single contact within a specified time frame. The result will be a raw dataset of clicks. Wicked Reports uses proprietary logic and technology to determine which clicks are shown and reported inside our platform. Clicks returned from this endpoint will likely not match clicks displayed for this contact inside Wicked Reports.

The first 10,000 clicks of a single contact will be returned paginated. If the contact has more, you will have to use the from and to parameters to retrieve any clicks after the 10,000th. The difference between the parameters from and to cannot exceed 180 days in this case.

You can look for the orders of a single contact using their Wicked Reports Contact id, sourceId (contactID from your CRM) or email with this endpoint. Simply provide the value in the contactId parameter. An example with the email would be: /async/clicks/test@example.com.

URI Parameters
HideShow
contactId
string (required) Example: test-contact-id

The id of the contact whose clicks you would like to receive. This could be either the internal id of the contact that you can find under the contactId property or the contactSourceId which is the id in your source system. You can also use an email for this parameter.

from
string (optional) Example: 2020-07-01

The start date to look for clicks. Format: YYYY-MM-DD

to
string (optional) Example: 2020-07-30

The end date to look for clicks. Format: YYYY-MM-DD

Fetch response for specific request

GET https://api.wickedreports.com/async/results/cf0e618?limit=1&next=1
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "results": {
    "id": "74bd59a",
    "data": [
      {
        "contactId": "test-contact-id",
        "contactSourceId": "test-contact-source-id",
        "date": "2020-07-01T00:01:43.000Z",
        "email": "test@example.com",
        "isFirstClick": false,
        "isFirstOptin": false,
        "isLastClick": false,
        "isReOptin": true,
        "source": "hubspot",
        "utms": {
          "source": "Email",
          "medium": "email",
          "campaign": "test-campaign",
          "content": "test-content",
          "term": "test-term"
        },
        "wickedid": "1234567",
        "wickedsource": "test",
        "trackingUrl": "https://example.com/tracking/url",
        "links": {
          "contact": {
            "href": "/contacts/AB-1234567"
          }
        }
      }
    ]
  },
  "meta": {
    "page": "2",
    "pageResults": "1000",
    "limit": "1000",
    "next": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "error"
      ]
    },
    "results": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "contactId": {
                "type": "string",
                "description": "The id of the contact in Wicked Reports."
              },
              "contactSourceId": {
                "type": "string",
                "description": "The id of the contact in your source system."
              },
              "date": {
                "type": "string",
                "description": "The date and time of the click."
              },
              "email": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The email of the contact this clicks belong to."
              },
              "isFirstClick": {
                "type": "boolean"
              },
              "isFirstOptin": {
                "type": "boolean"
              },
              "isLastClick": {
                "type": "boolean"
              },
              "isReOptin": {
                "type": "boolean"
              },
              "source": {
                "type": "string"
              },
              "utms": {
                "type": "object",
                "properties": {
                  "source": {
                    "type": "string"
                  },
                  "medium": {
                    "type": "string"
                  },
                  "campaign": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "term": {
                    "type": "string"
                  }
                }
              },
              "wickedid": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "wickedsource": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "trackingUrl": {
                "type": "string"
              },
              "links": {
                "type": "object",
                "properties": {
                  "contact": {
                    "type": "object",
                    "properties": {
                      "href": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            },
            "required": [
              "contactId",
              "date"
            ]
          }
        }
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "page": {
          "type": "string"
        },
        "pageResults": {
          "type": "string"
        },
        "limit": {
          "type": "string"
        },
        "next": {
          "type": "boolean"
        }
      }
    }
  }
}

Fetch response for specific request
GET/async/results/{resultId}{?limit,next}

You can use this endpoint to get a result for request to /async/clicks and /async/clicks/{contactId} endpoint.

URI Parameters
HideShow
resultId
string (required) Example: cf0e618

The id of the result to retrieve. This could be received from any outbound endpoint.

limit
number (optional) Default: 1000 Example: 1

Number of orders to return with a single call (max: 1000).

next
0, 1 (optional) Example: 1

A number indicating whether you need to go to the next page or to the very first page. Pass 1 if you need the next page, and 0 if you do not need next. Passing 0 and omitting this field causes the same behaviour.

Outbound Async Orders

Insert new data or retrieve existing data tracked orders by WickedReports.

The Wicked Reports API inbound orders endpoints allow 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.

List all orders

GET https://api.wickedreports.com/async/orders?from=2020-07-01&to=2020-07-02
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "resultId": "cf0e618"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "error"
      ]
    },
    "resultId": {
      "type": "string"
    }
  }
}

List all orders
GET/async/orders{?from,to}

Get all orders within a certain time frame.

URI Parameters
HideShow
from
string (required) Example: 2020-07-01

The start date to look for orders. Format: YYYY-MM-DD

to
string (required) Example: 2020-07-02

Date until which to look for orders. Format: YYYY-MM-DD

Retrieve the orders of a single contact

GET https://api.wickedreports.com/async/ordersAB-1234567?from=2020-07-01&to=2020-07-02
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "resultId": "cf0e618"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "error"
      ]
    },
    "resultId": {
      "type": "string"
    }
  }
}

Retrieve the orders of a single contact
GET/async/orders{contactId}{?from,to}

contactId - in this case is the unique ContactID generated by Wicked Reports and will not match the contactID from your CRM. This value can be seen in the contact history within the Customer LTV Report

You can use this endpoint to request the orders of a single contact. The response format will be similar to the one when getting all of the orders except that it will contain only the ones belonging to the contact id specified and won’t have information about the contact. If you need detailed information about the contact whose orders you are requesting, please check the /async/contacts/{contactId} endpoint above.

You can look for the orders of a single contact using their Wicked Reports Contact id, sourceId (contactID from your CRM) or email with this endpoint. Simply provide the value in the contactId parameter. An example with the email would be: /async/orders/test@example.com.

Note that when you request the orders of a specific contact, each order object won’t contain information about the contact as it is with the listing of all orders.

URI Parameters
HideShow
contactId
string (required) Example: AB-1234567

The id of the contact whose orders you would like to receive.

from
string (required) Example: 2020-07-01

The start date to look for orders. Format: YYYY-MM-DD

to
string (required) Example: 2020-07-02

Date until which to look for orders. Format: YYYY-MM-DD

Fetch response for specific request

GET https://api.wickedreports.com/async/results/cf0e618?limit=1&next=1
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "results": {
    "id": "e1090cd",
    "data": [
      {
        "id": "WR-order-id",
        "sourceId": "test-source-order-id",
        "sourceSystem": "stripe",
        "date": "2020-06-18T06:00:27.000Z",
        "attributions": {
          "firstClick": {
            "date": "2020-06-18T02:00:27",
            "source": "direct",
            "medium": "direct",
            "campaign": "direct",
            "content": "direct",
            "term": "direct"
          },
          "firstOptin": {
            "date": "2020-06-18T02:00:27",
            "source": "direct",
            "medium": "direct",
            "campaign": "direct",
            "content": "direct",
            "term": "direct"
          },
          "reOptin": {
            "date": "2020-06-18T02:00:27",
            "source": "direct",
            "medium": "direct",
            "campaign": "direct",
            "content": "direct",
            "term": "direct"
          },
          "lastClick": {
            "date": "2020-06-18T02:00:27",
            "source": "direct",
            "medium": "direct",
            "campaign": "direct",
            "content": "direct",
            "term": "direct"
          }
        },
        "contact": {
          "id": "AB-1234567",
          "sourceId": "test-source-contact-id",
          "sourceSystem": "unknown",
          "email": "test@example.com"
        },
        "products": [
          {
            "id": "test-product-id",
            "name": "Awesome Subscription Plan",
            "qty": 1,
            "PPU": 79
          }
        ],
        "payments": [
          {
            "date": "2020-06-18T02:00:27",
            "status": "APPROVED",
            "amount": 79
          }
        ],
        "amount": 79,
        "currency": "USD",
        "subscriptionId": "test-subscription-1234567",
        "links": {
          "contact": {
            "href": "/contacts/AB-1234567"
          },
          "clicks": {
            "href": "/contacts/AB-1234567/clicks"
          }
        }
      }
    ]
  },
  "meta": {
    "page": "2",
    "limit": "1000",
    "pageResults": "1000",
    "next": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "error"
      ]
    },
    "results": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "sourceId": {
                "type": "string"
              },
              "sourceSystem": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "date": {
                "type": "string"
              },
              "attributions": {
                "type": "object",
                "properties": {
                  "firstClick": {
                    "type": "object",
                    "properties": {
                      "date": {
                        "type": "string",
                        "default": "null"
                      },
                      "source": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "medium": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "campaign": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "content": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "term": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    }
                  },
                  "firstOptin": {
                    "type": "object",
                    "properties": {
                      "date": {
                        "type": "string",
                        "default": "null"
                      },
                      "source": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "medium": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "campaign": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "content": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "term": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    }
                  },
                  "reOptin": {
                    "type": "object",
                    "properties": {
                      "date": {
                        "type": "string",
                        "default": "null"
                      },
                      "source": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "medium": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "campaign": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "content": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "term": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    }
                  },
                  "lastClick": {
                    "type": "object",
                    "properties": {
                      "date": {
                        "type": "string",
                        "default": "null"
                      },
                      "source": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "medium": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "campaign": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "content": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "term": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    }
                  }
                }
              },
              "contact": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "sourceId": {
                    "type": "string"
                  },
                  "sourceSystem": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "sourceId"
                ]
              },
              "products": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "qty": {
                      "type": "number"
                    },
                    "PPU": {
                      "type": "number"
                    }
                  }
                }
              },
              "payments": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "date": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "APPROVED",
                        "FAILED",
                        "REFUNDED",
                        "Partially Refunded",
                        "MANUAL"
                      ]
                    },
                    "amount": {
                      "type": "number"
                    }
                  }
                }
              },
              "amount": {
                "type": "number"
              },
              "currency": {
                "type": "string"
              },
              "subscriptionId": {
                "type": "string"
              },
              "links": {
                "type": "object",
                "properties": {
                  "contact": {
                    "type": "object",
                    "properties": {
                      "href": {
                        "type": "string"
                      }
                    }
                  },
                  "clicks": {
                    "type": "object",
                    "properties": {
                      "href": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            },
            "required": [
              "id",
              "sourceId",
              "date"
            ]
          }
        }
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "page": {
          "type": "string"
        },
        "limit": {
          "type": "string"
        },
        "pageResults": {
          "type": "string"
        },
        "next": {
          "type": "boolean"
        }
      }
    }
  }
}

Fetch response for specific request
GET/async/results/{resultId}{?limit,next}

You can use this endpoint to get a result for request to /async/orders and /async/orders{contactId} endpoint.

URI Parameters
HideShow
resultId
string (required) Example: cf0e618

The id of the result to retrieve. This could be received from any outbound endpoint.

limit
number (optional) Default: 1000 Example: 1

Number of orders to return with a single call (max: 1000).

next
0, 1 (optional) Example: 1

A number indicating whether you need to go to the next page or to the very first page. Pass 1 if you need the next page, and 0 if you do not need next. Passing 0 and omitting this field causes the same behaviour.

Outbound Async Channels

Retrieve channels from WickedReports.

List all channels

GET https://api.wickedreports.com/async/channels?from=2021-05-01&to=2021-05-02&level=channel&rev=gross&attr_model=linear&channel=overall&source=test&medium=ppc&campaign=test&content=test&term=test&campaignid=12345678901111&adsetid=1234567890846&adgroupid=12345678951
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "resultId": "cf0e618"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "error"
      ]
    },
    "resultId": {
      "type": "string"
    }
  }
}

List all channels
GET/async/channels{?from,to,level,rev,attr_model,channel,source,medium,campaign,content,term,campaignid,adsetid,adgroupid}

You can use this endpoint to get a list of all channels and their performance for a provided date range.

URI Parameters
HideShow
from
string (required) Example: 2021-05-01

The start date of the channels data period. Format: YYYY-MM-DD

to
string (required) Example: 2021-05-02

The end date of the channels data period. Format: YYYY-MM-DD

level
сhannel, сampaign, adset/adgroup, adname/keyword (optional) Example: channel

level of data granularity, how data is grouped

rev
gross, net (optional) Default: net Example: gross
attr_model
linear, `full_impact`, `first_click`, `first_optin`, `reoptin`, `last_click` (optional) Default: linear Example: linear

Attribution model

channel
'overall', 'google', 'facebook', 'ads', 'organic', 'tiktok', 'pinterest', 'snapchat', 'sms', 'etc.' (optional) Example: overall

optional filter to show data only for specific channel

source
string (optional) Example: test

optional filter to show data only for specific utm_source

medium
string (optional) Example: ppc

optional filter to show data only for specific utm_medium

campaign
string (optional) Example: test

optional filter to show data only for specific utm_campaign

content
string (optional) Example: test

optional filter to show data only for specific utm_content

term
string (optional) Example: test

optional filter to show data only for specific term

campaignid
string (optional) Example: 12345678901111

optional filter to show data only for specific campaign ID (applicable for Google Ads and Facebook Ads campaigns)

adsetid
string (optional) Example: 1234567890846

optional filter to show data only for specific adset ID (applicable for Facebook Ads adsets)

adgroupid
string (optional) Example: 12345678951

optional filter to show data only for specific adset ID (applicable for Google Ads adgroups)

Fetch response for specific request

GET https://api.wickedreports.com/async/results/cf0e618?limit=1&next=1
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "results": {
    "id": "cf0e618",
    "data": [
      {
        "channel": "Facebook",
        "source": "",
        "medium": "",
        "campaignId": "",
        "campaign": "",
        "content": "",
        "adGroupId": "",
        "adId": "",
        "term": "",
        "adSetId": "",
        "creativeId": "",
        "ROAS": 0,
        "attributedROI": 92.23,
        "avgOrderValue": "",
        "date": "2021-05-01",
        "costs": 757.58,
        "revenue": 69114.02,
        "clicks": 136,
        "newLeads": 1,
        "reEngagedLeads": 1,
        "nonsubscriptionSales": 100,
        "newCustomerCount": 691,
        "repeatCustomerCount": 0,
        "CAC": 757.58,
        "allCustomerAcquisitionCost": 757.58,
        "LTV": 0,
        "attributionModalSales": 0,
        "attributionModalRevenue": 0,
        "facebookViewThroughConversions": 0,
        "facebookViewThroughRevenue": 0,
        "totalAttributedSales": 0,
        "totalAttributedRevenue": 0,
        "firstClickDate": "2021-05-01",
        "lastClickDate": "2021-05-01",
        "allCustomerCount": 691,
        "CPL": 757.58,
        "wickedAttributedSales": 90,
        "wickedAttributedRevenue": 50,
        "avgDaysFromLastClick": 1,
        "earningsPerClick": 58,
        "earnPerLead": 78,
        "newSubscriptionSales": 234,
        "recurringSubscriptionSales": 123
      }
    ]
  },
  "meta": {
    "page": "2",
    "limit": "1000",
    "pageResults": "1000",
    "next": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "error"
      ]
    },
    "results": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "channel": {
                "type": "string"
              },
              "source": {
                "type": "string"
              },
              "medium": {
                "type": "string"
              },
              "campaignId": {
                "type": "string"
              },
              "campaign": {
                "type": "string"
              },
              "content": {
                "type": "string"
              },
              "adGroupId": {
                "type": "string"
              },
              "adId": {
                "type": "string"
              },
              "term": {
                "type": "string"
              },
              "adSetId": {
                "type": "string"
              },
              "creativeId": {
                "type": "string"
              },
              "ROAS": {
                "type": "number"
              },
              "attributedROI": {
                "type": "number"
              },
              "avgOrderValue": {
                "type": "string"
              },
              "date": {
                "type": "string"
              },
              "costs": {
                "type": "number"
              },
              "revenue": {
                "type": "number"
              },
              "clicks": {
                "type": "number"
              },
              "newLeads": {
                "type": "number"
              },
              "reEngagedLeads": {
                "type": "number"
              },
              "nonsubscriptionSales": {
                "type": "number"
              },
              "newCustomerCount": {
                "type": "number"
              },
              "repeatCustomerCount": {
                "type": "number"
              },
              "CAC": {
                "type": "number"
              },
              "allCustomerAcquisitionCost": {
                "type": "number"
              },
              "LTV": {
                "type": "number"
              },
              "attributionModalSales": {
                "type": "number"
              },
              "attributionModalRevenue": {
                "type": "number"
              },
              "facebookViewThroughConversions": {
                "type": "number"
              },
              "facebookViewThroughRevenue": {
                "type": "number"
              },
              "totalAttributedSales": {
                "type": "number"
              },
              "totalAttributedRevenue": {
                "type": "number"
              },
              "firstClickDate": {
                "type": "string"
              },
              "lastClickDate": {
                "type": "string"
              },
              "allCustomerCount": {
                "type": "number"
              },
              "CPL": {
                "type": "number"
              },
              "wickedAttributedSales": {
                "type": "number"
              },
              "wickedAttributedRevenue": {
                "type": "number"
              },
              "avgDaysFromLastClick": {
                "type": "number"
              },
              "earningsPerClick": {
                "type": "number"
              },
              "earnPerLead": {
                "type": "number"
              },
              "newSubscriptionSales": {
                "type": "number"
              },
              "recurringSubscriptionSales": {
                "type": "number"
              }
            },
            "required": [
              "channel",
              "date",
              "firstClickDate",
              "lastClickDate"
            ]
          }
        }
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "page": {
          "type": "string"
        },
        "limit": {
          "type": "string"
        },
        "pageResults": {
          "type": "string"
        },
        "next": {
          "type": "boolean"
        }
      }
    }
  }
}

Fetch response for specific request
GET/async/results/{resultId}{?limit,next}

You can use this endpoint to get a result for request to /async/channels endpoint.

URI Parameters
HideShow
resultId
string (required) Example: cf0e618

The id of the result to retrieve. This could be received from any outbound endpoint.

limit
number (optional) Default: 1000 Example: 1

Number of orders to return with a single call (max: 1000).

next
0, 1 (optional) Example: 1

A number indicating whether you need to go to the next page or to the very first page. Pass 1 if you need the next page, and 0 if you do not need next. Passing 0 and omitting this field causes the same behaviour.

Outbound Async FunnelVision

You can use this endpoint to pull FunnelVision data for a provided date range.

Get FunnelVision data

GET https://api.wickedreports.com/async/funnelvision?from=2021-05-01&to=2021-05-02&channel=overall&source=test&medium=ppc&campaign=test&campaignId=12345678901111&content=test&term=test&adSetId=1234567890846&adGroupId=12345678951&level=channel&rev=gross&ignoreOrganicClicks=yes&revenueBreakdownMode=full&topOfFunnelWindowDefinition=contactCreation&middleOfFunnelDays=20&bottomOfFunnelDays=5&fbConfidenceScore=20
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "resultId": "cf0e618"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "error"
      ]
    },
    "resultId": {
      "type": "string"
    }
  }
}

Get FunnelVision data
GET/async/funnelvision{?from,to,channel,source,medium,campaign,campaignId,content,term,adSetId,adGroupId,level,rev,ignoreOrganicClicks,revenueBreakdownMode,topOfFunnelWindowDefinition,middleOfFunnelDays,bottomOfFunnelDays,fbConfidenceScore}

You can use this endpoint to pull FunnelVision data for a provided date range.

URI Parameters
HideShow
from
string (required) Example: 2021-05-01

The start date of the FunnelVision data period. Format: YYYY-MM-DD

to
string (required) Example: 2021-05-02

The end date of the FunnelVision data period. Format: YYYY-MM-DD

level
сhannel, сampaign, adset/adgroup, adname/keyword (optional) Example: channel

level of data granularity, how data is grouped

rev
gross, net (optional) Default: net Example: gross
channel
'overall', 'google', 'facebook', 'ads', 'organic', 'tiktok', 'pinterest', 'snapchat', 'sms', 'etc.' (optional) Example: overall

optional filter to show data only for specific channel

source
string (optional) Example: test

optional filter to show data only for specific utm_source

medium
string (optional) Example: ppc

optional filter to show data only for specific utm_medium

campaign
string (optional) Example: test

optional filter to show data only for specific utm_campaign

content
string (optional) Example: test

optional filter to show data only for specific utm_content

term
string (optional) Example: test

optional filter to show data only for specific term

campaignId
string (optional) Example: 12345678901111

optional filter to show data only for specific campaign ID (applicable for Google Ads and Facebook Ads campaigns)

adSetId
string (optional) Example: 1234567890846

optional filter to show data only for specific adset ID (applicable for Facebook Ads adsets)

adGroupId
string (optional) Example: 12345678951

optional filter to show data only for specific adset ID (applicable for Google Ads adgroups)

ignoreOrganicClicks
yes, no (optional) Example: yes

optional filter to ignore organic clicks

revenueBreakdownMode
full, linear (optional) Example: full

revenue breakdown mode value

topOfFunnelWindowDefinition
contactCreation, firstClick (optional) Example: contactCreation

top of funnel window definition value

middleOfFunnelDays
number (optional) Example: 20

middle of funnel window definition value

bottomOfFunnelDays
number (optional) Example: 5

bottom of funnel window definition value

fbConfidenceScore
number (optional) Example: 20

facebook confidence score value

Fetch response for specific request

GET https://api.wickedreports.com/async/results/cf0e618?limit=1&next=1
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "results": {
    "id": "2952b0f",
    "data": [
      {
        "channel": "test",
        "source": "test",
        "medium": "test",
        "campaign": "test",
        "content": "some",
        "term": "test",
        "campaignID": "null",
        "adsetID": "null",
        "adId": "null",
        "adGroupID": "null",
        "creativeID": "null",
        "costs": 0,
        "totalSales": 0,
        "totalRevenue": 0,
        "returnOnInvestment": 0,
        "returnOnAdSpend": 0,
        "newLeads": 0,
        "reEngagedLeads": 0,
        "totalLeads": 0,
        "costPerLead": 0,
        "costPerClick": 0,
        "facebookDateCreated": "null",
        "facebookStatus": "null",
        "facebookWebsiteAddToCart": 0,
        "facebookMetaAddToCart": 0,
        "facebookCostPerAddToCart": 0,
        "facebookWebsitePurchases": 0,
        "facebookWebsitePurchaseConversion": 0,
        "facebookMetaPurchases": 0,
        "facebookMetaPurchaseConversion": 0,
        "facebookWebsitePurchaseReturnOnAdSpend": 0,
        "facebookImpressions": 0,
        "facebookCostPerThousandImpressions": 0,
        "facebookOutboundClicks": 0,
        "facebookOutboundClickThroughRate": 0,
        "facebookCostPerOutboundClick": 0,
        "topOfFunnelSales": 0,
        "topOfFunnelRevenue": 0,
        "topOfFunnelReturnOnInvestment": 0,
        "topOfFunnelReturnOnAdSpend": 0,
        "middleOfFunnelSales": 0,
        "middleOfFunnelRevenue": 0,
        "middleOfFunnelReturnOnInvestment": 0,
        "middleOfFunnelReturnOnAdSpend": 0,
        "bottomOfFunnelSales": 0,
        "bottomOfFunnelRevenue": 0,
        "totalBottomOfFunnelSales": 0,
        "totalBottomOfFunnelRevenue": 0,
        "bottomOfFunnelReturnOnInvestment": 0,
        "bottomOfFunnelReturnOnAdSpend": 0,
        "facebookViewThroughConversions": 0,
        "facebookViewThroughRevenue": 0,
        "newCustomers": 0,
        "repeatCustomers": 0,
        "totalCustomers": 0,
        "customerAcquisitionCost": 2147483648,
        "allCustomerCustomerAcquisitionCost": 2147483648,
        "lifeTimeValue": 0,
        "earningsPerClick": 0,
        "earnPerLead": 0,
        "firstClickDate": "2016-09-13T00:00:00.000Z",
        "lastClickDate": "2023-10-08T00:00:00.000Z",
        "nonSubscriptionSales": 0,
        "newSubscriptionRevenue": 0,
        "recurringSubscriptionSales": 0,
        "date": "2023-06-10 00:00:00"
      }
    ]
  },
  "meta": {
    "page": "2",
    "limit": "1000",
    "pageResults": "1000",
    "next": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success",
        "error"
      ]
    },
    "results": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "channel": {
                "type": "string",
                "description": "channel (string),"
              },
              "source": {
                "type": "string",
                "description": "source (string),"
              },
              "medium": {
                "type": "string",
                "description": "medium (string),"
              },
              "campaign": {
                "type": "string",
                "description": "campaign (string),"
              },
              "content": {
                "type": "string",
                "description": "content (string),"
              },
              "term": {
                "type": "string",
                "description": "term (string),"
              },
              "campaignID": {
                "type": "string"
              },
              "adsetID": {
                "type": "string"
              },
              "adId": {
                "type": "string"
              },
              "adGroupID": {
                "type": "string"
              },
              "creativeID": {
                "type": "string"
              },
              "costs": {
                "type": "number"
              },
              "totalSales": {
                "type": "number"
              },
              "totalRevenue": {
                "type": "number"
              },
              "returnOnInvestment": {
                "type": "number"
              },
              "returnOnAdSpend": {
                "type": "number"
              },
              "newLeads": {
                "type": "number"
              },
              "reEngagedLeads": {
                "type": "number"
              },
              "totalLeads": {
                "type": "number"
              },
              "costPerLead": {
                "type": "number"
              },
              "costPerClick": {
                "type": "number"
              },
              "facebookDateCreated": {
                "type": "string"
              },
              "facebookStatus": {
                "type": "string"
              },
              "facebookWebsiteAddToCart": {
                "type": "number"
              },
              "facebookMetaAddToCart": {
                "type": "number"
              },
              "facebookCostPerAddToCart": {
                "type": "number"
              },
              "facebookWebsitePurchases": {
                "type": "number"
              },
              "facebookWebsitePurchaseConversion": {
                "type": "number"
              },
              "facebookMetaPurchases": {
                "type": "number"
              },
              "facebookMetaPurchaseConversion": {
                "type": "number"
              },
              "facebookWebsitePurchaseReturnOnAdSpend": {
                "type": "number"
              },
              "facebookImpressions": {
                "type": "number"
              },
              "facebookCostPerThousandImpressions": {
                "type": "number"
              },
              "facebookOutboundClicks": {
                "type": "number"
              },
              "facebookOutboundClickThroughRate": {
                "type": "number"
              },
              "facebookCostPerOutboundClick": {
                "type": "number"
              },
              "topOfFunnelSales": {
                "type": "number"
              },
              "topOfFunnelRevenue": {
                "type": "number"
              },
              "topOfFunnelReturnOnInvestment": {
                "type": "number"
              },
              "topOfFunnelReturnOnAdSpend": {
                "type": "number"
              },
              "middleOfFunnelSales": {
                "type": "number"
              },
              "middleOfFunnelRevenue": {
                "type": "number"
              },
              "middleOfFunnelReturnOnInvestment": {
                "type": "number"
              },
              "middleOfFunnelReturnOnAdSpend": {
                "type": "number"
              },
              "bottomOfFunnelSales": {
                "type": "number"
              },
              "bottomOfFunnelRevenue": {
                "type": "number"
              },
              "totalBottomOfFunnelSales": {
                "type": "number"
              },
              "totalBottomOfFunnelRevenue": {
                "type": "number"
              },
              "bottomOfFunnelReturnOnInvestment": {
                "type": "number"
              },
              "bottomOfFunnelReturnOnAdSpend": {
                "type": "number"
              },
              "facebookViewThroughConversions": {
                "type": "number"
              },
              "facebookViewThroughRevenue": {
                "type": "number"
              },
              "newCustomers": {
                "type": "number"
              },
              "repeatCustomers": {
                "type": "number"
              },
              "totalCustomers": {
                "type": "number"
              },
              "customerAcquisitionCost": {
                "type": "number"
              },
              "allCustomerCustomerAcquisitionCost": {
                "type": "number"
              },
              "lifeTimeValue": {
                "type": "number"
              },
              "earningsPerClick": {
                "type": "number"
              },
              "earnPerLead": {
                "type": "number"
              },
              "firstClickDate": {
                "type": "string"
              },
              "lastClickDate": {
                "type": "string"
              },
              "nonSubscriptionSales": {
                "type": "number"
              },
              "newSubscriptionRevenue": {
                "type": "number"
              },
              "recurringSubscriptionSales": {
                "type": "number"
              },
              "date": {
                "type": "string"
              }
            },
            "required": [
              "facebookDateCreated",
              "firstClickDate",
              "lastClickDate",
              "date"
            ]
          }
        }
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "page": {
          "type": "string"
        },
        "limit": {
          "type": "string"
        },
        "pageResults": {
          "type": "string"
        },
        "next": {
          "type": "boolean"
        }
      }
    }
  }
}

Fetch response for specific request
GET/async/results/{resultId}{?limit,next}

You can use this endpoint to get a result for request to /async/funnelvision endpoint.

URI Parameters
HideShow
resultId
string (required) Example: cf0e618

The id of the result to retrieve. This could be received from any outbound endpoint.

limit
number (optional) Default: 1000 Example: 1

Number of orders to return with a single call (max: 1000).

next
0, 1 (optional) Example: 1

A number indicating whether you need to go to the next page or to the very first page. Pass 1 if you need the next page, and 0 if you do not need next. Passing 0 and omitting this field causes the same behaviour.

Generated by aglio on 27 Nov 2023