Documentation

# Links

A Link is a record that contains the short URL, long URL and other related data.

Consult the <model:link> for general property/field information.

All link requests (/link/*) need to specify the Auth headers below as described in General

# HEADERS

"x-api-key": <API KEY>,
"Authorization": <JWT ID Token>

# ALL REQUESTS

# Get suggested name

Follows the long_url and retrieve the title tag from the head of the link as the name.

# REQUEST

# Path

/link/suggested_name

# Authorization Required

root, admin, user

# Body

{
    "control": { },
    "data": {
        "long_url": "https://aws.amazon.com/blogs/aws/new-amazon-dynamodb-transactions/"
    }
}

# RESPONSE

# Success

{
  "control": { "ResponseCode": 2000, "TraceID": "11648023-1376-4da8-806e-11999c1c519f", "Build": "eb511f1" },
  "data": "New – Amazon DynamoDB Transactions | AWS News Blog"
}
  • data Is null if the link took longer than 10 seconds to resolve.

Back to all Requests

# Create

Create a Short URL from a Long URL.

# REQUEST

# Path

/link/create

# Authorization Required

root, admin, user

# Body

{
    "control": { },
    "data": {
      "client_id": "#clt#6be8d279-591a-4210-922e-d6caa605b063",
      "username": "SuperAdmin1",
      "name": "Test link type",
      "long_url": "https://aws.amazon.com/blogs/aws/new-amazon-dynamodb-transactions/",
      "short_url": "/anything",
      "tags": ["News Letter", "Blog"],
      "campaign_id": "#cmp#2021-01-28 18:53:19.214#970a6ed7-90fd-42d9-81a4-62ad838e85bd",
      "campaign_channel": "Email"
    }
}
  • client_id, username, long_url Required.
  • name Optional, if left empty will default to the long_url.
  • short_url Optional, if left empty will default to a unique 6 value combination consisting of this alphabet: "123456789abcdfghijkmnpqrstvwxyzABCDFGHJKLMNPQRSTVWXYZ".
  • tags Optional, array of string values, maximum 5. The values are not validated against the Account set visible tags.
  • campaign_id Optional, the ID of the campaign you want to associate this link to. Must be specified if campaign_channel is specified.
  • campaign_channel Optional, if specifying and the Campaign does not have the channel, then the channel will also be added to the Campaign if allowed.

# RESPONSE

# Success

{
  "control": { "ResponseCode": 2000, "TraceID": "11648023-1376-4da8-806e-11999c1c519f", "Build": "eb511f1" },
  "data": <model:link>
}

Back to all Requests

# Update

Updates, replaces properties of an existing link.

All the same fields and logic applied to the creation of the link applies for the update. Except that you can not change the short_url and username fields. The link_id obtained from the Create is used as the identifier for the update.

Tags are updated with a separate API call.

All the optional properties when creating a link can be removed by not specifying that property or making them null.

WARNING

Changing long_url uses an invalidation which is a billing metric, only do so if absolutely necessary.

# REQUEST

# Path

/link/update

# Authorization Required

root, admin, user

# Body

{
    "control": { },
    "data": {
      "link_id": "#lnk#/anything",
      "name": "Test link type",
      "long_url": "https://aws.amazon.com/blogs/aws/new-amazon-dynamodb-transactions/",
      "campaign_id": "#cmp#2021-01-28 18:53:19.214#970a6ed7-90fd-42d9-81a4-62ad838e85bd",
      "campaign_channel": "Email"
    }
}

# RESPONSE

# Success

{
  "control": { "ResponseCode": 2000, "TraceID": "11648023-1376-4da8-806e-11999c1c519f", "Build": "eb511f1" },
  "data": <model:link>
}

Back to all Requests

# Update Tags

Updates, replaces, the tags of an existing link.

  • Maximum 5 tags per link.
  • Tags can not be longer than 20 characters.
  • To remove all tags; leave array empty, omit property or set to null.

# REQUEST

# Path

/link/update_tags

# Authorization Required

root, admin, user

# Body

{
    "control": { },
    "data": {
      "link_id": "#lnk#/anything",
      "client_id": "#clt#6be8d279-591a-4210-922e-d6caa605b063",
      "tags": ["Tag1"]      
    }
}

# RESPONSE

# Success

{
  "control": { "ResponseCode": 2000, "TraceID": "11648023-1376-4da8-806e-11999c1c519f", "Build": "eb511f1" },
  "data": <model:link>
}

Back to all Requests

# Update Hidden

Updates the hidden property of a link(s).

  • A maximum of 10 ids can be specified in link_ids.

# REQUEST

# Path

/link/update_hidden

# Authorization Required

root, admin, user

# Body

{
    "control": { },
    "data": {
      "link_ids": ["#lnk#/anything"],
      "client_id": "#clt#6be8d279-591a-4210-922e-d6caa605b063",
      "hidden": true    
    }
}
  • hidden Absolute true or false value

# RESPONSE

# Success

{
  "control": { "ResponseCode": 2000, "TraceID": "11648023-1376-4da8-806e-11999c1c519f", "Build": "eb511f1" },
  "data": {
    "link_ids": ["#lnk#/anything"],
    "client_id": "#clt#6be8d279-591a-4210-922e-d6caa605b063",
    "hidden": true
  }
}

Returns body as was sent on success.

Back to all Requests

# Invalidate

Update the long_url in the cache. This is only required in extreme edge cases as an implicit invalidation is done in the Link Update IF the long_url changed.

WARNING

This operation uses an invalidation which is a billing metric, only do so if absolutely necessary.

Wait between ten seconds to a few minutes for the invalidation to propagate the network.

  • A maximum of 10 ids can be specified in link_ids.

# REQUEST

# Path

/link/invalidate

# Authorization Required

root, admin, user

# Body

{
    "control": { },
    "data": {
      "link_ids": ["#lnk#/anything"],
      "client_id": "#clt#6be8d279-591a-4210-922e-d6caa605b063",
      "hidden": true    
    }
}
  • hidden Absolute true or false value

# RESPONSE

# Success

{
  "control": { "ResponseCode": 2000, "TraceID": "11648023-1376-4da8-806e-11999c1c519f", "Build": "eb511f1" },
  "data": true
}

Back to all Requests

# Find

Find an existing link and optionally all of its tags.

Tags can be retrieved with the link if Include: ["tags"] is specified in the control property, otherwise do not specify it if not required.

# REQUEST

# Path

/link/find

# Authorization Required

root, admin, user

# Body

{
    "control": { "Include": ["tags"] },
    "data": {
      "link_id": "#lnk#/anything"
    }
}

# RESPONSE

# Success

{
  "control": { "ResponseCode": 2000, "TraceID": "11648023-1376-4da8-806e-11999c1c519f", "Build": "eb511f1" },
  "data": {
    "link": <model:link>,
    "tags": ["Tag1"]
  }
}
  • tags Will only be returned if specified to do so in the control property of the request.

Back to all Requests

# Find Tags

Find the tags of an existing link.

# REQUEST

# Path

/link/find_tags

# Authorization Required

root, admin, user

# Body

{
    "control": { },
    "data": {
      "link_id": "#lnk#/anything",
      "client_id": "#clt#6be8d279-591a-4210-922e-d6caa605b063"
    }
}

# RESPONSE

# Success

{
  "control": { "ResponseCode": 2000, "TraceID": "11648023-1376-4da8-806e-11999c1c519f", "Build": "eb511f1" },
  "data": {
    "Items": [ "Tag1" ]
  }
}

Back to all Requests

# Paginate

Paginate the links of a user.

Pagination is seek based and ordered by creation date in descending order.

  • Limit Maximum amount of rows to return, must be less than 100, *might return less than the specified value.
  • PageKey Used to continue the pagination. If the first page call returned a PageKey in the response it indicates that there are more items. Specifying it in the next request continues getting the data from that previous point. Leave empty string, null or omit the PageKey on the request to not use it.

# REQUEST

# Path

/link/paginate_user

# Authorization Required

root, admin, user

# Body

{
    "control": { },
    "data": {
      "username": "SuperAdmin1",
      "Limit": 10,
      "PageKey": null
    }
}

# RESPONSE

# Success

{
  "control": { "ResponseCode": 2000, "TraceID": "11648023-1376-4da8-806e-11999c1c519f", "Build": "eb511f1" },
  "data": {
    "Items": [<model:link>],
    "PageKey": null
  }
}
  • PageKey Will only have a value IF there are more items to be retrieved, otherwise null.

Back to all Requests

Paginate the links of a user by popularity.

  • Limit Maximum amount of rows to return, must be less than 100, *might return less than the specified value.
  • PageKey Used to continue the pagination. If the first page call returned a PageKey in the response it indicates that there are more items. Specifying it in the next request continues getting the data from that previous point. Leave empty string, null or omit the PageKey on the request to not use it.
  • period Can be one of three values:
    • alltime Orders by most popular over all links
    • monthly Orders by most popular for the month (UTC)
    • daily Orders by most popular for the current day (UTC)
  • Sort Value can be one of:
    • ASC Sorts from the lowest count to highest.
    • DESC Sorts from the highest count to lowest. Default if property is omitted.

# REQUEST

# Path

/link/paginate_popular

# Authorization Required

root, admin, user

# Body

{
    "control": { },
    "data": {
      "username": "SuperAdmin1",
      "period": "daily",
      "Limit": 10,
      "PageKey": null,
      "Sort": "DESC"
    }
}

# RESPONSE

# Success

{
  "control": { "ResponseCode": 2000, "TraceID": "11648023-1376-4da8-806e-11999c1c519f", "Build": "eb511f1" },
  "data": {
    "Items": [<model:link>],
    "PageKey": null
  }
}
  • PageKey Will only have a value IF there are more items to be retrieved, otherwise null.

Back to all Requests

# Paginate Campaign Stats

Paginate and count the stats for the campaign links server side.

  • PageKey Used to continue the pagination. If the first page call returned a PageKey in the response it indicates that there are more items. Specifying it in the next request continues getting the data from that previous point. Leave empty string, null or omit the PageKey on the request to not use it.

# REQUEST

# Path

/link/paginate_campaign_stats

# Authorization Required

root, admin, user

# Body

{
    "control": { },
    "data": {
      "campaign_id": "#cmp#2021-01-28 18:53:19.214#970a6ed7-90fd-42d9-81a4-62ad838e85bd",
      "PageKey": null
    }
}

# RESPONSE

# Success

{
  "control": { "ResponseCode": 2000, "TraceID": "11648023-1376-4da8-806e-11999c1c519f", "Build": "eb511f1" },
  "data": {
    "Stat": {
      "links": 0,
      "clicks": 0,
      "clicks_month": 0,
      "clicks_day": 0,
      "clicks_unique": 0
    },
    "PageKey": null
  }
}
  • PageKey Will only have a value IF there are more links that needs to be counted server side, otherwise it will be null.
  • Stat This object contains statistic fields similar to <model:link>. With the extra property of links indicating the number of links that have been used for the calculation.

Back to all Requests

# Find Batch

Find links in a batch of maximum 25. Similar to Find except that it is done in batches.

# REQUEST

# Path

/link/find_batch

# Authorization Required

root, admin, user

# Body

{
    "control": { },
    "data": {
      "link_ids": ["#lnk#/anything"]
    }
}

# RESPONSE

# Success

{
  "control": { "ResponseCode": 2000, "TraceID": "11648023-1376-4da8-806e-11999c1c519f", "Build": "eb511f1" },
  "data": {
    "Items": [<model:link>],
    "PageKey": null
  }
}
  • PageKey Always null, not used.

Back to all Requests

# Find Batch History

Find link history in batches of maximum 25.

  • period Can be one of two values:
    • hourly Retrieve all the hourly values for the given period_value specified in days. Returns array of model:link_history_hourly.
    • daily Retrieve all the daily values for the given period_value specified in months. Returns array of model:link_history_daily.
  • period_value
    • IF period is hourly then this should be formatted as YYYY-MM-DD.
    • IF period is daily then this should be formatted as YYYY-MM.

# REQUEST

# Path

/link/find_batch_history

# Authorization Required

root, admin, user

# Body

{
    "control": { },
    "data": {
      "link_ids": ["#lnk#/anything"],
      "period": "daily",
      "period_value": "2021-06"
    }
}

# RESPONSE

# Success

{
  "control": { "ResponseCode": 2000, "TraceID": "11648023-1376-4da8-806e-11999c1c519f", "Build": "eb511f1" },
  "data": {
    "Items": [<model:link_history_hourly> | <model:link_history_daily>],
    "PageKey": null
  }
}
  • PageKey Always null, not used.

Back to all Requests

# Find User History

Finds the history for all the links of a user.

  • period_values
    • An array of values, maximum 13.
    • Formatted as YYYY-MM

# REQUEST

# Path

/link/find_history_user

# Authorization Required

root, admin, user

# Body

{
    "control": { },
    "data": {
      "client_id": "#clt#6be8d279-591a-4210-922e-d6caa605b063",
      "username": "SuperAdmin1",
      "period_value": ["2021-04", "2021-05"]
    }
}

# RESPONSE

# Success

{
  "control": { "ResponseCode": 2000, "TraceID": "11648023-1376-4da8-806e-11999c1c519f", "Build": "eb511f1" },
  "data": {
    "Items": [<model:link_history_daily>],
    "PageKey": null
  }
}

Same format as model:link_history_daily.

  • PageKey Always null, not used.
  • Items[x].link_id Will always be null
  • Items[x].for Will always be daily

Back to all Requests

# Delete

Delete links in batches of maximum 10.

  • invalidate Specify to clear links out of the edge caches immediately. Can be either true or false. If false is specified then the links will be removed and inaccessible within a day.

WARNING

Specifying invalidate as true uses an invalidation which is a billing metric, only do so if absolutely necessary.

# REQUEST

# Path

/link/delete

# Authorization Required

root, admin, user

# Body

{
    "control": { },
    "data": {
      "client_id": "#clt#6be8d279-591a-4210-922e-d6caa605b063",
      "link_ids": ["#lnk#/anything"],
      "invalidate": false
    }
}

# RESPONSE

# Success

{
  "control": { "ResponseCode": 2000, "TraceID": "11648023-1376-4da8-806e-11999c1c519f", "Build": "eb511f1" },
  "data": {
    "client_id": "#clt#6be8d279-591a-4210-922e-d6caa605b063",
    "link_ids": ["#lnk#/anything"],
    "invalidate": false
  }
}

Returns body as was sent on success.

Back to all Requests

← Campaigns →