API ReferenceCommunity DiscussionAnnouncementsSubscribe
API ReferenceAnnouncementsCommunity Discussion
API ReferenceCommunity DiscussionAnnouncementsSubscribeLog In
API Reference

End-To-End Flow

❗️

Deprecation Notice

Effective from 2020-11-30, the items endpoint will no longer support GIF thumbnails.

Instead, use the performance-video/items endpoint to create Video Sponsored Content.

Create a new campaign item

  1. Create a new item:
POST https://backstage.taboola.com/backstage/api/1.0/demo-advertiser/campaigns/1234/items/

{
   "url": "https://www.taboola-demosite.com/women/barack-obama-feminist-quotes.html"
}

{
    "id": "123",
    "campaign_id": "1234",
    "type": "ITEM",
    "url": "https://www.taboola-demosite.com/women/barack-obama-feminist-quotes.html",
    "thumbnail_url": null,
    "title": null,
    "approval_state": "PENDING",
    "is_active": true,
    "status": "CRAWLING",
    "policy_review": {
        "reject_reason": null
    }
}
  1. Check that item status is not CRAWLING:
GET https://backstage.taboola.com/backstage/api/1.0/demo-advertiser/campaigns/1234/items/123/

{
    "id": "123",
    "campaign_id": "1234",
    "type": "ITEM",
    "url": "https://www.taboola-demosite.com/women/barack-obama-feminist-quotes.html",
    "thumbnail_url": "https://static.taboola-demosite.com/s3fs-public/thumbnails/image/2019/08/04/15/gettyimages-630104414-0.jpg",
    "title": "Nine of Barack Obama’s best feminist quotes",
    "approval_state": "APPROVED",
    "is_active": true,
    "status": "RUNNING",
    "policy_review": {
        "reject_reason": null
    }
}

Upload a thumbnail image from the local device

  1. Upload an image from your local drive to Taboola:

📘

Image Guidelines

For up-to-date guidelines and best practices, refer to the Help Center, or sync with your Taboola Account Manager.

🚧

This endpoint expects multipart/form-data. Sample requests are shown below for cURL and Postman.

cURL sample:

curl --location --request POST 'https://backstage.taboola.com/backstage/api/1.0/operations/upload-image' \
--header 'Authorization: Bearer CUIPAAAAAAAAES1SAgAAAAAAGAEgACl0SwB3cAEAADooNzY2NDIxMTFkZGY0NThmZWZmYzQ1Y2RjNzBhODA4MDM5YmIxNjIyMEAC::949497::1ccd66' \
--header 'Content-Type: multipart/form-data; boundary=--------------------------028602095720144278277778' \
--form 'file=@/Users/john.doe/downloads/images/obama.jpg'

{
    "name": "image_url",
    "value": "http://cdn.taboola.com/libtrc/static/thumbnails/920fe389d79d1e44eed86b34b9a56b2c.jpg"
}
  1. Update the campaign item with the uploaded image:
POST https://backstage.taboola.com/backstage/api/1.0/demo-advertiser/campaigns/1234/items/123/

{
	"thumbnail_url": "http://cdn.taboola.com/libtrc/static/thumbnails/7db3df514736419e81df40ce0e57d25f.jpg"
}

{
    "id": "123",
    "campaign_id": "1234",
    "type": "ITEM",
    "url": "https://www.taboola-demosite.com/women/barack-obama-feminist-quotes.html",
    "thumbnail_url": "http://cdn.taboola.com/libtrc/static/thumbnails/7db3df514736419e81df40ce0e57d25f.jpg",
    "title": "Nine of Barack Obama’s best feminist quotes",
    "approval_state": "APPROVED",
    "is_active": true,
    "status": "RUNNING",
    "policy_review": {
        "reject_reason": null
    }
}

Upload an image from an Image Library

  1. Get taxonomies for the URL of the newly created item:
GET https://backstage.taboola.com/backstage/api/1.0/operations/thirdparty/taxonomies?url=https://www.taboola-demosite.com/women/barack-obama-feminist-quotes.html

{
    "results": [
        {
            "name": "Barack Obama"
        },
        {
            "name": "Obama"
        },
        {
            "name": "women's health"
        },
        {
            "name": "President of the United States"
        }
    ],
    "metadata": {
        "total": null,
        "count": null,
        "static_fields": [],
        "static_total_fields": []
    }
}
  1. Find third party images that match 1 or more of the taxonomies returned:
GET https://backstage.taboola.com/backstage/api/1.0/operations/thirdparty/image?taxonomies="Obama","President of the United States"

{
   "results": [
      {
         "source": "GETTY_IMAGES",
         "url": "https://media.gettyimages.com/photos/president-barack-obamas-inauguration-washington-dc-capitol-building-picture-id471131599?b=1&k=6&m=471131599&s=170667a&w=0&h=DU5hI5kxfb6Rc5bX639PhSECVR2iSz4AOzs79PtV5Ug=",
         "id": "471131599",
         "cdn_url": null
      },
      {
         "source": "GETTY_IMAGES",
         "url": "https://media.gettyimages.com/photos/assault-rifle-picture-id174833937?b=1&k=6&m=174833937&s=170667a&w=0&h=S3ytJ7BvvjobPeEg7hlRl4V-aC2Mk0N-05SJASGWLrg=",
         "id": "174833937",
         "cdn_url": null
      }
   ]
   // ...
}

📘

Provide a comma-delimited list of taxonomies within the request path. Make sure that the path is URL encoded. E.g.

cURL GET 'https://backstage.taboola.com/backstage/api/1.0/operations/thirdparty/image?taxonomies=Obama,%22White%20House%22'
  1. Upload 1 of the matching third party images to Taboola (Content-Type: application/json):
POST https://backstage.taboola.com/backstage/api/1.0/operations/thirdparty/image

{
   "source": "GETTY_IMAGES",
   "url": "https://media.gettyimages.com/photos/president-barack-obamas-inauguration-washington-dc-capitol-building-picture-id471131599?b=1&k=6&m=471131599&s=170667a&w=0&h=DU5hI5kxfb6Rc5bX639PhSECVR2iSz4AOzs79PtV5Ug=",
   "id": "471131599",
   "cdn_url": null
}

{
    "source": "GETTY_IMAGES",
    "url": "https://media.gettyimages.com/photos/president-barack-obamas-inauguration-washington-dc-capitol-building-picture-id471131599?b=1&k=6&m=471131599&s=170667a&w=0&h=DU5hI5kxfb6Rc5bX639PhSECVR2iSz4AOzs79PtV5Ug=",
    "id": "471131599",
    "cdn_url": "http://cdn.taboola.com/libtrc/static/thumbnails/GETTY_IMAGES/SKP/471131599__hGmp8jsq.jpg"
  1. Update the campaign item with the uploaded image:
POST https://backstage.taboola.com/backstage/api/1.0//campaigns/1234/items/123/

{
	"thumbnail_url": "http://cdn.taboola.com/libtrc/static/thumbnails/GETTY_IMAGES/SKP/471131599__hGmp8jsq.jpg"
}

{
    "id": "123",
    "campaign_id": "1234",
    "type": "ITEM",
    "url": "https://www.taboola-demosite.com/women/barack-obama-feminist-quotes.html",
    "thumbnail_url": "http://cdn.taboola.com/libtrc/static/thumbnails/GETTY_IMAGES/SKP/471131599__hGmp8jsq.jpg",
    "title": "Nine of Barack Obama’s best feminist quotes",
    "approval_state": "APPROVED",
    "is_active": true,
    "status": "RUNNING",
    "policy_review": {
        "reject_reason": null
    }
}

📘

Related Topics