Attach a call-to-action to every link you share

Get Started — It's Free!


Browsable API

The Sniply API can be explored completely through your browser. To give it a try, just visit snip.ly/api/v2/links/

Link Management

Integrate your system or application to manage your users' snips, while gaining insight into content being shared.

Automated Branding

Automate link creation to empower your users to extend their brand onto content from all over the Internet.



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.

The Sniply API uses Oauth2 authentication, so to authenticate:


  1. Send your user to https://snip.ly/api/authenticate/ with the following query string parameters:

    • redirect_uri: the url that you would like to use to handle the response from the authentication procedure. This is given to you when you request access to the API.
    • client_id: the API client ID that you received when you requested access to the API.

    Example:

    <a href="https://snip.ly/api/authenticate/?client_id=[my_client_id]&redirect_uri=[my_redirect_uri]">Connect Sniply!</a>

  2. After the authentication is complete, your user will be redirected to your redirect_uri with the following query string parameters:

    • state: 1
    • code: only appears in the query string for a successful login (the user accepted the sign-in). This code can be used to fetch your access token for the user as described below
    • error: only appears in the query string for an unsuccessful login (the user rejected the sign-in)

    Successful Authentication:

    [my_redirect_uri]?state=1&code=123456789

    Rejected Authentication:

    [my_redirect_ury]?state=1&error=access_denied

  3. After your user is redirected to your redirect_uri, you must complete a POST request to https://snip.ly/api/oauth2/access_token/ with the following POST data:

    • grant_type: This must be equal to ‘authorization_code’
    • client_secret: Your client secret, as received when you registered for the API
    • client_id: Your client id, as received when you registered for the API
    • code: The code from the query string included in the redirect_uri above

    Example in HTTP (for the above successful authentication example, "the_code_I_just_received" is 123456789):

    POST /api/oauth2/access_token/
    HOST: snip.ly
    {
        "grant_type": "authorization_code",
        "client_secret": "[my_client_secret]",
        "client_id": "[my_client_id]",
        "code": "[the_code_I_just_received]"
    }

  4. 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.

Example in HTTP:

POST /api/oauth2/access_token/
HOST: snip.ly
{
    "grant_type": "refresh_token",
    "client_secret": "[my_client_secret]",
    "client_id": "[my_client_id]",
    "refresh_token": "[my_refresh_token]"
}

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:

  1. Brand photo: The photo that appears in the Sniply Bar
  2. Brand name: The name that appears in the Sniply Bar
  3. Custom Shortlink: The domain used to load the link (defaults to snip.ly)
  4. 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.

Example:

GET /api/v2/brands/
HOST: snip.ly
Authorization: Bearer [access_token]

You can also use a GET request on the https://snip.ly/api/v2/brands/[brand_id]/ endpoint to retrieve information about a specific brand.

Example:

GET /api/v2/brands/[brand_id]/
HOST: snip.ly
Authorization: Bearer [access_token]
Creating Brands

To create a new Brand, use a POST request on the https://snip.ly/api/v2/brands/ endpoint. The following table indicates the parameters that you can use to configure the new Brand:

Parameter Name Description Requirement Type
name The name of the Brand, which will appear on the Sniply Bar to everyone who views it. Required string
photo_url A URL leading to a photo, which will appear as the Brand photo on the Sniply Bar to everyone who views it. Required url
website A URL that the Brand Photo and Name will link to on the Sniply Bar (when a reader clicks on the name or photo in a Sniply Bar, they will be directed to the Brand website). Required url
custom_url The URL that you would like to use to shorten links made using this Brand. Defaults to snip.ly. Different URLs will need to have the correct DNS configuration. Optional domain
custom_url_alternate The URL that you would like to redirect to if someone visits the root of the custom_url. Optional url
custom_code Any custom HTML that you would like to include in the body of the Sniply Bar (to alter the appearance, add retargeting, etc.) Optional html
archived Indicates whether or not the Brand is in an archived state. Archived Brands cannot be used to create Call-to-Actions or Links. Optional boolean

Example:

POST /api/v2/brands/
HOST: snip.ly
Authorization: Bearer [access_token]
{
    "name": "Example Brand",
    "photo_url": "https://3f40f2e5d9a320633d8a-76d63bd8779f62275bae70e2be2045cf.ssl.cf5.rackcdn.com/511ecb0d-102c-4872-b372-06f073e7a2d3"
    "website": "http://mysite.com"
}
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).

This endpoint is also used to change the archived flag.

Example:

PUT /api/v2/brands/[brand_id]/
HOST: snip.ly
Authorization: Bearer [access_token]
{
    "name": "New Name",
    "photo_url": "https://3f40f2e5d9a320633d8a-76d63bd8779f62275bae70e2be2045cf.ssl.cf5.rackcdn.com/511ecb0d-102c-4872-b372-06f073e7a2d3",
    "website": "http://mynewsite.com"
}

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

Example:

GET /api/v2/campaigns/
HOST: snip.ly
Authorization: Bearer [access_token]

If you only need the information belonging to a specific Campaign, you can use a GET request on the https://snip.ly/api/v2/campaigns/[campaign_id]/ endpoint.

Example:

GET /api/v2/campaigns/[campaign_id]/
HOST: snip.ly
Authorization: Bearer [access_token]
Creating Campaigns

To create a new Campaign, use a POST request on the https://snip.ly/api/v2/campaigns/. The following table indicates the parameters that you can use to configure the new Campaign:

Parameter Name Description Requirement Type
name The Name used to identify the campaign on the dashboard. Optional string
brand The ID of the Brand that the Campaign should be created under Required Brand ID

Example:

POST /api/v2/campaigns/
HOST: snip.ly
Authorization: Bearer [access_token]
{
    "brand": "[brand_id]"
}
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).

Example:

PUT /api/v2/campaigns/[campaign_id]/
HOST: snip.ly
Authorization: Bearer [access_token]
{
    "name": "My New Name",
    "brand": "[brand_id]"
}

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:

GET /api/v2/ctas/?campaign=[campaign_id]
HOST: snip.ly
Authorization: Bearer [access_token]

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

GET /api/v2/ctas/?brand=[brand_id]
HOST: snip.ly
Authorization: Bearer [access_token]

Finally, if you just want the details for a specific Call-To-Action, you can send a GET request to the https://snip.ly/api/v2/ctas/[cta_id]/ endpoint.

Example:

GET /api/v2/ctas/[cta_id]/
HOST: snip.ly
Authorization: Bearer [access_token]
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. Optional hex string
message_color The color of the text in the Sniply bar, defaults to dark grey. This is only available to users with a Pro Sniply account. Optional hex string
theme 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. Optional hex string
text_color The color of the text on the button, defaults to white. This is only available to users with a Pro Sniply account. Optional hex string
form_action The properties of the form on the Sniply bar, used to collect input from viewers Optional Object
Parameter Name Description Requirement Type
placeholder_text The text to be displayed in the placeholder of the input, which should be kept as short as possible Required, if a form_action is included string
button_text_color The color of the text of the submit button attached to the right side of the form element. This is only available to users with a Pro Sniply account. Optional hex string
button_background_color The color of the background of the submit button attached to the right side of the form element. This is only available to users with a Pro Sniply account. Optional hex string

Notes:

  1. Fields of type "hex string" must be a hash character ("#") followed by a three or six digit hex code, representing an RGB color. For example "#fff" (white) or "#000000" (black)
  2. If an option is sent that the user is not allowed to access (the user does not have the right level of paid account), a 403 Forbidden response will be sent.
  3. The simplest link that can be made includes only the message, profile ID and url parameters.

Example:

POST /api/v2/ctas/
HOST: snip.ly
Authorization: Bearer [access_token]
{
    "message": "This is the text on the Sniply Bar",
    "campaign": "[campaign_id]",
    "button_action": {
        "text": "I'm a button",
        "url": "http://mysite.com"
    }
}
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.

Example:

PUT /api/v2/ctas/[cta_id]/
HOST: snip.ly
Authorization: Bearer [access_token]
{
    "message": "This is edited text!",
    "campaign": "[campaign_id]",
    "button_action": {
        "text": "I'm an edited button!",
        "url": "http://mysite.com"
    }
}

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.


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.

Example:

GET /api/v2/links/?campaign=[campaign_id]&page=2
HOST: snip.ly
Authorization: Bearer [access_token]

The details for a specific Link can also be fetched using the /api/v2/links/[link_slug]/ endpoint. Example:

GET /api/v2/links/[link_slug]/
HOST: snip.ly
Authorization: Bearer [access_token]

To create a new Link, use a POST request on the https://snip.ly/api/v2/links/ endpoint. The following table indicates the parameters that you can use to configure the new Link:

Parameter Name Description Requirement Type
url The URL of the page that you would like to turn into a Sniply link. Required URL
campaign The ID of a Campaign that belongs to you. The Call-to-Actions that are attached to the Campaign dictate which Call-to-Action will show up on the link when it is rendered in a browser. Required Campaign ID

Example:

POST /api/v2/links/
HOST: snip.ly
Authorization: Bearer [access_token]
{
    "url": "http://example.com/",
    "campaign": "[campaign_id]"
}

To edit an existing Link, use a PUT request on the https://snip.ly/api/v2/links/[link_slug]/ endpoint. The URL and the campaign field are both editable.

Example:

PUT /api/v2/links/[link_slug]/
HOST: snip.ly
Authorization: Bearer [access_token]
{
    "url": "http://example.com/new-url",
    "campaign": "[campaign_id]"
}

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: