Sublime Ads

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://cdn.sublimeads.com/images/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBJZz09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--0877acc1ed8ba789abac0cdd9d08aa022820ea6d/some-nice-image.jpg",
			"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://cdn.sublimeads.com/images/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBJZz09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--0877acc1ed8ba789abac0cdd9d08aa022820ea6d/some-nice-image.jpg",
	"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 has a maximum width of 800 pixels and a quality setting of 95 unless you explicitly add extra Image Resizing options. See below.

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 image URL. Use this if you want your original image returned without any image resizing.

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://cdn.sublimeads.com/images/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBJZz09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--0877acc1ed8ba789abac0cdd9d08aa022820ea6d/some-nice-image.jpg"
},

URLs are proxied and should be cached by our CDN. Use this option only if you don't want any image resizing on your image.

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"
},

run_dates

If you'd like to bring back data concerning the schedule of your ad, you can do it with this query string.

Type: string/datetime/boolean

Use the show_run_dates parameter with a value of true

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

Response:

{
	...,
	"end_date": "2021-11-26T21:59:59.999Z",
	"is_currently_active": true,
	"start_date": "2021-10-20T22:00:00.000Z"
},

show_status

This goes hand in hand with scheduling and shows a text representation of your schedule status.

Type: string

Use the show_status parameter with a value of true

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

Response:

{
	...,
	"status": "active"
},

Possible return statuses:

  • active
  • upcoming
  • expired
  • inactive (Only returned if no schedule is set and ad is paused)

Image resizing

We allow for dynamic image resizing thanks to our CDN. This option is still very much experimental, but we're confident it does the job.

Image resizing allows multiple options like width, height and quality. You can add these during any request to the API.

GIF's, or "JIF's", are not supported. You'll get a static image instead if you pass in any image resizing options.

To get started pass any of the following options:

Width & Height

Type: string

Pass in any width you'd like your image to be, we'll automatically scale the hight to fit (without cropping). Or add a height and we'll do it the other way around. You can also provide both dimensions. Note that we do not offer cropping just yet. If you want it, get in touch.

Note that we set a default quality of 85 out of 100 when image resizing is used. You may use a different value as noted below.

Example, with width: https://sublimeads.com/api/ads/?token=yourAwesomeToken&width=300 Example, with height: https://sublimeads.com/api/ads/?token=yourAwesomeToken&height=300

Quality

Type: string

Pass in a value between 0 and 100 to adjust the quality that you want for the image, 100 being 100% quality (best).

Example: https://sublimeads.com/api/ads/?token=yourAwesomeToken&quality=75

Last Updated: