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"
}