NAV Navbar
cURL

REST Section

Getting started

Overview

Welcome to the SegMetrics API!

The SegMetrics API v1 is a way to enable customer to import their own data into their SegMetrics account, either through a custom integration, or to modify existing information in their integrations.

Calls for the SegMetrics API v1 are relative to the url: https://import.segmetrics.io/api/v1/<account_id>/<integration_id/

API v1 is in active development.

Authentication

The SegMetrics API uses two pieces of information to authorize your account.

Authorization

curl "https://import.segmetrics.io/api/v1/<account_id>/<integration_id/<endpoint>" \  
  -H 'Authorization: YOUR_API_KEY'
  -H 'Content-Type: application/json'

You can find your Account Id and API Key in the SegMetrics Account page.

Responses

Successful Call

{
    "status": "success"
}

When an API call succeeds, the API will return a 200 HTTP response and a JSON response body unless otherwise noted.

If there's an error, the API will return an HTTP response in the 400 or 500 range and a response body indicating what caused the error.

Bad data

When you create or update a field, you may receive an HTTP 400 if any fields contain bad data or required fields are missing.

Missing Data

{
    "status": "error",
    "errors": [
        "missing 'id' field "
    ]
}

Internal server errors

If the server is overloaded or you encounter a bug, you will get a 500 error. Try again after a short period, and if you continue to encounter an error, please raise the issue with support.

Contacts

Add or Update Contact

Example request

curl -X POST https://import.segmetrics.io/api/v1/<account_id>/<integration_id>/contact
     -H 'Authorization: YOUR_API_KEY'
     -H 'Content-Type: application/json'
     -d '{
           "contact_id": 249,
           "first_name": "Joey",
           "last_name": "Bloggs",
           "email": "joey@bloggs.com",
           "status": 'active',
           "date_created": "2018-10-02 16:15:00",
           "last_updated": "2018-11-28 09:28:42",
           "utm_source": "facebook",
           "utm_content": "holiday special",
           "utm_medium": "facebook",
           "utm_campaign": "holiday",
           "utm_term": "awesomeness",
           "referring_url": "reallycoolurl.com",
           "optin_url": "evencoolerurl.com",
           "ip_address": "8.8.8.8",
           "affiliate_id": "123",
           "geo_lat": "45.523064",
           "geo_lon": "-122.676483",
           "tags": [
             {
               "id": 3,
               "name": "New Lead",
               "date": "2018-10-02 16:15:00"
             },
             {
               "id": 45,
               "name": "2018 Holiday Special",
               "date": "2018-11-28 09:25:33"
             },
             {
               "id": 8,
               "name": "Platinum Customer",
               "date": "2018-11-28 09:28:42"
             }
           ],
           "custom_fields": {
                "shirt_size": "Medium",
                "Awesome Sauce": "Applesauce2"
           }
         }'

Adds a contact to the specified SegMetrics integration.

Endpoint

POST /v1/<account_id>/<integration_id>/contact

Path parameters

Parameter Description
account_id Account API id available from your Account Settings Page
integration_id This is the ID of the integration from your Account Settings Page

Request Body Schema

application/json

Required parameters

Parameter Description
contact_id Contact Id (Required if no contact email)
email Contact Email Address (Required if no contact_id)

Optional parameters

Parameter Description
date_created Date Created
first_name Contact First Name
last_name Contact Last Name
status Optin status of the contact. active or inactive (defaults to active)
tags List of TagIds or Array of Tag Objects
custom_fields Object containing custom field data. E.g. { "shirt_size": "Medium" }.
last_updated Date Last Updated
utm_campaign UTM Campaign
utm_content UTM Content
utm_medium UTM Medium
utm_source UTM Source
utm_term UTM Term
referring_url Referring URL
optin_url Optin URL
ip_address IP Address
affiliate_id Affiliate ID
geo_lat Geographic Latitude
geo_lon Geographic Longitude

Tags

Add Tags to Contact

Example request (Tag Ids)

curl -X POST https://import.segmetrics.io/api/v1/<account_id>/<integration_id>/tags/add \
     -H 'Authorization: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
           "contact_id": 249,
           "tags": [ 3, 45, 8 ]
         }'

Example request (Tag Names)

curl -X POST https://import.segmetrics.io/api/v1/<account_id>/<integration_id>/tags/add \
     -H 'Authorization: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
           "contact_id": 249,
           "tags": [
               "New Lead",
               "2018 Holiday Special",
               "Platinum Customer"
           ]
         }'

Example request (Tag Objects)

curl -X POST https://import.segmetrics.io/api/v1/<account_id>/<integration_id>/tags/add \
     -H 'Authorization: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
           "contact_id": 249,
           "tags": [
             {
               "id": 3,
               "name": "New Lead",
               "date": "2018-10-02 16:15:00"
             },
             {
               "id": 45,
               "name": "2018 Holiday Special",
               "date": "2018-11-28 09:25:33"
             }
           ]
         }'

Tags can be submitted in three different ways depending on how they're available in your application. Examples are shown to the right.

Endpoint

POST /v1/<account_id>/<integration_id>/tags/add

Path parameters

Parameter Description
account_id Account API id available from your Account Settings Page
integration_id This is the ID of the integration from your Account Settings Page

Request Body Schema

application/json

Required parameters

Parameter Description
contact_id Contact Id (Required if no contact email)
email Contact Email Address (Required if no contact_id)
tags Array of Tags.

Tag Format

Parameter Description
id Tag Id
name Tag Name
date DateTime the Tag was applied (defaults to now)

Remove Tags to Contact

Example request (Tag Ids)

curl -X POST https://import.segmetrics.io/api/v1/<account_id>/<integration_id>/tags/remove \
     -H 'Authorization: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
           "contact_id": 249,
           "tags": [ 3, 45, 8 ]
         }'

Example request (Tag Names)

curl -X POST https://import.segmetrics.io/api/v1/<account_id>/<integration_id>/tags/remove \
     -H 'Authorization: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
           "contact_id": 249,
           "tags": [
               "New Lead",
               "2018 Holiday Special",
               "Platinum Customer"
           ]
         }'

Example request (Tag Objects)

curl -X POST https://import.segmetrics.io/api/v1/<account_id>/<integration_id>/tags/remove \
     -H 'Authorization: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
           "contact_id": 249,
           "tags": [
             {
               "id": 3,
               "name": "New Lead"
             },
             {
               "id": 45,
               "name": "2018 Holiday Special"
             }
           ]
         }'

Tags can be submitted in three different ways depending on how they're available in your application. Examples are shown to the right.

Endpoint

POST /v1/<account_id>/<integration_id>/tags/remove

Path parameters

Parameter Description
account_id Account API id available from your Account Settings Page
integration_id This is the ID of the integration from your Account Settings Page

Request Body Schema

application/json

Required parameters

Parameter Description
contact_id Contact Id (Required if no contact email)
email Contact Email Address (Required if no contact_id)
tags Array of Tags.

Tag Format

Parameter Description
id Tag Id
name Tag Name

Orders

Add Purchase to Contact

Example request

curl -X POST https://import.segmetrics.io/api/v1/<account_id>/<integration_id>/invoice
     -H 'Authorization: YOUR_API_KEY'
     -H 'Content-Type: application/json'
     -d '{
           "contact_id": 4,
           "id": 234115,
           "amount": 4500,
           "paid": 4500,
           "is_refunded": 0,
           "date_created": "2018-10-03 11:14:32",
           "items": [
             {
               "name": "Round Tuit",
               "product_id": 1556402307145,
               "amount": 4000,
               "total_paid": 4000
             },
             {
               "name": "Uber Trinket",
               "product_id": 82638,
               "amount": 500,
               "total_paid": 500
             }
           ]
         }'

Adds a purchase to the specified SegMetrics integration.

Endpoint

POST /v1/<account_id>/<integration_id>/invoice

Path parameters

Parameter Description
account_id Account API id available from your Account Settings Page
integration_id This is the ID of the integration from your Account Settings Page

Request Body Schema

application/json

Required parameters

Parameter Description
id Invoice Id
contact_id Contact Id (Required if no contact email)
email Contact's Email (Required if no contact id)
amount Invoice Total in Cents
paid Invoice Amount Paid in Cents
date_created Invoice Date
items Array of Invoice Items

Optional parameters

Parameter Description
is_refunded Invoice Refunded Flag

Item Parameters

For each invoice, include the line items of which products were included. If the product does not exist in SegMetrics, one will be created.

Parameter Description
name Product Name
product_id Product Id
amount Product Price in Cents

Ads

Record Ad Performance

Example request

curl -X POST https://import.segmetrics.io/api/v1/<account_id>/<integration_id>/ad/performance
     -H 'Authorization: YOUR_API_KEY'
     -H 'Content-Type: application/json'
     -d '{
           "ad": 5489788855,
           "adcampaign": {             
              "id": 123456789,
              "name": "My Amazing Ad Campaign",
           },
           "adset": {             
              "id": 5678910,
              "name": "My Amazing Ad Set",
              "adcampaign": 123456789,
           },           
           "spend": 4500,
           "clicks": 7844,
           "impressions": 15487,
           "date": "2018-10-03",           
         }'

Adds the add performance for a specific day to SegMetrics.

The AdPerformance endpoint allows passing the Ad Set and Ad Campaign values in addition to the performance to allow users to skip campaign creation API calls in order to simplify performance.

Endpoint

POST /v1/<account_id>/<integration_id>/ad/performance

Path parameters

Parameter Description
account_id Account API id available from your Account Settings Page
integration_id This is the ID of the integration from your Account Settings Page

Request Body Schema

application/json

Required parameters

Parameter Description
ad The Id of the Ad. Alternately, an ad object may be passed (see below)
spend Amount spent on the ad for this day in Cents
date Date that the clicks, spend and impressions apply to

Optional parameters

Parameter Description
adcampaign The adcampaign object that the ad belongs to (see below)
adset The adset object that the ad belongs to (see below)
clicks Number of clicks on the ad for this day
impressions Number of impressions on the ad for this day

Ad Object Required Parameters

ad may be passed as either an existing ID or an object. If an object is passed, then the ad will be created in SegMetrics, similar to if the Create Ad endpoint was being called, with the following values:

Parameter Description
id Id of the Ad
name Name of the Ad
adcampaign Ad Campaign Id of the Ad
adset Ad Set Id of the Ad

AdSet Object Required Parameters

adset may be passed as either an existing ID or an object. If an object is passed, then the AdSet will be created in SegMetrics, similar to if the Create AdSet endpoint was being called, with the following values:

Parameter Description
id Id of the AdSet
name Name of the AdSet
adcampaign Ad Campaign Id of the AdSet

AdCampaign Object Required Parameters

adcampaign may be passed as either an existing ID or an object. If an object is passed, then the Campaign will be created in SegMetrics, similar to if the Create AdCampaign endpoint was being called, with the following values:

Parameter Description
id Id of the Ad Campaign
name Name of the Ad Campaign

JS Section

Getting Started

The SegMetrics tracking snippet has a number of API methods for performing tasks right from your website, such as identifying contacts and tracking page views. This document details everything you can do via our JavaScript API.

Installing Your JavaScript Snippet

The snippet for your site generally looks something like this:

<!-- SegMetrics  -->
<script type="text/javascript">
  var _segq = _segq || [];
  var _segs = _segs || {};
  _segs.integration = `your account id`;

  (function(){var dc=document.createElement('script');
    dc.type='text/javascript';dc.async=true;
    dc.src='//tag.segmetrics.io/seg.js';
    var s=document.getElementsByTagName('script')[0];
    s.parentNode.insertBefore(dc,s);})();
</script>
<!-- end SegMetrics  -->

To interact with the JavaScript API, you'll need to have your SegMetrics snippet installed on your website. Each SegMetrics account has a unique snippet that can be found under Settings → Site Setup.

How to Send a JS API Request

_segq.push(["methodName", { key: "value", ... }]);

All requests follow the same conventions. If you've ever worked with the Google Analytics API, the code should look familiar. This is the basis structure of an API request.

API requests are executed asynchronously, so you may safely place then anywhere on the page (even above the SegMetrics snippet).

Identifying Visitors

Connect a Contact to the Current Web Session

Example identify request

_segq.push(["identify", "john@example.com"]);

The identify command lets you tie a contact in your email marketing platform to their actions on the website. It includes an email address, and automatically connects to the current session.

Tracking Without the JavaScript API

Manually Identifying a User

curl -X GET -G https://track.segmetrics.io/identify     
     -d account_id=YOUR_ACCOUNT_ID
     -d seg_uid=SESSION_UID
     -d email=john@example.com     

In some cases you may want to manually identify a contact when you don't have access to the JavaScript API, either through a webhook or backend system like Zapier.

In that case, you can make a standard HTTP request with the same information to connect a Session UID to a contact.

The Session UID is always available in _segs.data.uid