API Reference

This document describes how to use the SegmentHub REST API to query and manage metadata about your visitors, ingest events, and activate segments in real-time.

Description

When you make a request to the REST API, you will specify an HTTP method and a path. Additionally, you might also specify request headers and path, query, or body parameters. The API will return the response status code, response headers, and potentially a response body.

API Base URL

The base URL for all API requests is:
https://api.segmenthub.com

Panel URL

The panel address for any management needs where you can use to add/remove users, upload media, generate API Tokens, create reports, campaigns, or manage audiences:
https://panel.segmenthub.com

Authenticating & Tokens

Many REST API operations are accessible without authentication. However, some operations require authentication or return additional information if you are authenticated. You can authenticate your request by adding a token. To own a token, please visit the panel and create an API Token by setting its access or limits. A token is required to directly modify a visitor or a profile data.

About Modules

  • DMP: tracks all of your visitors' (devices) behaviours even if they are anonymous or not.
  • CDP: unifies multiple devices' behaviours of a known user.
  • Ad Server: returns campaigns by visitor interests to show best offers.

API Response Codes

This API uses the following error codes:

  • 200 OK: The request was succeeded.
  • 400 Bad Request: The request was malformed or missing required parameters.
  • 401 Unauthorized: The API token provided was invalid or missing.
  • 403 Forbidden: The client does not have access rights to the content.
  • 404 Not Found: The requested account not found or suspended.
  • 415 Unsupported Media Type: API is only willing to process application/json.
  • 500 Internal Server Error: An unexpected error occurred on the server.
POST /campaigns/query

Events - Page View

Fires a page view event and returns eligible campaigns for the user.

Body Parameters

  • account Required

    The account uuid.

  • visitorId Required

    The visitorId generated by the SDK (in the UUID4 format) of the visitor.

  • profileId Optional

    The profileId (e-mail, phone, userId etc.) of the user.

  • platform Required

    The platform code of your website or mobile app. Example: www.example.com

  • device Optional

    The device type (desktop, tablet or mobile) of the current user.

  • event Required

    The event type which is created in the Panel under the Events menu.

  • path Optional

    The path of the current website or view name for the mobile apps.

  • referrer Optional

    The referrer URL where visitor coming from.

Request Body application/json 
{
    "account": "{{account}}",
    "visitorId": "{{visitorId}}",
    "profileId": "{{profileId}}",
    "platform": "{{platform}}",
    "device": "mobile",
    "event": "pageView",
    "path": "/",
    "referrer": null
}
Response 200 OK 
{
    "status": 200,
    "message": "Campaigns executed successfully.",
    "campaigns": []
}
POST /campaigns/query

Events - Product View

Fires a product view event and returns eligible campaigns for the user. (Inherits common properties from Page View).

Product Parameters

  • sku Required

    The SKU information of the product being viewed.

  • price Optional

    Price info of the product (US format locale).

  • brand Optional

    The brand information of the product.

  • breadcrumb Optional

    The breadcrumb (category path) information.

  • category Optional

    The category information of the product.

Request Body 
{
    "account": "{{account}}",
    "visitorId": "{{visitorId}}",
    "profileId": "{{profileId}}",
    "platform": "{{platform}}",
    "device": "mobile",
    "event": "productView",
    "path": "/",
    "referrer": null,
    "sku": "PRODUCT_SKU_HERE",
    "price": 99.90,
    "brand": "PRODUCT_BRAND_HERE",
    "breadcrumb": "PRODUCT_BREADCRUMB_HERE",
    "category": "PRODUCT_CATEGORY_HERE"
}
POST /campaigns/query

Events - Purchase

Fires a purchase event and returns eligible campaigns for the user.

Purchase Parameters

  • orderId Required

    The order id of the purchased items.

  • orderTotal Optional

    Order total of the purchased items.

  • purchasedItems Optional

    Array list of SKUs of the purchased items.

Request Body 
{
    "account": "{{account}}",
    "visitorId": "{{visitorId}}",
    "profileId": "{{profileId}}",
    "platform": "{{platform}}",
    "device": "mobile",
    "event": "purchase",
    "path": "/",
    "referrer": null,
    "orderId": "ORDER_ID_HERE",
    "orderTotal": 199.90,
    "purchasedItems": ["SKU1_HERE", "SKU1_HERE"]
}
POST /profiles/query

Profiles - Query

Returns requested attributes and segments of the given profile.

Body Parameters

  • account Required
  • token Required

    The token generated from the Panel at the Account -> API Tokens page.

  • profileId Required
  • attributes Optional

    Array of attributes to request. Must be allowed for the given token.

  • segments Optional

    Array of segments to request.

Request Body 
{
    "account": "{{account}}",
    "token": "{{token}}",
    "profileId": "{{profileId}}",
    "attributes": [
        "country",
        "firstName",
        "lastName",
        "lastViewedProducts"
    ],
    "segments": ["VIP", "Churn"]
}
Response 200 OK 
{
    "status": 200,
    "message": "Profile queried successfully.",
    "errors": [],
    "attributes": {
        "country": [{"value": "us"}],
        "firstName": [{"value": "John"}],
        "lastName": [{"value": "Doe"}],
        "lastViewedProducts": [
            {"value": "SKU1"},
            {"value": "SKU2"}
        ]
    },
    "segments": ["VIP"]
}
POST /profiles/attributes

Profiles - Update Attributes

Updates requested attributes of the given profile.

Body Parameters

  • attributes Required

    Dictionary of attributes to update. Requested attributes must be allowed for the token.

Request Body 
{
    "account": "{{account}}",
    "profileId": "{{profileId}}",
    "token": "{{token}}",
    "attributes": {
        "firstName": "Test",
        "lastName": "User",
        "email": "{{profileId}}"
    }
}
Response 200 OK 
{
    "status": 200,
    "profileId": "YOUR_PROFILE_ID",
    "message": "Profile attributes saved successfully.",
    "errors": []
}
POST /profiles/segments

Profiles - Update Segments

Assigns or removes segments for the given profile.

Body Parameters

  • assignees Optional

    List of segments to assign to the profile.

  • removes Optional

    List of segments to remove from the profile.

Request Body 
{
    "account": "{{account}}",
    "profileId": "{{profileId}}",
    "token": "{{token}}",
    "assignees": [
        "SEGMENT_TO_BE_ASSIGNED"
    ],
    "removes": [
        "SEGMENT_TO_BE_REMOVED"
    ]
}
POST /visitors/query

Visitors - Query

Returns requested attributes and segments of the given visitor (anonymous user).

Note: Requires visitorId instead of profileId.

Request Body 
{
    "account": "{{account}}",
    "token": "{{token}}",
    "visitorId": "{{visitorId}}",
    "attributes": ["country"],
    "segments": ["VIP"]
}
POST /visitors/attributes

Visitors - Update Attributes

Updates requested attributes of the given visitor.

Request Body 
{
    "account": "{{account}}",
    "visitorId": "{{visitorId}}",
    "token": "{{token}}",
    "attributes": {
        "gender": "Man",
        "favoriteBrands": ["Nike", "adidas"]
    }
}
POST /visitors/segments

Visitors - Update Segments

Assigns or removes segments for the given anonymous visitor.

Request Body 
{
    "account": "{{account}}",
    "visitorId": "{{visitorId}}",
    "token": "{{token}}",
    "assignees": [
        "SEGMENT_TO_BE_ASSIGNED"
    ],
    "removes": [
        "SEGMENT_TO_BE_REMOVED"
    ]
}