Authentication

SafeUrl uses OAuth2 for authentication. You can find libraries for most popular languages here.

Get An Access Token

POST to https://auth.safeurl.com/connect/token

Content-Type must be application/x-www-form-urlencoded

Parameter Default value Required Notes
grant_type Yes Must be password.
scope Yes May be spaced delimetered. You must request at least one scope.
api.safeurl.read Allows read-only access to API resources.
api.safeurl.write Allows clients to create and modify API resources.
client_id Yes Can be requested here.
client_secret Yes Can be requested here.
username Yes The user's email address.
password Yes The user's email password.

Links

Creating Links

POST to https://api.safeurl.com/v1/links

Content type must be application/json

Parameter Default value Required Notes
code No You can specify the short code you want to use.
redirectType 301 No You may specify 301 or 302. You can read more about how redirect type affects SEO here and here.
links Yes You must provide an array of objects with a url property. You can provide up to 3 urls for split-testing. SafeUrl will evenly distribute traffic to your link accross all the urls.
campaignId No You may provide a campaignId if would like to add the link to an existing Campaign. If you do not provide a campaignId SafeUrl will add it to the user's default Campaign that is scaffolded when the user is created.
utm No You may provide a map of UTM parameters that you would like added to the destination url. utm can be added at either the root level of the request or on each link. If a UTM parameter exists on the root and you provide a UTM parameter with the same key on a link the two utm maps will be merged together with the link taking presendence over the value defined in the root.
data No You may provide a map of additional parameters that you would like added to the destination url. data can be added at either the root level of the request or on each link. If a parameter exists on the root and you provide a parameter with the same key on a link the two data maps will be merged together with the link taking presendence over the value defined in the root.
Example request:

{
   links: [{
    url: https://site.com/b,
    utm: {
      utm_medium: "email"
    },
    data: {
      email: "john.doe@gmail.com"
    }
    
   }],
   code: "BigDiscountsForQ1",
   
   utm: {
    utm_source: "newsletter"
   }
}
Will generate a short link with custom code:
https://safeurl.com/BigDiscountsForQ1
Which expands to:
https://site.com?utm_source=newsletter&utm_medium=email&email=john.doe@gmail.com

Campaigns

Campaigns allow you to manage your links in a meaningful way. Campaigns are optional and don't need to be used unless you want them.

Creating a Campaign

POST to https://api.safeurl.com/v1/campaigns

Content type must be application/json

Parameter Default value Required Notes
name Yes You must specify a name for a campaign.
description No You may include a description.
Example request:

{
  name: "Customer Engagement Q1",
  description: "Post holiday customer engagement campaign."
}