shell

Introduction

Intempt API allows developers to integrate Ecommerce platforms, CRMs and POS machines with Intempt real-time segmentation platform.

Base URL: https://api.intempt.com/

curl "https://api.intempt.com/

Example response:

{
  "service": "metadata",
  "version": "v1",
  "status": "ok",
  "_links": {
    "sources": {
      "href": "https://api.intempt.com/v1/playground/sources/"
    },
    "collections": {
      "href": "https://api.intempt.com/v1/playground/collections/"
    }
  }
}

Sending a request to the root URL will return API details.

HTTP request

GET https://api.intempt.com

Authentication

Intempt uses API keys to authorize API access. To get a hold of an API key, you will first need to log in to Intempt's Console.

Navigate to the edit view of an existing Source or create a new one.

The API key will be located in the Source configuration object.

Intempt expects the API key to be included in all API requests in a header that looks like the following:

Authorization: ApiKey <YOUR_API_KEY>

Sources

An Intempt Source represents the integration of Intempt with one of the supported platforms (Shopify, HubSpot, Magento, POS system, etc.) or a client's website/mobile app. You can find all the sources listed at https://app.intempt.com under Data -> Sources. A Source's type can be picked from the listed categories below:

  1. Web tracker - for tracking all data flowing through your website.
  2. iOS App - for tracking all data flowing through your iOS Application.
  3. Proximity iOS tracker - for tracking proximity beacon data through iOS Application.
  4. API source - for creating custom collections, relations, identifiers etc. from scratch as they are created by default in other sources for you.

Collections

Collections describe schemas for data of a certain type, while collection data items represent specific pieces of data in that collection.

To put that in relational terms, collections are tables that describe columns (types, constraints, etc.), and collection data items are rows of values for those columns.

For example, collections can be created for:

Before putting data in collection you should define its keys. Primary key is required before data insertion.

There are two types of keys that can be put on collection's field: * Primary Key - shows a field that uniquely specify a data item. * Foreign Key - shows a field that refers to the primary key of another collection.

After creating a collection, defining its keys and identifiers use the collection data endpoints to store and retrieve actual data items.

Intempt platform collection schemas should comply to Apache Avro spec

Collection Data

Collection data endpoint is for working with the data items in a collection.

Before storing data items, you will need to create a collection with a schema for this particular type of data. Also, after you create a collection and before you store data items to your collection, your collection must have an identifier.

Retrieve a data item

curl "https://api.intempt.com/v1/your-org/collections/collection-id/data/data-item-id"
  -H "Authorization: ApiKey <YOUR_API_KEY>"

Example response:

{
    "collId": 19554189106348032,
    "id": 24663674875432960,
    "data": {
        "id": 4,
        "bookingDate": -1,
        "guestId": 2,
        "roomId": 10
    },
    "matches": [],
    "_links": {
        "self": {
            "href": "https://api.intempt.com/v1/intempt-test/collections/19554189106348032/data/24663674875432960"
        }
    }
}

This endpoint retrieves a specific data item.

HTTP Request

GET https://api.intempt.com/v1/your-org/collections/<ID>/data/<DATA-ITEM-ID>

URL Parameters

Parameter Description
ID The ID of the collection to retrieve data from
DATA-ITEM-ID The ID of the data item to retrieve

Success Response

This call will return an array of collection objects that contain id, collId, data, matches properties, alongside with child _links object.

collId property shows which collection this data item belongs to.

data is actual data payload.

In the _links object self points to the collection data item itself.

Delete a data item

curl "https://api.intempt.com/v1/your-org/collections/194123921/data/24663674875432960"
  -X DELETE
  -H "Authorization: ApiKey <YOUR_API_KEY>"

This endpoint deletes a specific collection data item.

HTTP Request

DELETE https://api.intempt.com/v1/your-org/collections/<ID>/data/<DATA-ITEM-ID>

URL Parameters

Parameter Description
ID The ID of the collection to delete data item from
DATA-ITEM-ID The ID of the data item to delete

Success Response

On successful delete, the deleted collection will be sent in the response.

List all data items

curl "https://api.intempt.com/v1/your-org/collections/19554189106348032/data"
  -H "Authorization: ApiKey <YOUR_API_KEY>"

Example response:

{
  "_embedded": {
    "dataItemList": [
      {
        "collId": 19554189106348032,
        "id": 24665844119130112,
        "data": {
          "id": 2,
          "dateFrom": "2019-10-25",
          "dateTo": "2019-12-25",
          "guestId": 123123213,
          "roomId": 312312312
        },
        "matches": [],
        "_links": {
          "self": {
              "href": "https://api.intempt.com/v1/your-org/collections/19554189106348032/data/24665844119130112"
          }
        }
      },
      {
        "collId": 19554189106348032,
        "id": 24663674875432960,
        "data": {
          "id": 4,
          "bookingDate": -1,
          "guestId": 2,
          "roomId": 10
        },
        "matches": [],
        "_links": {
          "self": {
              "href": "https://api.intempt.com/v1/your-org/collections/19554189106348032/data/24663674875432960"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.intempt.com/v1/your-org/collections/19554189106348032/data"
    }
  }
}

This endpoint retrieves all data items for selected collection.

In current example, this call retrieves all room booking records.

HTTP Request

GET https://api.intempt.com/v1/your-org/collections/19554189106348032/data

Success Response

This call will return an array of collection objects that contain id, collId, data, matches properties, alongside with child _links object.

collId property shows which collection this data item belongs to.

data is actual data payload.

In the _links object self points to the collection data item itself.

The root _links object's self property points to the list of data items.

Keys and Identifiers

Keys and Identifiers are very important part of Intempt app. They are used to identify the specific data item and to find or create the relation between two or more data items. All keys and Identifiers can be easily set using Intempt's app in source schema editor (Sources -> Pick a specific source -> Schema). They also can be set only on top level fields.

Keys

Primary Key

Primary key is a unique identifier for data item so any duplicate with same value for this key will be overwritten. Collection can have only one primary key. Primary key is mandatory for collection to insert any data item into it.

Foreign Key

Foreign key is identifier that used to link two collection together. Foreign key can be set on any field of collection, if type of that field matches type of primary key of related collection. So it's mandatory to set primary keys first to set foreign keys after that.

Relations

Relation is additional setting for foreign key that allows you to set a custom name of foreign key and use it in event editor to generate events based on related data item fields. One collection can have any amount of foreign identifiers.

Identifiers

Profile identifier

Profile identifier helps to identify profiles in one source. Profile is a bunch of information about user collected in one source. User can have multiple profiles that shows full picture of your customers. Example of profile identifier for one source is visitor ID or session ID, all data collected during that visit or session is related to one user, but can't fully describe that user.

Source can have one profile identifier (fieldName should be same), but you can set it to multiple collections. So all data items to collections with that profile identifier will be connected to one user.

Only collections with profile identifier can be used in event editor. If collection don't have profile identifier it can't be used as event, and you can't add user identifier and user attribute on it, because it's impossible to connect data from that collection to any user. Example of collections like that can be Rooms in hospitality source or Devices in proximity source.

User identifier

User identifier helps to identify user across all sources in your organization. So all attributes of that user will be in connected to one exact user. Usually as user identifiers we use email or phone. So all profiles from all sources with same user identifier values will be merged into one user.

To add user identifier collection should have profile identifier. One collection can have any amount of user identifiers.

Main difference between user attribute and user identifier is that user identifier value is unique for every user, but user attribute values can be same for different users. For example, user identifier - email, user attribute - location.

Attributes

Attributes is a set of data related to one user that shows valuable information for that user. In Intempt's app you can create custom user attributes easily using source schema editor (Sources -> Pick a specific source -> Schema). In schema editor you need to pick a field which you want to be a user attribute and create it by checking appropriate box. This will collect data from that specific field. User attribute data can be collected across multiple sources to create a full user description. Remember that you can't create user attribute on collection that don't have a profile identifier on it.

In Attributes page you can edit next properties of your user attributes:

Merge Strategies

There is 4 merge strategies defined for attributes.

Title Meaning
First used value Shows only first used value for user
Most recent value Shows last used value, the most recent ones for user
Most frequently used value Shows the most frequently used value
All used values Shows all unique used values (won't show duplicates)

If you decide to change merging strategy for some attribute you can instantly see changes in Users page.

Data ingestion



A data item describes an atomic state of a particular object concerning a specific property at a certain time point. For example, data item for collection clicks contains main information about a click that was done by web page visitor like page, HTML element, visitor ID, IP address, timestamp, URL, etc. That kind of data can be used for events matching, segmentation and full user experience for your customers.

User can freely create additional collections to any predefined sources. For example, web tracker can additionally have collections with user discounts card information, user total spent information, abandoned cart, etc.

To ingest data item you need to have created collection and defined primary key for that collection.

Ways to ingest data

Intempt provides multiple way of data ingestion. Here are a list of all possible ways to do that: 1. Using Intempt's web, iOS, proximity tracker (used in sources with type web, ios, proximity). 2. Using scheduled integrated source (like Shopify or Hubspot). 3. Using default API calls (can be used for every source). 4. Uploading CSV file for certain collection (can be used for every source).

Collections data API call

You can use collections data endpoint to insert one data item to that collection. This type of ingestion can be applied to any type of source.

curl "https://api.intempt.com/v1/{org-name}/collections/{id}/data"
  -X POST
  -H "Authorization: ApiKey <YOUR_API_KEY>"
  --data-raw '{"visitorId":"194jso4nfja-fanjs-1584","identifier":"yaroslav@intempt.com"}'

Response code on success: 201 CREATED

HTTP Request

POST https://api.intempt.com/v1/{org-name}/collections/{id}/data

Body

Body should contain JSON formatted data for collection to which you insert this data item. Key should be field name, value should match field type. If you have conflicting data types in one union (for example ["string", "long", "double"]) you should wrap value to confirm data type: {"fieldName": {"double":3.14}}. There is no need to wrap data if you use nullable fields like ["null", "long"]. Nested fields, arrays, maps should be created in usual JSON formatted way. Fields can appear in any order, fields that are not presented in collection's schema will be ignored.

URL Parameters

Parameter Description
ID The ID of the collection to ingest data in

Success Response

On a successful call, you will get 201 CREATED response.

Sources data API call

You can use sources data endpoint to insert multiple data items to one or more collections of that source. This type of ingestion can be applied to any type of source.

curl "https://api.intempt.com/v1/{org-name}/sources/{id}/data"
  -X POST
  -H "Authorization: ApiKey <YOUR_API_KEY>"
  --data-raw '{"profile":[{"visitorId":"194jso4nfja-fanjs-1584","identifier":"yaroslav@intempt.com"},
  {"visitorId":"194jso4nfja-fanjs-1584","identifier":"yaroslav@intempt.com"}]}'

Response code on success: 201 CREATED

HTTP Request

POST https://api.intempt.com/v1/{org-name}/sources/{id}/data

Body should contain JSON formatted data in next pattern: 

{
  "collectionName1": [
    {
      "field1": "value1",
      "field2": "value2"
    },
    {
      "field1": "value3",
      "field2": "value4"
    }
  ],
  "collectionName2": [
    {
      "field3": "value5",
      "field4": "value6"
    },
    {
      "field3": "value7",
      "field4": "value8"
    }
  ]
}

You can insert any amount of data items to any amount of collections in that source.

URL Parameters

Parameter Description
ID The ID of the source to ingest data in

Success Response

On a successful call, you will get 201 CREATED response.

Using CSV file

Visualized process to upload CSV file to process shown on next image:

s3.png

You can insert any amount of data items to one collection using that type of data ingestion. This type of ingestion can be applied to any type of source.

To upload CSV file for some collection you need to generate the link to upload file to s3 bucket. To generate that link use next request:

curl "https://api.intempt.com/v1/{org-name}/collections/{id}/data"
  -X POST
  -H "Authorization: ApiKey <YOUR_API_KEY>"
  -H "Content-Type: text/csv"

Response code on success: 307 TEMPORARY REDIRECT

HTTP Request

POST https://api.intempt.com/v1/{org-name}/collections/{id}/data Request should not have body and should have Content-Type header set to test/csv.

URL Parameters

Parameter Description
ID The ID of the collection to ingest data in

Success Response

On a successful call, you will get 307 TEMPORARY REDIRECT response.

On success, you will receive response with code 307 TEMPORARY REDIRECT and in header Location you can find s3 upload URL. Now you can do PUT request to that link to send the file to process.

CSV file

First line of csv file should have field names.

Example of CSV file

fieldName1,fieldName2,fieldName3
value1,3.1415,true
value2,1.16,false

Events

Events are flexible, configurable entity, that shows that something happen to customer's user(s).

Technically events are data items of specific collection that matches some defined filter. This filter can be complex and defined using our Event Editor.

We follow the concept called "sum of product".

You can define complex filters by pressing + button on filter flow, that will allow you to create new and or or clause.

To trigger event data should come in collection, on which you created event, and this data should meet requirements of specified filter.

Create Event

To create a new event you need to follow next steps:

  1. Press + Create event button

  2. Choose collection on which we want to put event filter

  3. Define a filter

Operators

In event editor you can use next operators to filter collection's fields:

Get matched events

Collection data endpoint is for working with the data items in a collection.

Before storing data items, you will need to create a collection with a schema for this particular type of data. Also, after you create a collection and before you store data items to your collection, your collection must have an identifier.

Get matched events for profile or master id

curl "https://api.intempt.com/v1/org-name/events/matches?profileId={id}"
  -X GET
  -H "Authorization: ApiKey <YOUR_API_KEY>"

Example response:

{
  "masterId": "182233620328374272",
  "profileIds": [
    182233618306719744,
    182233618306719715,
    182233618306771518
  ],
  "matchedEvents": ["newtestevent"],
  "lastUpdated": "2021-01-13T09:09:52.207+00:00",
  "_links": {
    "self": {
      "href": "http://api.intempt.com/v1/org-name/events/matches"
    }
  }
}

Use this request to get matches by profile ID. Remember that masterId or profileId parameters should be specified to see results.

curl "https://api.intempt.com/v1/org-name/events/matches?masterId={id}"
  -X GET
  -H "Authorization: ApiKey <YOUR_API_KEY>"

Example response:

{
  "masterId": "182233620328374272",
  "profileIds": [182233618306719744],
  "matchedEvents": ["newtestevent"],
  "lastUpdated": "2021-01-13T09:09:52.207+00:00",
  "_links": {
    "self": {
      "href": "http://api.intempt.com/v1/org-name/events/matches"
    }
  }
}

HTTP Request

GET https://api.intempt.com/v1/{org-name}/events/matches

URL Parameters

Parameter Description
profileId The ID of the profile to retrieve event matches for
masterId The ID of the user to retrieve event matches for

Success Response

On a successful call, you will see matched events for provided user.

Segment

A segment is a group of users that are labeled as part of a segment by fitting the criteria through the events, user attributes or other segment of a segment. A user joins or leaves a segment based on the defined events, user attributes filters or\and other segments.

You can create new segment on Segment Editor page.

You can define complex filters by pressing + button on filter flow, that will allow you to create new and or or clause.

Create Segment

To create a new segment you need to follow next steps:

  1. Press + Create segment button

  2. Define a filter

Get segmentation

curl "https://api.intempt.com/v1/org-name/segmentations/latest?profileId={id}"
  -X GET
  -H "Authorization: ApiKey <YOUR_API_KEY>"

Example response:

{
  "_embedded": {
    "segmentations": [
      {
        "id": "200382528132874240",
        "masterId": "200382140847620096",
        "profileIds": [
          "200382140415606784"
        ],
        "created": "2021-03-03T12:52:03.723+00:00",
        "_links": {
          "self": {
            "href": "https://api.intempt.com/v1/org-name/segmentations/200382528132874240"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.intempt.com/v1/org-name/segmentations"
    }
  }
}

This request can help you to get the latest segmentation by different parameters.

HTTP Request

GET https://api.intempt.com/v1/{org-name}/segmentations/latest

URL Parameters

To see results next parameters should be provided:

Parameter Description
profileId Get segmentation by profile ID
masterId Get segmentation by master ID
sourceId and profile Get segmentation by source id and value of profile id

To use last option you should define both sourceId and profile parameters. Note: The profile filter only accepts a json object, hence you will need to encode that into url format. You can use this website for example to encode json:

Success Response

On a successful call, you will see segmentation for provided user

shell