New In Version 2

The new Sniply API allows you to manage groups of links through Campaigns. A Campaign is a group of links, to which a Call-To-Action can be applied. It makes creating Sniply links simple, enabling you to pass in only the URL of the link you'd like to Snip, along with the Campaign ID, and immediately retrieve a Sniply Link.

Campaigns also allow you to build A/B testing scenarios, just add more than one Call-to-Action to a Campaign, and Sniply will rotate through the Call-to-Actions when displaying the page.

Finally, Campaigns make editing links simple. Rather than having to edit each link individually, a single Campaign can be edited. Link management has become so much simpler!

Authentication

The Sniply API requires you to authenticate your users. Once authenticated, you can view and edit your users snips, as well as create new snips on behalf of the authenticated user. You must authenticate your user so that the snips you create will have the user information displayed on them (the users twitter profile image and name). Before getting started, you will need to request access to the API.

You will receive a response with an access_token. Include this access token with any requests you make through the API in order to authenticate the request. Note that the scope in the response that you receive is not currently in use by the API (there is only one level of access granted).

To make an authenticated request, just include the access_token in your HTTP Headers along with your API calls, in the following form:

Authorization: Bearer [access_token]

Note: In the browsable API, your browser must be logged in to Sniply to make use of the features. Log in here and browse the API here.

Once your access_token expires, you can refresh it using the refresh_token provided along with your initial access_token to continue making API calls on behalf of a user. To do so, use a POST request to the http://snip.ly/api/oauth2/access_token/ endpoint.

Note that the refresh_token request will provide you with a new refresh_token as well as a new access_token. For all API calls, the new access_token must be used. Similarly, the new refresh_token must be used to refresh the access_token in the future.

Brands

Brands are the top-level object used to control and manage Snips. Several things get set inside of a brand that impact the appearance and behaviour of Sniply links, including:

Brand photo: The photo that appears in the Sniply Bar

Brand name: The name that appears in the Sniply Bar

Custom Shortlink: The domain used to load the link (defaults to snip.ly)

Custom Code: Retargeting code, custom styling, etc.

This means that if you would like to create Snips using different photos or names, you will need to create multiple brands.

Note: In v2, Brands replace Profiles.

Reading Brands

To read the existing Brands associated with your account, use a GET request on the https://snip.ly/api/v2/brands/ endpoint.

Editing Brands

To edit an existing Brand associated with your account, use a PUT request on the https://snip.ly/api/v2/brands/[brand_id]/ endpoint. This endpoint accepts all the same parameters as the endpoint used to create Brands (see above).

Campaigns

Campaigns are objects that are used to manage groups of Links. Each link that belongs to a Campaign, will display the Call-to-Action that is attached to the Campaign. This makes it simple to add new links to Campaign, edit groups of links, etc.

Campaigns can also be used to set-up A/B testing. To do this, just attach multiple Call-to-Actions to a Campaign. Sniply will automatically randomize the Call-to-Action that gets shown to each visitor, allowing you to test multiple Call-to-Actions within a single link.

Reading Campaigns

To get a list of your existing Campaigns, you can use a GET request on the https://snip.ly/api/v2/campaigns/ endpoint. By default, this endpoint filters out Campaigns that belong to archived Brands. However, a full list of Campaigns (including Campaigns belonging to archived Brands) can be fetched by adding query string parameter: https://snip.ly/api/v2/campaigns/?archived=true

Editing Campaigns

To edit an existing Campaign, use a PUT request on the https://snip.ly/api/v2/campaigns/[campaign_id]/. This endpoint accepts all the same parameters as the endpoint used to create Campaigns (see above).

Call-To-Actions (CTAs)

A Call-to-Action specifies the full details of how would like the call-to-action to show up inside a Sniply Link. This includes the message text, color configuration, themes, positioning, etc. A Call-to-Action is attached to a campaign, which means that all links added to a campaign will show the Call-to-Action.

Note: if there are multiple call-to-actions attached to a campaign, Sniply randomly chooses one to show each reader, which allows you to A/B test different Call-to-Actions.

Reading Call-To-Actions

To fetch the list of CTAs that you have used, use the https://snip.ly/api/v2/ctas/ endpoint. To query this endpoint, you must either specify a brand or a campaign for which to fetch the call-to-actions through a query string parameter.

If you want to fetch all the Call-To-Actions that have been created and attached to a specific Campaign, you can add the campaign query string parameter:

Creating Call-to-Actions

To create a new Call-To-Action, send a POST request to the https://snip.ly/api/v2/ctas/ endpoint. The following table indicates the parameters that you can use to configure the new Call-to-Action:

Parameter Name

Description

Requirement

Type

message

The text of the message that you would like to dislppay in the snip. HTML messages are not supported and messages can be a maximum of 80 characters once URLs have been removed.

Required

string

campaign

The campaign that should be used to Snip links using this Call-to-Action. The campaign's brnad is used to set the image and name on the Sniply bar. Values must be the id of a Campaign that the authenticated user has created.

Required

campaign id string

background_color

The color of the background of the snip bar, defaults to white. This is only available to users with a Pro Sniply account.

The theme to use to create the appearance of the Sniply. Must be either "social" for the speech-bubble like appearance, "fullwidth" for the classic appearance, "candy" for the modern rectangle appearance or "bean" for a rounded appearance..

Optional

enum { 'social', 'fullwidth', 'candy', 'bean' }

show_sniply_logo

True keeps the Sniply logo on the bar, false removes it. This is only available to users with a Business Sniply account.

Optional

boolean

position

The positioning of the Sniply bar, defaults to bottom. This is only available to users with a Pro (or greater) Sniply account. Values of 'top' and 'bottom' are left-aligned by default.

Optional

enum {'top', 'bottom', 'bottom-right', 'top-right'}

button_action

The properties of the button on the Sniply bar, used for call-to-actions.

Optional

Object

Parameter Name

Description

Requirement

Type

text

The text to be displayed on the button, which should be kept as short as possible.

Required, if a button_action is included

string

url

The URL that the button points to

Required, if a button_action is included

string

background_color

The color of the background of the button, defaults to light blue. This is only available to users with a Pro Sniply account.

Editing Call-to-Actions

To edit an existing Call-to-Action, use a PUT request on the https://snip.ly/api/v2/ctas/[cta_id]/ endpoint. This endpoint accepts all the same parameters as the endpoint used to create Call-to-Actions (see above).

Note that the campaign field is editable. If a Campaign is left without a Call-to-Action, the links in that Campaign will be displayed to visitors without any Sniply Bar.

Links

Links are the most important part of Sniply, they are what users interact with the most. A Link is created by passing in a URL and a Campaign ID. The API will return Sniply Link, which will show viewers the URL with the Call-to-Action associated with the Campaign overlaid.

Reading Links

Links can be fetched through the API using a GET request on the https://snip.ly/api/v2/links/ endpoint. The result of this query is paginated and page navigation can be handled using the page query string parameter.

Links for a specific campaign can also be fetched, by setting the campaign query string parameter.

Responses

There are two kinds of responses returned by the API: list responses and single item responses.

List Responses

List Responses apply to the folowing endpoints:

/api/v2/brands/

/api/v2/campaigns/

/api/v2/ctas/

/api/v2/links/

The responses that come from GET requests sent to these endpoints represent lists of objects. Each list is paginated, and the response contains information about how many items are available in total, current page information, and links to the next and previous pages. The number of items returned per page can be changed using the count query string parameter. The page number fetched can be changed using the page query string parameter.

For example, to get a list of the links that a user has created, you would use the /api/v2/links/ endpoint. Assuming that the user has created many links, a normal GET request to this endpoint would return a result with the 10 most recently-created links. To get the second page of links (links 11-20 most recently-created) you could add use a GET request on https://snip.ly/api/v2/links/?page=2. Alternatively, you could get the top 20 most recently-created links all at once by using the count parameter and querying https://snip.ly/api/v2/links/?count=20.

The count and page query string parameters can also be used together. For example to get the fourth most recently-created link, you could send a request to https://snip.ly/api/v2/links/?page=4&count=1.

Note that the actual data is always returned in the "result" attribute of the response.

Item Responses

Item Responses are simple responses that only contain the information requested. They do not have any metadata sent along, and are not paginated. Item responses are always single items, and do not have top-level lists of objects.

Item Responses are always returned for all POST, or PUT requests. Additionally, they are used for GET requests on endpoints that are expected to only ever return a single item.

The Sniply Community

There are some great developers in the Sniply community, developing amazing applications that use the Snip.ly API. Some have even written open-source projects that will make your integration dead-easy. If you would like to contribute and join this list of amazing people, send an email to [email protected].

Give the following unofficial clients a try when you integrate Sniply: