UTM Campaign Builder Documentation

Throttle: 500/Hour

Object: UTM

URI and IRI are NOT Normalized!
Only Shortened and Validated have Normalized!

print-uri
String
URI Output
Unicode and Unsafe ASCII Characters are Percent Encoded

Example

"print-uri": "https://juandefu.ca/"
"print-uri": "//xn--238h/?%25" // ascii % character
"print-uri": "//xn--238h/?%F0%9F%98%BB" // 😻
print-iri
String
IRI Output
Unicode is Unencoded, Unsafe ASCII Characters are Percent Encoded

Example

"print-iri": "https://juandefu.ca/"
"print-iri": "//😻/?%25" // ascii % character
"print-iri": "//😻/?😻"

POST /api;v1.0/utm

JSON POST endpoint. Supports Validator Options!

Request

Parameters

raw
String
Raw Input to Modify

Example

"raw": "http://juandefu.ca/"
validator
Number
Optional
Method of Validation to use.
STRICT Validation will not allow Incorrect Spec Validation to occur! It's recommended to use LOOSE!
LOOSE_ASIS assumes percent encoding DOES NOT EXIST and any percent characters will be encoded!

The Default/Invalid Validator is LOOSE

Constants

Key Value
STRICT 1
LOOSE 2
LOOSE_ASIS 3


Example

"validator": 0
uri
Boolean
Optional
Allow URIs to be Modified

Example

"uri": true
urn
Boolean
Optional
Allow URNs to be Modified

Example

"urn": true
utm_source
String
Required
Raw Input to Validate and then use to Modify the Query String with.
The same Validator as the URI Validator is used. Loose Validator is recommended.

Advertiser, Site, Publication

Example

"utm_source": "adsense"
"utm_source": "newsletter"
"utm_source": "g%2B"
utm_medium
String
Optional
Raw Input to Validate and then use to Modify the Query String with.
The same Validator as the URI Validator is used. Loose Validator is recommended.

Banner, Email, Newsletter

Example

"utm_medium": "email"
"utm_medium": "cpc"
"utm_medium": "cpm"
utm_campaign
String
Optional
Raw Input to Validate and then use to Modify the Query String with.
The same Validator as the URI Validator is used. Loose Validator is recommended.

Product, Promotion, Strategy

Example

"utm_campaign": "spring sale"
"utm_campaign": "promo_abc123"
"utm_campaign": "newsletter subscribers"
utm_term
String
Optional
Raw Input to Validate and then use to Modify the Query String with.
The same Validator as the URI Validator is used. Loose Validator is recommended.

Target Audience, Paid Keywords

Example

"utm_term": "running+shoes"
"utm_term": "new car"
"utm_term": "white t-shirt"
utm_content
String
Optional
Raw Input to Validate and then use to Modify the Query String with.
The same Validator as the URI Validator is used. Loose Validator is recommended.

Context, A/B Testing

Example

"utm_content": "top banner"
"utm_content": "text-link"
"utm_content": "a/b test 2"
shorten
Boolean
Optional
Shorten Modified Object
Modified must be Valid and Shorten must not be Throttled!

Example

"shorten": true
shorten-private
Boolean
Optional
If this is set you will only be able to access the Shortened Link with a Private Key!
Private is a very large Random Integer up to 2^64 (18,446,744,073,709,551,615) and should be very hard to brute force!
DO NOT RELY SOLEY ON THIS FOR SECURITY!

Example

"private": true
validate
Boolean
Optional
Validate Input
Input must be Valid and Validate must not be Throttled!

Example

"validate": true
validate-options
Object: URI Options
Optional
Validator Options
Default Options will be used when nil

Response

errors
[]String
This is only returned on Internal Errors! Always check the Response Header Content-Type before parsing!

Example

"errors": [
	"internal server error"
]
utm
Object: UTM
Always returned!

If Throttled, returns an Object containing the Attribute "throttle" with a value of the Throttle Expiration Timestamp RFC 3339

shortened
Object: Shortened
If UTM is Throttled or an error occurs Shortened will be ignored!

validated
Object: URI Validated
If UTM is Throttled or an error occurs Validated will be ignored!