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'
- Your
Account ID
is appended to the URL of each request that you'll make to the API - Your
API Key
is sent as an authorization header on each request.
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 |