# Ads

Getting your ads is easy. You have the option to retrieve ads depending on category in the categories section of this guide.

# Get all Ads

Endpoint:

https://sublimeads.com/api/ads

Again, pass in your token as a URL parameter.

This will return all of your ads on your account. Here is an example response:

{
	"message":"Here are your ads",
	"count":1,
	"items":[
		{
			"id":34,
			"public_id":"XjtXY7re_kWmLw",
			"image_url":"https://assets.sublimeads.com/1dmbubekywe7h4u3hlcz6a4a650q",
			"title":"Sublime Ads",
			"content":"\u003cdiv\u003eA privacy focused \u003cstrong\u003ead management\u003c/strong\u003e service for your apps, websites and others.\u003c/div\u003e",
			"plain_content":"A privacy focused ad management service for your apps, websites and others."
			"redirect_to_url":"https://sublimeads.com",
			"url":"https://sublimeads.com/tap/XjtXY7re_kWmLw",
			"accent": "#5522FA",
			"tag": "Service",
			"is_paused":false
		},
	]
}

Info on the ad object is below.

To keep things easy, the count of ads is also returned. Might be useful.

As default, any paused ad will not be shown. This just makes it easier on the receiving end. However, if you wish, you can add an optional parameter to your call:

Adding a show_paused URL parameter will return paused ads and categories. The value can be anything. For example:

https://sublimeads.com/api/ads/?token=yourAwesomeToken&show_paused

# Get an Ad by ID

Each ad has its own ID and you can grab an ad individually if so needed.

Endpoint: https://sublimeads.com/api/ad/:id

Note that you replace :id with the ID of the ad you want to grab. Do not use the "public_id" here - it will not work.

The ID of your ad can be found in your ad list.

# The Ad object

Let's break down the Ad object.

{
	"id":34,
	"public_id":"XjtXY7re_kWmLw",
	"image_url":"https://assets.sublimeads.com/1dmbubekywe7h4u3hlcz6a4a650q",
	"title":"Sublime Ads",
	"content":"\u003cdiv\u003eA privacy focused \u003cstrong\u003ead management\u003c/strong\u003e service for your apps, websites and others.\u003c/div\u003e",
	"plain_content":"A privacy focused ad management service for your apps, websites and others."
	"redirect_to_url":"https://sublimeads.com",
	"url":"https://sublimeads.com/tap/XjtXY7re_kWmLw",
	"accent": "#5522FA",
	"tag": "Service",
	"is_paused":false
},

Note that the API will return values alphabetically.

# id

The ID of your Ad - useful if you need to grab it individually.

Type: int

# public_id

This is the public facing id of your ad, which will be used for the "tap" redirect found in the "url" field.

Type: string

# image_url

This is the URL of the image. This image is coming straight from our CDN, via Cloudflare. For most use cases, use this.

Type: string

# title

The title of your ad.

Type: string

# content

HTML encoded content as set for your ad.

Type: string

# plain_content

The ad content without HTML tags. Great for when embedding into an app where you don't need all that HTML.

Type: string

# redirect_to_url

This is the URL that is used when redirecting a user to the specific website for the ad. You can use this directly if you so wish and register a "tap" via a POST instead. See the taps section for more info.

In general the user is directed to the Sublime Ads "tap" endpoint where they are then redirected to the redirect_to_url.

Type: string

# url

The URL of the Sublime Ads link endpoint. This is the preferred way to handle a click/tap of your ads. Once navigated to this the use will be redirected to the redirect_to_url.

Type: string

When returning Ads from a category this URL changes slightly as we also want to know about the category that it's tied to. See categories for details.

A URL with a tied category will look like this:

http:s//sublimeads.com/tap/XjtXY7re_kWmLw/5c3sO4cNrK2Jlg

To break it down, the first "public_id" is for the ad. The second is the "public_id" for the category.

# accent

This is the accent color that is set for the specific ad. Useful to style your content.

Type: string

# tag

This returns a tag, if set. It's null if none is set. Use tags to display in your integrations.

Type: string

# is_paused

Tells you if the ad is paused or not.

Type: boolean

# Optional ad data

In addition to the above data being returned there are also some optional extras that you can return with extra parameters when calling the API.

# alternative_image_url

This is an alternative, short lived, image URL. Instead of using the image_url you can use this to get a short lived URL back straight from Sublime Ads. Links are valid for 5 minutes.

Type: string

Use the show_alternative_image_url parameter with a value of true

Example: https://sublimeads.com/api/ads/?token=yourAwesomeToken&show_alternative_image_url=true

Response:

{
	...,
	"alternative_image_url": "https://sublimeads.com/images/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBJZz09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--0877acc1ed8ba789abac0cdd9d08aa022820ea6d/some-nice-image.jpg"
},

Use this only as an alternative. Images served from here make an extra roundtrip to the Sublime Ads server. Also note that these URLs are only valid for 5 minutes.

# tap_api_url

This is a special link to easily allow you to POST using the Tap API. Just makes things easier.

Type: string

Use the show_tap_api_url parameter with a value of true

Example: https://sublimeads.com/api/ads/?token=yourAwesomeToken&show_tap_api_url=true

Response:

{
	...,
	"tap_api_url": "https://sublimeads.com/api/tap/pjc1hPP2tRnpJg/5c3sO4cNrK2Jlg"
},

If you look at the URL in the ad object, it contains a specific code. Namely a category public_id, if applicable, and the ad public_id. This property shows those for you, which allows you to call the tap, or any future, URL with this ID. Again this is just to make things easier for you, especially if you have a specific API setup with predefined routes.

Type: string

Use the show_link_id parameter with a value of true

Example: https://sublimeads.com/api/ads/?token=yourAwesomeToken&show_link_id=true

Response:

{
	...,
	"link_id": "PY8WtJbwY0wbFw/5c3sO4cNrK2Jlg"
},
Last updated: 5/28/2021, 10:34:50 AM