Sublink APIs

This set of APIs allows you to create and manage SubLink. A SubLink can only be created programmatically via Yozio SubLink "Create" API.

This set of APIs is designed to create multiple transactional level short urls which may be used for one-time purpose or at a very granular level. For example, a SubLink may be created for every picture on a mobile website or email campaign.

Yozio automatically rolls up all attribution stats of SubLinks to it's parent SuperLink. Thus, SubLinks may also be leveraged to keep your dashboard data grouped and easier to analyze. For example, you might create a SuperLink for your Spring Break promotion then create individual SubLinks for one-tiSubLinkme-use coupon codes. When an end user clicks on a SubLink to claim a reward, you can add the SubLink to your internal blacklist table to prevent people for forwarded or sharing it online.

Check this article out to learn more about the difference between SuperLinks and SubLinks.

  • SuperLink short url: each SubLink is associated with one and only one existing SuperLink. The parent SuperLink has a unique short url. i.e. "a.b.c"
  • SubLink short url: this is the SubLink id. i.e. "a.b.c.d"
  • SubLink alias: a SubLink may be assigned a link alias. i.e. "coupon145". The link alias assigned must be unique for all of your apps SuperLinks or SubLinks.
  • Static metadata: a SubLink can have static metadata configured or changed via the SubLink APIs. A SubLink will also inherit any static metadata it's parent SuperLink has. If a key / value pair (metadata) has the same key, static metadata set at the SubLink level will override any static metadata set at the SuperLink level.
  • Dynamic metadata: each SubLink can also have it's own dynamic metadata. i.e. a.b.c.d?&a=1&b=2. If a key / value pair (metadata) has the same key, dynamic metadata will overwrite any static metadata set at the SuperLink or SubLink level.

The SubLink API works over HTTP protocol and supports three basic options: Create, Update, and Get. Please note the following for all API operations:

  • URL endpoint: For all API operations implement a HTTP GET request to "http://api.yozio.com/v2.0/"
  • App key: For all API operations utilize your own app key. You can find your_app_key and your_secret_key by going to your app in the Yozio Console > SDK > Integration Info
  • User agent string: The user agent string of your http request cannot be empty

While there are many possible codes possibilities given the API operations covered below, you can see some code examples here.

This API will create multiple SubLinks for an apps active SuperLink. The SubLink short url will be returned immediately and once returned, the SubLink is active and ready for use.

NAME TYPE MODIFIER DESCRIPTION
app_key string not null Your app key
method string not null Value must be "sub.link.create"
short_url string not null The parent SuperLink id for SubLink, ie: "a.b.c"
link_alias string Unique for your app, including any alias assigned to any SuperLink or SubLink.
reassign_old_alias_to_this_link boolean Default value is "false". When value is "true", Yozio will remove the existing link alias assigned to another SuperLink or SubLink, and assign the alias to this SubLink.
meta_data dictionary Data must be provided in an dictionary. i.e, meta_data[name]=john&meta_data[age]=24
1
2
3
4
5
6
7
http://api.yozio.com/v2.0/?
app_key=YOUR_APP_KEY&
method=sub.link.create&
short_url=g.c.c8&
link_alias=from_gmail&
reassign_old_alias_to_this_link=true
&meta_data[email_source]=gmail

The response is in JSON format, and the result depends on your input and your app. Here’s an example of the correct response for the example request above:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    status: "ok",
    body: {
        sub_link: "g.c.c8.f",
        link_alias: "from_gmail",
        meta_data: {
            email_source: "gmail"
        },
        timestamp: 1426452804376
    }
}

This API will create multiple update attributes of a SubLinks using a script for an apps active SuperLink. Once confirmed with "status: "ok" changes to the SubLink are live.

NAME TYPE MODIFIER DESCRIPTION
app_key string not null Your app key
method string not null Value must be"sub.link.update"
short_url string not null The SubLink id, ie: "a.b.c.d"
link_alias string Unique for your app, including any alias assigned to any SuperLink or SubLink.
reassign_old_alias_to_this_link boolean Default value is "false". When value is "true", Yozio will remove the existing link alias assigned to another SuperLink or SubLink, and assign the alias to this SubLink.
meta_data dictionary Data must be provided in an dictionary. i.e, meta_data[name]=john&meta_data[age]=24
1
2
3
4
5
http://api.yozio.com/v2.0/?
app_key=YOUR_APP_KEY&
method=sub.link.update&
short_url=g.c.c8.f&
link_alias=from_gmail

The response is in JSON format, and the result depends on your input and your app. Here’s an example of the correct response for the example request above:

1
2
3
4
5
6
7
8
9
{
    status: "ok",
    body: {
        sub_link: "g.c.c8.f",
        link_alias: "from_gmail",
        meta_data: null,
        timestamp: 1426453241655
    }
}

This API will create multiple update attributes of a SubLinks using a script for an apps active SuperLink. Once confirmed with "status: "ok" changes to the SubLink are live.

NAME TYPE MODIFIER DESCRIPTION
app_key string not null Your app key
method string not null Value must be"sub.link.get"
short_url string not null The SubLink id, ie: "a.b.c.d"
1
2
3
4
http://api.yozio.com/v2.0/?
app_key=YOUR_APP_KEY
&method=sub.link.get&
short_url=g.c.c8

The response is in JSON format, and the result depends on your input and your app. Here’s an example of the correct response for the example request above:

1
2
3
4
5
6
7
8
{
    status: "ok",
    body: {
        meta_data: null,
        link_alias: "from_gmail",
        timestamp: 1426453729984
    }
}