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",
                "field_to_remove": null
           }
         }'

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

Delete Contact

Example request

curl -X DELETE https://import.segmetrics.io/api/v1/<account_id>/<integration_id>/contact/<contact_id_or_email>
     -H 'Authorization: YOUR_API_KEY'

Successful Response

{
    "id": "CONTACT_ID",
    "status": "success",
    "object": "contact",
    "deleted": true
}

Permanently deletes a contact from SegMetrics. This cannot be undone.
This will not delete any invoices or purchases from the contact in the same integration.

Endpoint

DELETE /v1/<account_id>/<integration_id>/contact/<contact_id_or_email>

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
contact_id_or_email Contact Id or Email Address of the contact to delete.

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
discount Invoice discount amount in Cents
tax Invoice tax amount in Cents
shipping Invoice shipping amount in Cents

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
id (optional) Line Item Id (defaults to Order Id - Item number)
name Product Name
product_id Product Id
amount Product Price in Cents
subscription_id (optional) The ID of the Subscription that the purchase is connected to

Delete Invoice

Example request

curl -X DELETE https://import.segmetrics.io/api/v1/<account_id>/<integration_id>/invoice/<id>
     -H 'Authorization: YOUR_API_KEY'

Successful Response

{
    "id": "INVOICE_ID",
    "status": "success",
    "object": "invoice",
    "deleted": true
}

Permanently deletes an invoice from SegMetrics. This cannot be undone.

Endpoint

DELETE /v1/<account_id>/<integration_id>/invoice/<id>

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
id Id of the Invoice to delete

Subscriptions

Add Subscription

Example request

curl -X POST https://import.segmetrics.io/api/v1/<account_id>/<integration_id>/subscription
     -H 'Authorization: YOUR_API_KEY'
     -H 'Content-Type: application/json'
     -d '{
           "email": "mwiegand@gmail.com",
           "id": 234115,
           "amount": 4500,
           "product_id": 108,
           "start_date": "2019-12-03 11:14:32",
           "last_bill_date": "2019-12-03 11:14:32",
           "billing_cycle": "month",
           "frequency": 1
         }'

Adds a subscription to the existing contact. If the subscription id already exist, it will be updated.

Endpoint

POST /v1/<account_id>/<integration_id>/subscription

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 Subscription Id
contact_id Contact Id (Required if no contact email)
email Contact's Email (Required if no contact id)
amount Subscription Total in Cents
product_id Product Id that the Subscription applies to
start_date DateTime that the Subscription started
last_bill_date DateTime that the Subscription was last billed
billing_cycle One of year, month, week or day The frequency with which a subscription should be billed.
frequency The number of intervals (specified in the billing_cycle property) between subscription billings. For example, billing_cycle=month and frequency=3 bills every 3 months.

Optional parameters

Parameter Description
name Product Name that the Subscription applies to
quantity The quantity of the plan to which the customer is subscribed. Defaults to 1
trial_end_date If the subscription has a trial, the end of that trial.
end_date A date in the future at which the subscription will automatically get canceled
canceled_date If the subscription has been canceled, the date of that cancellation.

Delete Subscription

Example request

curl -X DELETE https://import.segmetrics.io/api/v1/<account_id>/<integration_id>/subscription/<id>
     -H 'Authorization: YOUR_API_KEY'

Successful Response

{
    "id": "SUBSCRIPTION_ID",
    "status": "success",
    "object": "subscription",
    "deleted": true
}

Permanently deletes a subscription from SegMetrics. This cannot be undone.

Endpoint

DELETE /v1/<account_id>/<integration_id>/subscription/<id>

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
id Id of the Subscription to delete

Products

Add Product

Example request

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 ]
         }'

Adds a product to the specified SegMetrics integration.

Endpoint

POST /v1/<account_id>/<integration_id>/product

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 Product Id
name Name of the Product

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

Reporting Section

The Reporting API allows users to programmatically pull the metrics that SegMetrics generates.

Saved Reports

Get Report Data

Example request

curl -X GET https://api.segmetrics.io/<account_id>/report/<report_type>/<report_id>            
     -H 'Authorization: YOUR_API_KEY'
     -H 'Content-Type: application/json'
     -d start=2020-01-01 \
     -d end=2020-11-24 \
     -d scale=day \

Example Response

{
    "report": {
        "name": "New Lead Report",
        "type": "leads",
        "date_range": {
            "start": "2021-11-01",
            "end": "2021-11-30",
            "duration": null,
            "scale": "day",
            "start_date": "2021-11-01",
            "end_date": "2021-11-30",
            "name": ""
        }
    },
    "kpis": [
        {
            "name": "Leads",
            "key": "leads",
            "value": 42,
            "type": "NUMBER",
            "aggregation": "SUM"
        },
        {
            "name": "Customers",
            "key": "numOfCustomers",
            "value": 5,
            "type": "NUMBER",
            "aggregation": "SUM"
        },
        ...
    ],
    "graph": {
        "labels": [
            "2021-11-01",
            "2021-11-02",
            ...
        ],
        "datasets": [
            {
                "label": "Leads",
                "data": [
                    0,
                    3,
                    ...
                ]
            }
        ]
    },
    "table": {
        "fields": [
            {
                "name": "Channel",
                "key": "channel",
                "type": "STRING",
                "aggregation": null
            },
            {
                "name": "Leads",
                "key": "leads",
                "type": "NUMBER",
                "aggregation": "SUM"
            },
            ...
        ],
        "rows": [
            {
                "channel": "social",
                "leads": 2,
                "numOfCustomers": 0,
                "conversionRate": 0,
                "revenue": 0,
                "leadValue": 0
            },
            {
                "channel": "paid",
                "leads": 33,
                "numOfCustomers": 5,
                "conversionRate": 15.1515,
                "revenue": 2900,
                "leadValue": 87.878788
            },
            ...
        ]
    }
}

Retrieves all key metrics, for the specified report and time period.

Endpoint

GET /<account_id>/report/<report_type>/<report_id>

Path parameters

Parameter Description
account_id Account API id available from your Account Settings Page
report_type The report type that you would like to query. One of: leads, revenue, ads or subscriptions
report_id (Optional) The ID of the saved report that you would like to return

Optional parameters

Parameter Description
start The start date of the required period of data. Either a Relative DateTime, or an ISO-8601 formatted date, e.g. 2020-01-01
end The end date of the required period of data. Either a Relative DateTime, or an ISO-8601 formatted date, e.g. 2020-01-01
scale Breakdown for the graph metrics. One of day (default), week, or month

Customer Journey

Example request

curl -X GET https://api.segmetrics.io/<account_id>/report/<report_type>/<report_id>/contacts            
     -H 'Authorization: YOUR_API_KEY'
     -H 'Content-Type: application/json'
     -d start=2020-01-01 \
     -d end=2020-11-24 \
     -d extend=tags,events

Example response

{
  "data" : [
    {
      "contact_id": "1004",
      "first_name": "Linda",
      "last_name": "Dare",
      "email": "linda.dare@example.com",
      "status": "active",
      "date_created": "2021-12-18T19:07:50+00:00",
      "last_updated": "2021-12-31T00:00:00+00:00",
      "custom_fields": {
        "City": "Mortimerville",
        "State": "UT",
        "Phone1": "780.555.3533",
        ...
      },
      "tags": [
        {
          "tag_id": "115",
          "name": "marketing-blueprint",
          "contact_id": "1060",
          "date_created": "2021-11-18T05:07:44+00:00"
        },
        ...
      ],
      "orders": [
        {
          "order_id": "26",
          "contact_id": "1012",
          "is_paid": true,
          "is_refunded": false,
          "subtotal": 500,
          "total_tax": 0,
          "total_shipping": 0,
          "total_discount": 0,
          "total": 500,
          "total_paid": 500,
          "date_created": "2021-12-12T20:32:11+00:00",
          "line_items": [
            {
              "contact_id": "1012",
              "order_item_id": "894689",
              "product_id": null,
              "order_id": "26",
              "subscription_id": null,
              "product_name": "Launching a Marketing Plan",
              "order_type": "product",
              "is_paid": true,
              "is_refunded": false,
              "amount": 500,
              "total_paid": 500,
              "total_due": 500,
              "date_created": "2021-12-12T20:32:11+00:00",
              "imported_at": "2021-12-12T20:32:11+00:00",
              "last_imported_at": "2021-12-31T00:00:00+00:00"
            }
          ]
        }
      ],
      "events": [
        {
          "type": "page_view",
          "contact_id": "1004",
          "uid": null,
          "fingerprint": null,
          "date_created": "2021-12-18T19:07:50+00:00",
          "ip_address": "3159:c782:bf13:9cdc:6b0d:c76b:d20a:5167",
          "country_code": "BV",
          "region": "port",
          "city": "North Benton",
          "postal_code": "39433",
          "latitude": "1.490988",
          "longitude": "-174.138608",
          "url": "https://example.com./top-page",
          "full_url": "https://example.com./top-page?utm_campaign=Retargeting&utm_medium=cpc&utm_source=fb&utm_term=WARM+Retarget&utm_content=RT+-+Testimonial+-+J&ad_id=559675250&fbclid=1",
          "referrer": "lifehacker.com",
          "host": "example.com",
          "path": "/top-page",
          "args": {
            "utm_campaign": "Retargeting",
            "utm_medium": "cpc",
            "utm_source": "fb",
            "utm_term": "WARM Retarget",
            "utm_content": "RT - Testimonial - J",
            "ad_id": "559675250",
            "fbclid": 1,
            "sega_prod": null
          },
          "meta": null,
          "channel": "paid",
          "utm_source": "fb",
          "utm_medium": "cpc",
          "utm_campaign": "Retargeting",
          "utm_term": "WARM Retarget",
          "utm_content": "RT - Testimonial - J",
          "ad_id": "559675250"
        },
        ...
      ]
    } ...
  ],  
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,    
    "path": "https://api.segmetrics.io/example/report/ads/contacts",
    "per_page": 20,
    "to": 20,
    "total": 85
  }
}

Retrieves the customer journey for all contacts in the specified report and time period.

Endpoint

GET /<account_id>/report/<report_type>/<report_id>/contacts

Path parameters

Parameter Description
account_id Account API id available from your Account Settings Page
report_type The report type that you would like to query. One of: leads, revenue, ads or subscriptions
report_id (Optional) The ID of the saved report that you would like to return

Optional parameters

Parameter Description
start The start date of the required period of data. Either a Relative DateTime, or an ISO-8601 formatted date, e.g. 2020-01-01
end The end date of the required period of data. Either a Relative DateTime, or an ISO-8601 formatted date, e.g. 2020-01-01
extend By default only the core contact data is returned. If you would like to include other data, you can do so by adding a CSV of the following options: events, tags, orders, subscriptions, lists. e.g. events,tags
limit Number of records to return in a page, 1 - 100 (Default 20)
page Result page to return

Contact API

Get Contact

Example request

curl -X GET https://api.segmetrics.io/<account_id>/contact/<contact_id_or_email>            
     -H 'Authorization: YOUR_API_KEY'
     -H 'Content-Type: application/json'
     -d extend=tags,events

Example response

{
  "data": {
    "contact_id": "1004",
    "first_name": "Linda",
    "last_name": "Dare",
    "email": "linda.dare@example.com",
    "status": "active",
    "date_created": "2021-12-18T19:07:50+00:00",
    "last_updated": "2021-12-31T00:00:00+00:00",
    "custom_fields": {
      "City": "Mortimerville",
      "State": "UT",
      "Phone1": "780.555.3533",
      ...
    },
    "tags": [
      {
        "tag_id": "115",
        "name": "marketing-blueprint",
        "contact_id": "1060",
        "date_created": "2021-11-18T05:07:44+00:00"
      },
      ...
    ],
    "orders": [
      {
        "order_id": "26",
        "contact_id": "1012",
        "is_paid": true,
        "is_refunded": false,
        "subtotal": 500,
        "total_tax": 0,
        "total_shipping": 0,
        "total_discount": 0,
        "total": 500,
        "total_paid": 500,
        "date_created": "2021-12-12T20:32:11+00:00",
        "line_items": [
          {
            "contact_id": "1012",
            "order_item_id": "894689",
            "product_id": null,
            "order_id": "26",
            "subscription_id": null,
            "product_name": "Launching a Marketing Plan",
            "order_type": "product",
            "is_paid": true,
            "is_refunded": false,
            "amount": 500,
            "total_paid": 500,
            "total_due": 500,
            "date_created": "2021-12-12T20:32:11+00:00",
            "imported_at": "2021-12-12T20:32:11+00:00",
            "last_imported_at": "2021-12-31T00:00:00+00:00"
          }
        ]
      }
    ],
    "events": [
      {
        "type": "page_view",
        "contact_id": "1004",
        "uid": null,
        "fingerprint": null,
        "date_created": "2021-12-18T19:07:50+00:00",
        "ip_address": "3159:c782:bf13:9cdc:6b0d:c76b:d20a:5167",
        "country_code": "BV",
        "region": "port",
        "city": "North Benton",
        "postal_code": "39433",
        "latitude": "1.490988",
        "longitude": "-174.138608",
        "url": "https://example.com./top-page",
        "full_url": "https://example.com./top-page?utm_campaign=Retargeting&utm_medium=cpc&utm_source=fb&utm_term=WARM+Retarget&utm_content=RT+-+Testimonial+-+J&ad_id=559675250&fbclid=1",
        "referrer": "lifehacker.com",
        "host": "example.com",
        "path": "/top-page",
        "args": {
          "utm_campaign": "Retargeting",
          "utm_medium": "cpc",
          "utm_source": "fb",
          "utm_term": "WARM Retarget",
          "utm_content": "RT - Testimonial - J",
          "ad_id": "559675250",
          "fbclid": 1,
          "sega_prod": null
        },
        "meta": null,
        "channel": "paid",
        "utm_source": "fb",
        "utm_medium": "cpc",
        "utm_campaign": "Retargeting",
        "utm_term": "WARM Retarget",
        "utm_content": "RT - Testimonial - J",
        "ad_id": "559675250"
      },
      ...
    ]
  }
}

Returns the full customer journey of a single contact, either by email or contact_id.

Endpoint

GET /<account_id>/contact/<contact_id_or_email>

Path parameters

Parameter Description
account_id Account API id available from your Account Settings Page
contact_id_or_email The email address or external contact_id of the contact to return

Optional parameters

Parameter Description
extend By default only the core contact data is returned. If you would like to include other data, you can do so by adding a CSV of the following options: events, tags, orders, subscriptions, lists. e.g. events,tags
cURL