Import data

Getting your data into MarketHype is one of the first things you need to do in order to properly take advantage of the application. Customer data, purchase history and marketing consents are all important to run a successful marketing operation for your organization.

For convenience, MarketHype provides a range of ready-made integrations for data ingestion from external sources. If you want to import data from any of the supported sources, using a ready-made integration is usually the easiest way to go. However, if you want to build your own integration, or import data from other sources, the Data Ingestion API is the way to go.

Import follow up

Importing data to your MarketHype account is an asynchronous operation. Whenever you send data to MarketHype through the JSON API an import process will be started. The import process will do a number of things with the data you send - validation, normalization, extending it with additional data, map it to existing data, index it for filtering and segmentation etc., which might take a few moments. To not leave you waiting, each import process is assigned an ID, which you can use later on to follow up on progress.

With your import process ID, you can call the API to get a complete report for the import process, including current status, success / error count and a detailed list of any error that might have occurred within your data.

Let's say you've started a new import process, and the import process was assigned id 123. To get the current status of that process, you would call the API:

curl -X 'GET' \
  'https://api.markethype.io/ingestion/v1/imports/123' \
  -H 'accept: application/json' \
  -H 'X-API-TOKEN: YOUR-API-TOKEN'

The import report is always up to date and will reflect the current status of your import process.

{
  "id": "123",
  "createdAt": "2021-04-26T07:11:41.884Z",
  "status": "FINISHED",
  "successCount": 99,
  "errorCount": 1,
  "errors": [
    {
      "index": 55,
      "code": 1000,
      "message": "Too little information"
    }
  ]
}

The import process have three statuses:

Status	Description
CREATED	We've received your data, but have not yet started processing it.
STARTED	We are currently processing your data. The report will be updated as we progress.
FINISHED	We've processed all your data. The report now contain a complete result of success and errors.

The import report will contain a successCount and an errorCount describing how many items were successfully imported and how many contained errors. While we are processing your data - status STARTED, the success and error count will increment as the process progress. When the import process receive status FINISHED that combined success and error count will match the number of items included in your import process.

For any error that occur, a more detailed error report will be included, describing which item caused the error and what the error was.

NOTICE

An imported item that causes an error will be ignored completely during the import process. To import the item, correct the described error and send the correct data as part of a new import process.

Input errors

The import report will contain an error object for each item that caused an error.

{
  "index": 55,
  "code": 1000,
  "message": "Too little information"
}

The index field refers to the row number of the erroneous index of the item. The first item in the import process will have index 0, the second item will have index 1 and so on.

The error object will contain an error code and a message describing the error. This is a list of all input error codes the import report may contain.

Code	Message	Description
1000	Too little information	The input contained too little information to create a valid entity.
1001	Invalid custom attribute	The input contained unknown custom attribute(s) or the custom attributes were of incorrect type
1002	Invalid values	The input contained values that couldn't be parsed to correct data type.
1003	Invalid values	The emails or phone numbers values that are being blocked by specific organization
1004	PackageId referenced an non existing packageItem	The input contained an item with packageId but no package was found inside the same order with this id
1010	No contact found	The input referred to an email or phone that does not exist on any contact

Order Data

An order may detailed order information, including order item specifications, but also customer information that is mapped to your contact database. In MarketHype we separate order items by type - the API currently support BOOKING, PRODUCT, TICKET and PACKAGE. An order may contain as many order items as you need, and can contain a mix of bookings, tickets, packages and products.

An order item of type BOOKING could be anything from hotel room reservation, to a restaurant, SPA-treatment reservation or a train ride (basically anything that is time-based). In order to separate the different types of bookings, you should use the bookingType field. This field may have one of the following values: ACCOMMODATION, TRANSPORT, ACTIVITY, if no value is set ACCOMMODATION will be used.

An order item of type PRODUCT is usually a physical product - a bottle of wine, a gift card, a team scarf, or something else you might be selling.

An order item of type TICKET could be a ticket to a sporting event, a concert or a theatre, really any event with tickets.

An order item of type PACKAGE is a package that can contain the price/cost any of the previous items, meaning that a PACKAGE should always be accompanied by the items it contains. The items in the order that the package contains should have the field packageId with the value of the id in the PACKAGE, more information on the PACKAGE order item type and packageId can be found here.

Depending on its type, an order item can specify slightly different attributes - please refer to the Schemas section of the API Specification for a complete list of attributes that can be specified for each type.

Conflict Strategy

The import pipeline currently provides three conflict strategies, to support various use cases depending on how your solutions works.

Strategy	Description
IGNORE	If an order with the same order ID already exist in your database, the order included in your data will be ignored.
REPLACE	If an order with the same order ID already exist in your database, the order included in your data will replace the order in the database.
MERGE	If an order with the same order ID already exist in your database, the order included in your data will merge with the order in the database. This strategy requires there to be an externalOrderId on all orders and an externalOrderItemId on each orderItem.

Package order item type

An order item of type PACKAGE is a package that can contain the price/cost any of the previous items, meaning that a PACKAGE should always be accompanied by the items it contains. For instance; for a spa-weekend PACKAGE the entire order could contain a PACKAGE, multiple BOOKING items where one could be the actual room reservation and the others could be activties in the spa-hotel such as dinner, massage, tennis-court booking, etc.

Addtionally the cost of the items in the package should exist on either the package itself or the items in the order. If the price is included on both the package and the items from the package in the order, the entire order value will be more than what was actually paid.

packageId

In order to keep track of what items are connected to a package, we use the field packageId. When present on any item in an order the Ingestion API will validate that there is also a PACKAGE with this id value in the same order.