Integrate Tumblr with Native API

This guide describes how you can integrate Tumblr Sponsored Posts with your existing Native Ad Platform API account.

The advantage for Native Ad Platform partners and developers is that you can create Tumblr posts programmatically via the Tumblr Ads API and then manage those post campaigns via the Native API.

That means, you can utilize both Tumblr and the Native API for a fully programmatic solution when you create Tumblr Sponsored Posts. You can reach Tumblr users natively with photos and videos, create interactive Call-to-action buttons, and capture the right audiences, with iOS- & Android-specific links to those audiences.

A new campaign objective for Tumblr called Social_Engagement with CPC bidding is provided to accomplish these tasks.

Important

This guide relies on the Postman collection to test and verify the calls you make in the Native API. If you’re not familiar with Postman, which is used for building and handling HTTP requests to REST-based services, navigate to the documentation for the Postman API Toolkit in Native & Search API. You’ll need to work with global variables, which are described in the Postman Toolkit documentation.

Prerequisites

To work successfully with Tumblr and integrate with the Native API, do the following:

  1. Sign up with Tumblr and create an account at

https://www.tumblr.com/register
  1. Tumblr supports the OAuth 1.0a Protocol, so you’ll need to register your OAuth app to get your Customer Key and Secret at

https://www.tumblr.com/oauth/apps
  1. Once these are generated, you can retrieve your Token and Token secret by clicking the Explore API at

https://api.tumblr.com/console/calls/user/info

Note

To use the Tumblr Ads API, all new apps that are created need to have their credentials whitelisted.

Postman Manage Environments

The simplified Postman Collection is available at

https://www.getpostman.com/collections/86a89aec765a5646f209

Use this Postman Collection, as you work through the steps in this guide, which is based off of this collection.

Note that the guide on adding global variables is available in the Postman API Toolkit.

Tumblr’s Authentication Protocols

The following table describes the fields required for Tumblr’s authentication protocols.

Key

Value

CONSUMER_KEY

Tumblr’s Consumer Key for authentication.

CONSUMER_SECRET

Tumblr’s Consumer Secret for authentication.

TOKEN

Tumblr’s Token for authentication.

TOKEN_SECRET

Tumblr’s Token Secret for authentication.

TUMBLR_ADVERTISER_ID

Tumblr’s Advertiser ID – Used for Tumblr Campaign Management Calls (Option A) See the Tumblr Account Management section for details on how to obtain your Advertise Id.

BLOG_NAME

Tumblr Blog Name without the trailing .tumblr.com

Authorization

Your access_token found in steps 4 and step 5 of OAuth Authentication. The token is used if you are planning on using Native & Search Campaign Management Calls (Option B)

You can edit the Environment variables in Postman for Tumblr authentication, as shown in the Postman Manage Environments panel below:

manage environments panel

Authenticate Tumblr Calls with OAuth 1.0a

The Tumblr API requires that you use the OAuth 1.0a Protocol. Once you have your Global Variables configured, select the request you are calling and do the following:

  1. Select the Authorization tab.

  2. In the Type dropdown, select OAuth 1.0.

  3. Click Update Request.

The calls automatically populate with your OAuth 1.0a credentials, thus enabling you to run the call, as shown below.

authorization

Tumblr Account Management

This section describes the steps you need to follow if you use the Tumblr Campaign Management API.

Use this endpoint:

https://api.tumblr.com/v2/pmd/accounts
  1. Call GET Advertiser Accounts. This will

    • Return an array of the current Tumblr Advertising Accounts.

    • Ensure your Blog displays in the tumblelogs array.

    • Ensure your Native & Search Advertiser Id displays as the yam_id.

If you don’t see any Advertising Accounts, run the Create Advertiser Account request.

Do this: Enter your Native & Search Account ID and a nickname for the account in the body.

If you see Advertising Accounts and your Native & Search AccountID, but don’t see your blog listed under tumblelogs, do this:

  1. Run the Add Blog to Advertiser Account.

  2. Enter your Tumblr Advertiser ID (id Found in the GET call) and Tumblr Blog name directly in the Request URI.

Note

An internal Tumblr Administrator will need to approve the change.

advertiser id

Note

The id displayed is the TUMBLRER_ADVERTISER_ID in your global variables.

Create a Tumblr Blog Post

To create a new Video Post, follow these steps:

  1. Use this endpoint:

https://api.tumblr.com/v2/blog/[BLOG_NAME without .tumblr.com]/post

For example:

https://api.tumblr.com/v2/blog/myswimmingbananacollectorfan/post
  1. Header keypair:

    • Authorization - OAuth 1.0

  2. Body keypairs:

    • type - video

    • embed - link to your video

    • ads_params[cta_text_code]

    • 0 => ‘Learn more’

    • 1 => ‘Contact us’

    • 2 => ‘Shop now’

    • 3 => ‘Sign up’

    • 4 => ‘Watch more’

    • 5 => ‘Subscribe’

    • 6 => ‘Book now’

    • 7 => ‘Apply now’

    • 8 => ‘Get quote’

    • 9 => ‘Donate now’

    • ads_params[cta_link_url] - where you want to link your CTA button and image to.

  3. Other optional body keypairs:

    • ads_params[blogless_is_rebloggable] - 0 to disable reblogging

    • ads_params[blogless_is_likeable] - 0 to disable likes

    • ads_params[cta_android_link_url] - optional, link for Android-specific devices

    • ads_params[cta_ios_link_url] - optional, link for iOS-specific devices

    • Tags - comma-separated list

This is illustrated in the screen below:

form encoded

To create a new Photo Post, follow these steps:

  1. Create a Blog-less Photo Post with CTA with this endpoint:

https://api.tumblr.com/v2/blog/[BLOG_NAME without .tumblr.com]/post

For example:

https://api.tumblr.com/v2/blog/myswimmingbananacollectorfan/post
  1. Header keypair:

    • Authorization - OAuth 1.0

  2. Body keypairs:

    • type - photo

    • source - Photo URL

    • ads_params[cta_text_code]

    • 0 => ‘Learn more’

    • 1 => ‘Contact us’

    • 2 => ‘Shop now’

    • 3 => ‘Sign up’

    • 4 => ‘Watch more’

    • 5 => ‘Subscribe’

    • 6 => ‘Book now’

    • 7 => ‘Apply now’

    • 8 => ‘Get quote’

    • 9 => ‘Donate now’

    • ads_params[cta_link_url] - where you want to link your CTA button and image to.

  1. Other optional body keypairs:

    • ads_params[blogless_is_rebloggable] - 0 to disable reblogging

    • ads_params[blogless_is_likeable] - 0 to disable likes

    • ads_params[cta_android_link_url] - optional, link for Android-specific devices

    • ads_params[cta_ios_link_url] - optional, link for iOS-specific devices

    • Tags - comma-separated list

This is illustrated in the screen below:

photo post

Manage Campaigns

To manage your campaigns, two options are available:

  • The Tumblr API (Option A). Note that your IP Addresses will need to be whitelisted. You’ll need to provide the range of IPs from which you’ll be sending the calls. One advantage of using this API is that ad groups are auto-generated when you create a campaign.

  • The Native & Search API (Option B)

Examples for both options are described in the following sections.

Option A - Use Tumblr API

Tumblr Campaign Management API uses a separate set of Ids from Native & Search. Ensure that you’re using the IDs generated from the Tumblr calls only.

Note

Tumblr Campaign Management calls require that your IP Addresses are whitelisted. You’ll need to provide a list of IP addresses from which you’ll be sending requests.

To create the Native & Search Campaign and AdGroup

  1. Choose a lifetime budget with an endDate or a Daily budget with no endDate.

  2. Enter your campaign details in the body.

  3. Enter your Tumblr Advertiser Id in the URI.

The steps are illustrated in the screen below:

campaign management

To create the Tumblr Ad

  1. Take the campaign ID from your campaign creation or get campaigns call, as shown in the screen below.

  2. Name your Ad and enter that name in the Tumblr Post URL.

campaign management post call

Option B - Use Native API

The Native API calls follow the same format as the usual Native & Search Campaign Management workflow.

For example:

Create a new Native & Search campaign

Method: To create a new campaign, make a POST call to the Campaign endpoint with the required fields.

POST https://api.gemini.yahoo.com/v3/rest/campaign

  {
      "advertiserId":1583838,
      "budget":1000,
      "bid": 10,
      "budgetType":"DAILY",
      "campaignName":"Tumblr Test1",
      "channel":"NATIVE",
      "objective": "SOCIAL_ENGAGEMENT",
      "status":"PAUSED"
  }

Create a new Native & Search adgroup

Method: To create a new adgroup, make a POST call to the adgroup endpoint with the required fields.

POST https://api.gemini.yahoo.com/v3/rest/adgroup

  {
       "status": "ACTIVE",
       "adGroupName": "Sample Tumblr Ad Group",
       "advertiserId": 1583838,
       "campaignId": 365799644,
       "startDateStr": "2018-03-01",
       "advancedGeoPos": "DEFAULT",
       "advancedGeoNeg": "DEFAULT",
       "biddingStrategy": "DEFAULT",
       "ecpaGoal":null,
       "bidSet": {
           "bids": [
               {
                     "priceType": "CPE",
                     "value": ".1",
                     "channel": "NATIVE"
               }
             ]
         }
      }

Create a new Tumblr ad

Method: To create a new Tumblr ad, make a POST call to the ad endpoint with the required fields.

POST https://api.gemini.yahoo.com/v3/rest/ad/

{
       "advertiserId": 1583838,
       "campaignId": 365799644,
       "adGroupId": 9689635542,
       "status": "ACTIVE",
       "landingUrl": "https://myswimmingbananacollectorfan.tumblr.com/post/172081051522",
       "adFormat": "TUMBLR",
       "title": "Tumblr Ad",
       "description": "Tumblr Ad",
       "displayUrl": "www.yahoo.com",
       "sponsoredBy": "www.yahoo.com"
}

Use Tumblr & Native Cubes for Reporting

Tumblr reporting calls will display all impressions received, as well as sponsored-specific impressions.

Note

Tumblr reporting calls require that your IP Addresses are whitelisted. You’ll need to provide a list of IP addresses from which you’ll be sending requests.

To get analytics for social cubes:

  1. Use this endpoint

https://ads-api.tumblr.com/v1/advertisers//analytics/social
  1. The endpoint will accept JSON describing the results that you want.

analytics social cube analytics social cube json

To get analytics for paid cubes:

  1. Use this endpoint

https://ads-api.tumblr.com/v1/advertisers//analytics/paid
  1. The endpoint will accept JSON describing the results that you want.

analytics paid cube analytics-paid-cube-json

Native Cube User Stats

Native cube user_stats are described in Reporting Cubes.

All user_stats fields are supported. Tumblr-specific fields are listed below:

"field": "Reblogs"
    },
    {
        "field": "Reblog Rate"
    },
    {
        "field": "Likes"
    },
    {
        "field": "Like Rate"
    },
    {
        "field": "Follows"
    },
    {
        "field": "Follow Rate"
    },
    {
        "field": "Engagements"
    },
    {
        "field": "Engagement Rate"
    }

FAQs

Whom do I contact if I have questions or issues for support?

ads-API@tumblr.com cc: Native Account Team.

What if I run into an Unauthorized error?

Make sure you refresh your OAuth 1.0a Signature.

I am unable to see my CTA buttons when I visit my blog.

You can only see your CTA buttons in your Tumblr feed and mobile app.

Can I enable Tumblr at the MDM level?

Currently, Tumblr can only be enabled at the Account level.