Custom Integration¶

Custom Integration (Backend Side) Guide and Restful API

Beta

This integration method is in beta and not recommended for frontend use. Please check other integration methods.

Introduction¶

This tutorial provides a very simple and quick introduction to the Segmentify integration for custom applications by walking you through details of different events. Segmentify has a RESTful API to feed important events like page/product information and visitor actions to the Segmentify Engine.

Integration¶

This guide will help you to integrate different events (visitor actions) and also product recommnendations, engagement campaigns. Integration can be divided into following steps:

Event Types
Event/Request Details
Response Details
User & Session Management
Common Parameters
Page View
Product View
Basket Operations
Checkout Operations
User/Visitor Operations
Custom Event
Interaction
Form/Survey
Banners
Tracking

Event Types¶

Segmentify uses different event types for different visitor actions. You can define following events by using Segmentify RESTful API:

Event	Description	Event Name
Page	It is send when a visitor views a page	PAGE_VIEW
Product	It is send when a visitor views a product	PRODUCT_VIEW
Basket	It is send when a visitor makes a basket action (add product to basket or remove product from basket)	BASKET_OPERATIONS
Checkout	It is send when a visitor makes a checkout action (views basket, enter customer information, enter payment information, finishes purchase)	CHECKOUT
User	It is send when a visitor makes a user action or use this event to update information about customers	USER_OPERATIONS
Custom	It is send when to identify any visitor action that has no predefined value in Segmentify	CUSTOM_EVENT
Interaction	It is send when a visitor makes an interaction like click, view a widget, submit, etc.	INTERACTION
Form	It is send when a visitor submits a form or survey	USER_FORM
Banner	It is send when visitors views or clicks to banners	BANNER_VIEW or BANNER_OPERATIONS

Request Details¶

In order to use Segmentify RESTful API, you must be make POST requests to your data center end point with event details at request body. Request body must be formed as a valid json array.

Segmentify accounts have two important system variables used in integration: API KEY and Data Center. You can access these values from Integrations menu of Segmentify Panel:

System Variable	Description
Api Key	unique Segmentify key value to send events
Data Center	data center end point to send Segmentify events

To access Integrations menu of Segmentify Panel, please login to your Segmentify account and navigate to Settings > Integrations.

Request body should be a json array whose elements are Segmentify events that will be described in the next sections, you can send multiple events with a single request.

Request Endpoint¶

Requests must be made to proper end point. Endpoint url format is like

Request Endpoint Format:

<DATA CENTER URL>/add/events/v1.json?apiKey=<APIKEY>

Data Center Url is account specific and you should use the end point shown at Integrations page under Account Settings.

Example Data Center Url:

https://dce1.segmentify.com

Api Key is your account's unique key to send requests to Segmentify RESTful Api, and you can learn your Api Key from Integrations page under Account Settings

Example Api Key:

XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Proper request end point is changing data center url and api key with your account specific value.

Example Request Endpoint:

https://dce1.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Request Headers¶

Segmentify Restful API is based on json, so headers should match content type and response type.

All request should have the following headers:

Header	Value
Content-Type	application/json
Accept	application/json

Request Body¶

Request body should be a json array whose elements are Segmentify events that will be described in this document.

An example request body will be in this format:

[
    {
        "name": "PAGE_VIEW",
        "userId": "XXXXXXXXXXXXXXXXX",
        "sessionId": "YYYYYYYYYYYYYYYY",
        "device": "IOS",        
        "pageUrl": "http://www.exampleshop.com/",
        "referrer": "http://www.google.com/",
        "category": "Product Page",
        "subCategory": "Men > Sports"        
    },
    {
        "name": "PRODUCT_VIEW",
        "userId": "XXXXXXXXXXXXXXXXX",
        "sessionId": "YYYYYYYYYYYYYYYY",        
        "device": "IOS",
        "productId": "EXAMPLE_PRODUCT_1"        
    }
]

--

Response Details¶

RESTful API returns different status codes to show you status of your request. Summary of status codes are given:

Status Code	Description
200 - OK	Request has reached to Segmentify Server and it is processed. Please check Response Body for details.
400 - Bad Request	The request was unacceptable, often due to wrong request type. You should make a POST request for sending events.
404 - Not Found	The requested resource doesn't exist, often due to illformed request url
429 - Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
5XX - Server Errors	Something went wrong on Segmentify's end.

Response Body¶

Segmentify event requests returns a json object as reponse.

Example format of response body is given below:

{
    "campaigns": [
        [],
        []
    ],
    "responses": [
        [],
        []
    ],
    "timestamp": 1501142345512
}

If request is taken successfully, but there is an error with the request, statusCode variable shows the error. Example format of response body indicating an error is given below:

{
    "timestamp": "",
    "responses": [],
    "statusCode": "NO_DOMAIN_APIKEY_MATCH"
}

Details of response errors are given in secotion API Errors

API Errors¶

If your request body has a field statusCode, then you have an error in your request. Details of errors are given in below table:

Error Code	Description
NO_API_KEY	Your request doesn't have an apiKey parameter, please provide apiKey parameter at the request with your account's unique api key.
NO_ACCOUNT	Given api key is not associated with a Segmentify account, please check your api key value.
UNVERIFIED_ACCOUNT	Account associated with api key is not a verified account. To verify your account, please check your email and verify it.
FAILED_ACCOUNT	Account associated with api key is not an active account. Please contact with support team to re-activate your account.
NO_DOMAIN_APIKEY_MATCH	Each Segmentify account is associated with a domain. Please check your domain and provide at requests with header `Origin`. Check Reqeust Details for required headers.
UNVERIFIED_ACCOUNT	Account associated with api key is not a verified account. To verify your account, please check your email and verify it.
NO_EVENT	There is no events inside request body. You should add at least one event with each request.
NO_USERID	Each Segmentify event should have an `userId` parameter, and at least one event in the request lacks this parameter.
NO_SESSIONID	Each Segmentify event should have an `sessionId` parameter, and at least one event in the request lacks this parameter.
BAD_INPUT	Your request body should be a json array of Segmentify events. It is malformed, please check your json object for validity.

User & Session Management¶

Each event has to have user and session id fields to uniquely identify the user using your store and current session through out the visit.

User and session ids can be generated by Segmentify and new ids can be reached by making GET requests to following url:

<DATA CENTER URL>/get/key?count=<KEY COUNT TO GENERATE>

Data Center Url is account specific and you should use the end point shown at Integrations page under Account Settings.

Example Data Center Url:

https://dce1.segmentify.com

You should ask for one key to just getting key for session id, and ask for two keys to get keys for both user id and session id.

Example Key Generate Request:

GET https://dce1.segmentify.com/get/key?count=1 // for just session id

GET https://dce1.segmentify.com/get/key?count=2 // for both user id and session id

Request Body is a simple array with number of keys you have asked for. Example request body is shown below for two key request:

["XXXXXXXXXXXXXXXXXXXXXXX","YYYYYYYYYYYYYYYYYYYY"]

Alternative approach is creating and using your own unique ids. These ids can be any string, but must be unique for each user and session.

Common Parameters¶

Every event in Segmentify shares common parameters and you can add these parameters to all events that will be defined later.

Details of common parameters for events are given below:

Name	Type	Description	Example
Event (name)	Mandatory	Name of the event. Use one name from Event Types	'PAGE_VIEW' or 'CHECKOUT'
User ID (userId)	Mandatory	Unique id of the user. Please check User & Session Management for creating unique key for the user/visitor. You should send same key for every event of same user and this id must be unique among other users	'USER_1234567890'
Session ID (sessionId)	Mandatory	Unique id of the user session. Please check User & Session Management for creating unique key for the user/visitor session. You should send same key for every event of same user session and this id must be unique among other sessions	'SESSION_1234567890'
Device (device)	Mandatory	Device type of current visitor. Possible Options are: - 'PC' - 'TABLET' - 'MOBILE' - 'ANDROID' - 'IOS'	'PC'
User Agent (userAgent)	Optional	User Agent information of current visitor's browser	'Mozilla/5.0 (iPhone; CPU iPhone OS 9_1 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13B143 Safari/601.1'
Language (lang)	Optional	Type of current visitor's language.Contact us for other languages. Default languages : - 'TR' - 'EN' - 'FR' - 'DE'	'FR'
Currency (currency)	Optional	Currency of product price. Must be in Short Format. If not given, account's currency will be used for the product	'EUR'
Browser (browser)	Optional	Type of current visitor's browser Possible Options are: - 'Chrome' - 'Firefox' - 'Internet Explorer' - 'Microsoft Edge' - 'Safari' - 'Android' - 'Opera' - 'Maxthon' - 'iPhone' - 'iPad'	'Chrome'
Operating System (os)	Optional	Operating System of current visitor. Possible Options are: - 'Windows' - 'Linux' - 'MacOS' - 'Android' - 'iOS' - 'Other'	'MacOS'
Operating System Version (osversion)	Optional	Operating System Version of current visitor.	'10.13.2'
Page Url (pageUrl)	Optional	Url of the current page which the event is generated	'https://www.exampleshop.com/example-product-1/'
Referrer (referrer)	Optional	Referal Url of the current page	'https://www.google.com/'
Parameters (params)	Optional	Custom parameters of the event. Must be in map format	`{'FIELD_1': 'VALUE_1', 'FIELD_2': 'VALUE_2'}`
Test Mode (testMode)	Optional	Test Mode Flag. If event is set to test mode, it will be only processed by campaigns in test mode and discarded in reports. Possible values are 'true' or 'false'	'false'
Next Page Flag (nextPage)	Optional	Next Page Flag. If it is set to next page mode, this event will not be sent now, but will be kept for next page load. Set this flag to true, if page is redirecting and you want to store the event to be sent at next page. Possible values are 'true' or 'false'	'false'

Page View¶

When a visitor views a page, this event should be sent.

Parameters can be sent with page view event is given below (you can also add common parameters):

Name	Type	Description	Example
Category (category)	Mandatory	Category of the Page. Predefined values for Segmentify are: - Home Page - Product Page - Category Page - Basket Page - Checkout Page - Search Page - 404 Page	'Product Page'
Sub Category (subCategory)	Optional	Sub-category of the page. It is used to enhance information about product and category pages. Example: For a sports category listing page, page category should be 'Category Page' and sub category should be 'Men>Shoes>Sports'	'Men>Shoes>Sports'

An example curl request is given below:

curl \
    --url 'https://dce1.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"PAGE_VIEW",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",
        "category":"Home Page”,
        "device":"IOS"
    }
]
BODY

Product View¶

When a visitor views a product, this event should be sent.

If product is also inside a page, don't forget to send a page view event with category 'Product Page' and subCategory product's category too.

Parameters can be sent with product view event is given below (you can also add common parameters):

Name	Type	Description	Example
Product ID (productId)	Mandatory	Unique id of the product	'EXAMPLE_PRODUCT_1'
Title (title)	Mandatory	Name/Title of the product	'EXAMPLE PRODUCT'
Stock (inStock)	Optional	Product’s stock status - either true or false. If not given it is assumed to be in stock ('true')	'true'
Url (url)	Mandatory	Canonical url of the product	'https://www.exampleshop.com/example-product-1/'
Mobile Url (mUrl)	Optional	mobile specific url for the product	'https://m.exampleshop.com/example-product-1/'
Image (image)	Mandatory	main image url to be used in product recommendations	'https://cdn.exampleshop.com/example-product-1.png'
Image X-Small (imageXS)	Optional	very small image url to be used in product recommendations	'https://cdn.exampleshop.com/example-product-1-xs.png'
Image Small (imageS)	Optional	small image url to be used in product recommendations	'https://cdn.exampleshop.com/example-product-1-small.png'
Image Medium (imageM)	Optional	medium image url to be used in product recommendations	'https://cdn.exampleshop.com/example-product-1-medium.png'
Image Large (imageL)	Optional	large image url to be used in product recommendations	'https://cdn.exampleshop.com/example-product-1-large.png'
Image X-Large (imageXL)	Optional	very large image url to be used in product recommendations	'https://cdn.exampleshop.com/example-product-1-xl.png'
Category (category)	Mandatory	Hierarchical category of the product	'Men > Sports > Shoes'
Brand (brand)	Optional	Brand of the product	'EXAMPLE BRAND'
Price (price)	Mandatory	Price of the product, must be numeric	349.99
Old/Sales Price (oldPrice)	Optional	Price of the product before sales	449.99
Currency (currency)	Optional	Currency of product price. Must be in Short Format. If not given, account's currency will be used for the product	'EUR'
Gender (gender)	Optional	Gender of the product. Possible values are 'M', 'F', 'U'	'M'
Colors (colors)	Optional	Different color options of the product. Must be in array format	['black', 'red', 'blue']
Sizes (sizes)	Optional	Different size options of the product. Must be in array format	['small', 'medium', 'large']
Labels (labels)	Optional	Custom labels associated with the product. You can use these labels to filter products in the recommendations. Must be in array format	['top-seller', 'new-comer']

An example curl request is given below:

curl \
    --url 'https://dce1.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"PRODUCT_VIEW",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",
        "device":"TABLET"
        "productId":"EXAMPLE_PRODUCT_1”,
        "title":"Example Product”,
        "inStock":"true”,
        "url":"https://www.exampleshop.com/example-product-1/”,
        "image":"https://cdn.exampleshop.com/example-product-1.png,
        "category":"Men>Sports>Shoes”,
        "brand":"Example Brand,
        "price":349.99,
        "oldPrice":449.99,
        "gender":"M",
        "colors":["black","red","blue"],
        "sizes":["small","medium","large"],
        "labels":["new-comer","top-seller"],
        "params":{
            "field1":"value1",
            "field2":"value2"
        }
    }
]
BODY

Basket Operations¶

Segmentify uses basket operations as intermediary step for measuring success of recommendations throughout the conversion funnel. Basket success rate is also reported by Trendify and Bannerify to show individual performance of products, categories, brands and banners.

Basket operations are similar to page view and product view. There are two possible steps in a basket operation these are: add product to basket, remove product from basket.

Add Product to Basket¶

When a visitor adds a product to basket/cart, this event should be sent.

An example curl request is given below:

curl \
    --url 'https://dce1.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"BASKET_OPERATIONS",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",
        "device":"IOS",
        "step":"add",
        "productId":"EXAMPLE_PRODUCT_1",
        "price":349.99,
        "currency":"EUR",
        "quantity":2
    }
]
BODY

Remove Product from Basket¶

When a visitor removes a product from basket/cart, this event should be sent.

An example curl request is given below:

curl \
    --url 'https://dce1.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"BASKET_OPERATIONS",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",
        "device":"IOS",
        "step":"remove",
        "productId":"EXAMPLE_PRODUCT_1",
        "quantity":1
    }
]
BODY

Basket Event Parameters¶

Parameters can be sent with basket operations event is given below (you can also add common parameters):

Name	Type	Description	Values
Basket Step (step)	Mandatory	Basket operation type. Can be either 'add' or 'remove'	'add'
Product ID (productId)	Mandatory	Unique id of the product. Must match with product ids sent with product view event	'EXAMPLE_PRODUCT_1'
Price (price)	Optional	Price of the product in the basket. If not given, price of the product in product catalogue will be assumed	349.99
Currency (currency)	Optional	Currency of product price. Must be in Short Format. Currency of the product is used if not given	'EUR'
Quantity	Optional	Number of items added to basket at this operation. If not given, it is assumed 1. You can also use decimals for not integer quantities like 2.3	1

Checkout Operations¶

Segmentify uses checkout operations to measure success of recommendations throughout the conversion funnel. Checkout information and steps are also used in email & personalization campaigns. Campaign, Trendify, Bannerify and Sales reports are feed from checkout information. It is essential for both analyitcs and recommendation capabilities to function properly.

Segmentify track four different steps of checkout operation:

Operation	Step	Details
View Basket	basket	When customer views the basket page. Some online stores has dedicated basket pages, others have basket detail pop-ups. For both use cases we recommend you to send checkout event with basket details. To see details, please click
Customer Information	customer	This is the second step on checkout funnel. When customer is entering his personal information details, this event should be send to Segmentify. To see details, please click
Payment Information	payment	When customer is on payment stage of checkout funnel, you should send this event to Segmentify.To see details, please click
Purchase/Success	purchase	Final step of checkout funnel is purchase and Segmentify uses this step as success indicator for recommendations. Reports for campaigns (both recommendation and engagement), sales analysis and real-time analtyics are dependent to this event and shoukd be implemented with great care. To see details, please click

View Basket¶

View Basket is the first step of checkout funnel, and followed by Customer Information.

When a visitor views his/her basket/cart, this event should be sent with basket details.

An example curl request is given below:

curl \
    --url 'https://dce1.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"CHECKOUT",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",
        "device":"ANDROID",
        "step":"basket",
        "totalPrice":999.99,
        "currency":"EUR",
        "cartUrl":"http://www.exampleshop.com/cart/cart-1234567890/"
        "productList":[
            {
                "productId":"EXAMPLE_PRODUCT_1",
                "price":349.99,
                "currency":"EUR",
                "quantity":2
            },
            {
                "productId":"EXAMPLE_PRODUCT_2",
                "price":249.99,
                "currency":"EUR",
                "quantity":1
            }
        ]
    }
]
BODY

Customer Information¶

Customer Information is the second step of checkout funnel, and preceeded by View Basket & followed by Payment Information.

When a visitor enters customer information as second step of checkout funnel, this event should be sent with basket details.

An example curl request is given below:

curl \
    --url 'https://dce1.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"CHECKOUT",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",
        "device":"ANDROID",
        "step":"customer",
        "totalPrice":999.99,
        "currency":"EUR",
        "cartUrl":"http://www.exampleshop.com/cart/cart-1234567890/"
        "productList":[
            {
                "productId":"EXAMPLE_PRODUCT_1",
                "price":349.99,
                "currency":"EUR",
                "quantity":2
            },
            {
                "productId":"EXAMPLE_PRODUCT_2",
                "price":249.99,
                "currency":"EUR",
                "quantity":1
            }
        ]
    }
]
BODY

Please refer to View Basket Step of Checkout for basket products detail and use the same information throughout the purchase funnel by only changing step information.

Payment Information¶

Payment Information is the third step of checkout funnel, and preceeded by Payment Information & followed by Purchase/Success.

When a visitor enters payment information as third step of checkout funnel, this event should be sent with basket details.

An example curl request is given below:

curl \
    --url 'https://dce1.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"CHECKOUT",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",
        "device":"ANDROID",
        "step":"payment",
        "totalPrice":999.99,
        "currency":"EUR",
        "cartUrl":"http://www.exampleshop.com/cart/cart-1234567890/"
        "productList":[
            {
                "productId":"EXAMPLE_PRODUCT_1",
                "price":349.99,
                "currency":"EUR",
                "quantity":2
            },
            {
                "productId":"EXAMPLE_PRODUCT_2",
                "price":249.99,
                "currency":"EUR",
                "quantity":1
            }
        ]
    }
]
BODY

Please refer to View Basket Step of Checkout for basket products detail and use the same information throughout the purchase funnel by only changing step information.

Purchase/Success¶

Purchase/Success is the fourth and final step of checkout funnel, and preceeded by Payment Information.

When a visitor finalizes a purchase, this event should be sent with basket details.

An example curl request is given below:

curl \
    --url 'https://dce1.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"CHECKOUT",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",
        "device":"ANDROID",
        "step":"purchase",
        "totalPrice":999.99,
        "currency":"EUR",
        "productList":[
            {
                "productId":"EXAMPLE_PRODUCT_1",
                "price":349.99,
                "currency":"EUR",
                "quantity":2
            },
            {
                "productId":"EXAMPLE_PRODUCT_2",
                "price":249.99,
                "currency":"EUR",
                "quantity":1
            }
        ]
    }
]
BODY

Please refer to View Basket Step of Checkout for basket products detail and use the same information throughout the purchase funnel by only changing step information.

Checkout Parameters¶

Detailed explanation for each parameter is given below:

Name	Type	Description	Example
Checkout Step (step)	Mandatory	Identifies which step of the checkout funnel. Each step has different meaning and use it accordingly	'basket'
Total Price/Amount (totalPrice)	Mandatory	Total amount of the basket including taxes, shipping costs and also discounts	999.99
Currency (currency)	Optional	Currency of the total amount of the basket. Must be in Short Format. If not given, currency of the account is used	'EUR'
Order No (orderNo)	Optional	Your unique id of the order. Send this value only for purchase/succeess step and you can access to this id on sales report	'ord_XXXXXX'
Cart Url (cartUrl)	Optional	Permalink for accessing basket at later stages. Should be used for view basket, customer information and payment information steps of checkout. This url can be used at engagement campaigns like cart abondonment reminders. Customers will be informed with this url with out-bound channels like email and push messages. If not given, account's default cart url will be used (which can be adjusted from account settings in panel)	'https://www.exampleshop.com/cart/cart-1234567890/'
Products	Mandatory	List of products inside the basket. Must be in array format. Details are given at product parameters	[product1,product2]

Basket Product Parameters¶

Each product inside the basket can be defined with following parameters. See Checkout Parameters for defining checkout operation in which basket product is also defined.

Name	Type	Description	Example
Product ID (productId)	Mandatory	Unique id of the product	'EXAMPLE_PRODUCT_1'
Price	Optional	Price of the product in the basket. If not given, price of the product in the product catalogue will be used	349.99
Currency	Optional	Currency of product price. Must be in Short Format. If not given, currency of the product in the product catalogue will be used	'EUR'
Quantity	Optional	Number of items from current product in the basket. If not given, it is assumed to be 1	1

User/Visitor Operations¶

Segmentify tracks important user operations like sign-up/register, sign-in/login, sign-out/logout and also you can share your customer's information with Segmentify by sending an update event.

There are 4 possible user/visitor operations:

User Register/Sign-up: It should be sent when a visitor signed up to your website, to see details please click
User Login/Sign-in: It should be sent when a registered user logins to your website, to see details please click
User Logout/Sign-out: It should be sent when a registered user logouts from your website, to see details please click
User Update: It should be sent when you want to share registered user's information (ex: name, email, phone number, etc.) with Segmentify. These information can be used at campagin templates to customize message or email address is used for email out-bound campaigns like abandoned cart reminders. To see details please click

New User¶

When a visitor registers (sign-up) to your website, you should send a new user event.

If you want to share details of an already registered user with Segmentify, please use User Update.

Details of parameters of new user is given below:

Name	Type	Description	Example
User Operation (step)	Mandatory	Identifies which operation is taken for current user/customer. Each operation has differen meaning and use it accordingly	'signup'
Username (username)	Mandatory	Unique identifier for the customer	'johndoe'
Full Name (fullName)	Optional	Full name of the customer.	'John Doe'
Email (email)	Optional (Mandatory for using email module)	Email address of the customer	'john.doe@exampleshop.com'
Mobile Phone (phone)	Optional	Mobile phone number of the customer	'+1 555 555 5555'
Gender (gender)	Optional	Gender of the customer. Must be either 'M' or 'F'	'M'
Age (age)	Optional	Age of the customer. Must be numeric. Either use age or birthdate	27
Birthdate (birthdate)	Optional	Birthdate of the customer. Must be in format 'DD.MM.YYYY'. Either use age or birthdate	'23.01.1980'
Membership Date (memberSince)	Optional	Membership date of the customer. Must be in format 'DD.MM.YYYY'	'20.01.2014'
Location (location)	Optional	Location of the customer	'New York'
Customer Segments (segments)	Optional	Segments of the customer. Must be in array format	['SEGMENT 1', 'SEGMENT 2']

An example curl request is given below:

curl \
    --url 'https://dce1.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"USER_OPERATIONS",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",      
        "device":"MOBILE",
        "step":"signup",
        "username":"CUSTOMER USERNAME",
        "fullName":"NAME SURNAME",
        "email":"EMAIL OF THE CUSTOMER",
        "phone":"MOBILE PHONE OF THE CUSTOMER",
        "gender":"GENDER OF THE CUSTOMER",
        "age":18,
        "memberSince":"23.01.2014",
        "location":"LOCATION OF THE CUSTOMER",
        "segments":["segment1","segment2"],
        "custom":{
            "field1":"value1",
            "field2":"value2"
        }
    }
]
BODY

When a registered customer logins (sign-in), a user login event should be sent to Segmentify.

Details of parameters of user login is given below:

Name	Type	Description	Example
User Operation (step)	Mandatory	Identifies which operation is taken for current user/customer	'signin'
Username	Mandatory	Unique identifier for the customer	'johndoe'

An example curl request is given below:

curl \
    --url 'https://dce1.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"USER_OPERATIONS",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",      
        "device":"MOBILE",
        "step":"signin",
        "username":"CUSTOMER USERNAME"  
    }
]
BODY

User Logout¶

When a registered customer logouts (sign-out), a user logout event should be sent to Segmentify.

Details of parameters of user logout is given below:

Name	Type	Description	Example
User Operation (step)	Mandatory	Identifies which operation is taken for current user/customer	'signout'
Username	Mandatory	Unique identifier for the customer	'johndoe'

An example curl request is given below:

curl \
    --url 'https://dce1.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"USER_OPERATIONS",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",      
        "device":"MOBILE",
        "step":"signout",
        "username":"CUSTOMER USERNAME"
    }
]
BODY

User Update¶

When you want to share an already registered customer information, provide details of the customer by sending an user update event. You can use both this integration for both frequently updating user information and instant updates when customer updates his/her personal information.

If you want to share a new registered user with Segmentify, please use New User.

Details of parameters of user update is given below:

Name	Type	Description	Example
User Operation (step)	Mandatory	Identifies which operation is taken for current user/customer. Each operation has differen meaning and use it accordingly	'update'
Username (username)	Mandatory	Unique identifier for the customer	'johndoe'
Full Name (fullName)	Optional	Full name of the customer.	'John Doe'
Email (email)	Optional (Mandatory for using email module)	Email address of the customer	'john.doe@exampleshop.com'
Mobile Phone (phone)	Optional	Mobile phone number of the customer	'+1 555 555 5555'
Gender (gender)	Optional	Gender of the customer. Must be either 'M' or 'F'	'M'
Age (age)	Optional	Age of the customer. Must be numeric. Either use age or birthdate	27
Birthdate (birthdate)	Optional	Birthdate of the customer. Must be in format 'DD.MM.YYYY'. Either use age or birthdate	'23.01.1980'
Membership Date (memberSince)	Optional	Membership date of the customer. Must be in format 'DD.MM.YYYY'	'20.01.2014'
Location (location)	Optional	Location of the customer	'New York'
Customer Segments (segments)	Optional	Segments of the customer. Must be in array format	[ 'SEGMENT 1', 'SEGMENT 2' ]
Is Registered Flag (isRegistered)	Optional	This is an advanced parameter, use cautiously. If you want to change user's register status without sending a register event, use this flag. Value is either 'true' or 'false'	'true'
Is Login Flag (isLogin)	Optional	This is an advanced parameter, use cautiously. If you want to change user's login status without sending a login/logout event, use this flag. Value is either 'true' or 'false'	'true'

An example curl request is given below:

curl \
    --url 'https://dce1.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"USER_OPERATIONS",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",      
        "device":"MOBILE",
        "step":"update",
        "username":"CUSTOMER USERNAME",
        "fullName":"NAME SURNAME",
        "email":"EMAIL OF THE CUSTOMER",
        "phone":"MOBILE PHONE OF THE CUSTOMER",
        "gender":"GENDER OF THE CUSTOMER",
        "age":18,
        "memberSince":"23.01.2014",
        "location":"LOCATION OF THE CUSTOMER",
        "segments":["segment1","segment2"],
        "custom":{
            "field1":"value1",
            "field2":"value2"
        }
    }
]
BODY

Custom Event¶

This integration enables any event & data important for you to be tracked by Segmentify and become actionable. With this integration, you can send any non standard events & data to Segmentify, and gives endless opportunities to track and take actions to your visitor's behaviour.

Details of parameters of custom event is given below:

Name	Type	Description	Example
Type (type)	Mandatory	Type of the event. You should use same type for same events	'my_custom_event'
Custom Parameters (params)	Optional	Custom parameters of the event. Must be in map format.	'{"field1":"value1", "field2":"value2"}'

An example curl request is given below:

curl \
    --url 'https://dce1.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"CUSTOM_EVENT",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",      
        "device":"MOBILE",
        "type":"my_custom_event",
        "params":{
            "field1":"value1",
            "field2":"value2"
        }
    }
]
BODY

Interaction¶

This section will be available in next releases. To learn more about this integration, please contact with support team, by sending an email to support@segmentify.com.

Form/Survey¶

This section will be available in next releases. To learn more about this integration, please contact with support team, by sending an email to support@segmentify.com.

Banners¶

This section will be available in next releases. To learn more about this integration, please contact with support team, by sending an email to support@segmentify.com.

Tracking¶

This section will be available in next releases. To learn more about this integration, please contact with support team, by sending an email to support@segmentify.com.

Custom Integration¶

Introduction¶

Integration¶

Event Types¶

Request Details¶

Request Endpoint¶

Request Headers¶

Request Body¶

Response Details¶

Response Body¶

API Errors¶

User & Session Management¶

Common Parameters¶

Page View¶

Product View¶

Basket Operations¶

Add Product to Basket¶

Remove Product from Basket¶

Basket Event Parameters¶

Checkout Operations¶

View Basket¶

Customer Information¶

Payment Information¶

Purchase/Success¶

Checkout Parameters¶

Basket Product Parameters¶

User/Visitor Operations¶

New User¶

User Login¶

User Logout¶

User Update¶

Custom Event¶

Interaction¶

Form/Survey¶

Banners¶

Tracking¶