• Live Demo
  • Features
  • Pricing
  • FAQs
  • Blog
Menu
  • Live Demo
  • Features
  • Pricing
  • FAQs
  • Blog
Book Demo
LOGIN
Menu
  • Live Demo
  • Features
  • Pricing
  • FAQs
  • Blog

API Usage

The utm-builder.com API provides an easy way to access your created link data. This is perfect for developer and BI Teams who want to import created links into reports or a Data-warehouse.

API Standard

  • The API is JSON based
  • HTTP Header “Content-Type” should be set to “application/json”
  • All methods are POST only.

Generic Request

All authenticated requests have the general body structure structure of:

{
	"resource":OBJECT_BEING_ACCESSED,
	"action":API_METHOD,
	"request":{
		....REQUEST_DETAILS
	}
	"token":YOUR_AUTH_TOKEN,
}

Generic Response

All responses will be status 200. A generic response will contain the format:

{
	"error":null, // or error message
	"data":{
		... The primary response
	},
	// if applicable
	"page": 1,
	"nextPage": 2,
	"limit": 2 // the applied page size/limit
}

Authentication

Base Endpoint : https://app.utm-builder.com/auth/

Methods

Login

Endpoint https://app.utm-builder.com/auth/login

{
"email":ACCOUNT_EMAIL,
"password":ACCOUNT_PASSWORD
}

Response

Contains Users details and Auth Token which expires after 24hours.

{
	"token": "48d451f8-b40b-42f8-84ea-85e86ced38b2",
	"user": {
		"_id": USER_ID,
		"name": NAME,
		"email": ACCOUNT_EMAIL,
		"profiles": [
			.... Profile List
			{
				"_id": "58f0bb92c211d231f40XXXXX",
				"permission": "owner",
				"linkCount": 68
			}
		]
	}
}

Resources

Resource: Links

Links are the primary resource you might want to access.

Base Endpoint : https://app.utm-builder.com/api/v0.2
N.B Links endpoint is version 0.2 – v0.2

Methods / Action

Get

Use this method to list or find Links on conventions you have access to: A variety of link data and meta data is provided

Sample

{
	"resource":"links",
	"action":"get",
	"request":{
		// link created at (createdAt) dates
		"startDate":"2017-01-01", // REQUIRED
		"endDate":"2018-06-25T13:25:34.934Z", // Default = Now
		"filters":{}, // Mongo Query Syntax
		"projection":{}, // Mongo Query Syntax
		"sort":FIELD_NAME, // Default "createdAt"
		"order":SORT_ORDER, 1 = ASCENDING || -1 = DESCENDING
		"limit":INT, Default = 500 min 0 , max 500
		"page":PAGE_NUMBER // Default 1
	},
	"token":YOUR_AUTH_TOKEN,
}

Response

{
	"error": null,
	"data": [
		{
			"_id": "5b30ed4e5b7c7f0004e3f213",
			"createdAt": "2018-06-25T13:25:34.934Z",
			"updatedAt": "2018-06-25T13:25:34.934Z",
			"baseUrl": "https://www.example.com/lp/fassade-renovieren_06",
			"linkId": "807440074391f9a131d3b3583b5a0d3a", // MD5 output link
			// will be the shortened link if that was used
			"outputUrl": "https://www.example.com/lp/fassade-renovieren_06?utm_source=facebook&utm_medium=so&utm_campaign=so_de_facade_material-type_na&utm_term=na_na_2018-06-25_na&utm_content=pic_na_na_na",
			"profileId": "5901d386cf53d40011ba0524",
			"profileTitle": "My UTM Tagging",
			"userEmail": "example@email.com",
			"queryString": "utm_source=facebook&utm_medium=so&utm_campaign=so_de_facade_material-type_na&utm_term=na_na_2018-06-25_na&utm_content=pic_na_na_na",
			"host": "www.example.com",
			"pathname": "/lp/fassade-renovieren_06",
			"idInt": 689,
			"shortId": "cT",
			"clickCount": 0,
			"fieldValues": [
				{
					"title": "socialSource",
					"value": "facebook-so"
				},
				{
					"title": "nativeadsSource",
					"value": "hidden"
				},
				...MORE
			],
			"dataPoints": [
				{
					"title": "source",
					"value": "facebook"
				},
				...MORE
			],
			"utms": [
				{
					"utm": "utm_source",
					"value": "facebook"
				},
				.... MORE
			]
		}
	],
	"page": 1,
	"nextPage": 2,
	"limit": 2
}

getReport

N.B response is not JSON.
getReports will download a New Line JSON file. This is compatible with upload to Datawarehouse solutions such as Amazon Redshift or Google BigQuery.

Transformations (“transformations”) will flatten selected fields from being nested. “NONE” will return raw array nested objects.

eg “UTMS”
Changes the “utms” fields (an array of key value pairs) into a selection of properties and values of the form

prefix_$ORIGINAL_KEY: $ORIGINAL_VALUE —> “utms_utm_source”: “facebook”

{
	"resource":"links",
	"action":"getReport",
	"request":{
		"startDate":"2017-04-01",
		"transformations":["UTMS"], // Other values ,"FIELDS","DATAPOINTS","NONE"
		"limit":2
	},
	"token":"48d451f8-b40b-42f8-84ea-85e86ced38b2"
}

Response
N.B. File type is Newline JSON not JSON

{
	"_id":"5b30f88d5b7c7f0004e3f21a",
	"createdAt":"2018-06-25T14:13:33.344Z",
	"updatedAt":"2018-06-25T14:13:33.344Z",
	"baseUrl":"https://example.com/blog/arbeitszimmer-einrichten",
	"linkId":"87398b5049b8f044b25ef154fbda453b",
	"outputUrl":"https://exmample.com/blog/arbeitszimmer-einrichten?utm_source=facebook&utm_medium=so&utm_campaign=so_de_blog_general_na&utm_term=na_na_2018-06-29_na&utm_content=pic_na_na_na",
	"profileId":"5901d386cf53d40011ba0524",
	"profileTitle":"Tagging",
	"userEmail":"name@example.com",
	"queryString":"utm_source=facebook&utm_medium=so&utm_campaign=so_de_blog_general_na&utm_term=na_na_2018-06-29_na&utm_content=pic_na_na_na",
	"host":"example.com",
	"pathname":"/blog/arbeitszimmer-einrichten",
	"idInt":690,
	"shortId":"cU"
}\n // all other line break characters are for easy of reading and will not be included 
{
	"_id":"5b30ed4e5b7c7f0004e3f213",
	"createdAt":"2018-06-25T13:25:34.934Z",
	"updatedAt":"2018-06-25T13:25:34.934Z",
	"baseUrl":"https://example.com/lp/fassade-renovieren_06",
	"linkId":"807440074391f9a131d3b3583b5a0d3a",
	"outputUrl":"https://example.com/lp/fassade-renovieren_06?utm_source=facebook&utm_medium=so&utm_campaign=so_de_facade_material-type_na&utm_term=na_na_2018-06-25_na&utm_content=pic_na_na_na",
	"profileId":"5901d386cf53d40011ba0524",
	"profileTitle":"Tagging",
	"userEmail":"email@example.com",
	"queryString":"utm_source=facebook&utm_medium=so&utm_campaign=so_de_facade_material-type_na&utm_term=na_na_2018-06-25_na&utm_content=pic_na_na_na",
	"host":"example.com",
	"pathname":"/lp/fassade-renovieren_06",
	"idInt":689,
	"shortId":"cT"
}
 

Documentation

Documentation

  • Introduction
  • UTMs & Datapoints
  • Using the Editing Suite
  • Using the questionnaire
  • Managing your Account
  • Field Logic (Advanced Mode)
  • Datapoint Logic (Advanced Mode)
  • Chrome Extension
  • API Usage
  • Expression syntax reference
  • Glossary
Imprint

UTM-Builder LTD
Represented By: Michael O’Toole
68 Garville Ave
Rathgar D6 Dublin Ireland
Email: hello@utm-builder.com

 

Useful links

FAQs
Privacy Policy
Terms & Conditions
Documentation

Cookie Settings

Terminate Contract

 

Facebook-f Twitter Linkedin

About This Sidebar

You can quickly hide this sidebar by removing widgets from the Hidden Sidebar Settings.

Recent Posts

Social Media success metrics for campaigns19. February 2021
Pinterest tracking with UTM parameters20. April 2020
Email Tracking with UTM-Parameters6. February 2020

Categories

  • Allgemein
  • General
  • How To
  • Tips & Tricks

Meta

  • Log in
  • Entries feed
  • Comments feed
  • WordPress.org