API ReferenceCommunity DiscussionAnnouncements
API ReferenceAnnouncementsCommunity Discussion
API ReferenceCommunity DiscussionAnnouncementsLog In
API Reference
Start typing to search…

Postal Code Targeting Flow

📘

General Guidelines

  1. Apply country targeting (via the campaigns endpoint) for 1 country only.
  2. Apply postal code targeting (via the targeting endpoint) for the targeted country.

Sample Flow 1 - Apply Postal Code Targeting

  1. Fetch a newly created campaign, using the campaigns resource. In the example below, the campaign has no country targeting or postal codes targeting (type = ALL):
GET /backstage/api/1.0/demo-advertiser/campaigns/1234
{
   "id": "1234"
   // other Campaign fields...
   "country_targeting": {
      "type": "ALL",
      "value": [],
      "href": null
   },
   // other Campaign fields...
   "postal_code_targeting": {
      "type": "ALL",
      "value": null,
      "href": "https://backstage.taboola.com/backstage/api/1.0/demo-advertiser/campaigns/1234/targeting/postal_code"
   }
}
📘

The endpoint stored by the href property for postal_code_targeting returns an empty array (i.e. no targeting).

  1. Update the country targeting, using the campaigns resource. Notice that the type is now INCLUDE and the value property contains the targeted collection (US):
POST /backstage/api/1.0/demo-advertiser/campaigns/1234
{
   "country_targeting": {
      "type": "INCLUDE",
      "value": [
         "US"
      ]
   }
}
{
   "id": "1234",
   // other Campaign fields...
   "country_targeting": {
      "type": "INCLUDE",
      "value": [
         "US"
      ],
      "href": null
   }
}
📘

The href property for country targeting is always null.

  1. Update postal code targeting, using the targeting resource (see previous topic):
POST /backstage/api/1.0/demo-advertiser/campaigns/1234/targeting/postal_code
{
    "type": "INCLUDE",
    "collection":[
            "10001",
            "10002",
            "10003 
    ]
}
{
    "type": "INCLUDE",
    "collection":[
            "10001",
            "10002",
            "10003 
    ]
}
📘

To fetch a list of supported postal codes for a given country, see: Get Postal Codes for a Country

  1. View the updated campaign object, using the campaigns resource. Notice that type is for postal code targeting has changed to INCLUDE:
GET /backstage/api/1.0/demo-advertiser/campaigns/1234
{
   "id": "1234",
   // other Campaign fields...
   "country_targeting": {
      "type": "INCLUDE",
      "value" : ["US"],
      "href": null
   },
   // other Campaign fields...
   "postal_code_targeting": {
      "type": "INCLUDE",
      "value": null,
      "href": "https://backstage.taboola.com/backstage/api/1.0/demo-advertiser/campaigns/1234/targeting/postal_code"
   }
}
📘

The value property for postal code targeting is always null.

  1. Invoke the endpoint reference stored in the href property of postal_code_targeting. The same Targeting Restrictions Object (from Step 3 above) is returned:
GET https://backstage.taboola.com/backstage/api/1.0/demo-advertiser/campaigns/1234/targeting/postal_code
{
    "type": "INCLUDE",
    "collection":[
            "10001",
            "10002",
            "10003 
    ]
}

Sample Flow 2 - Remove Postal Code Targeting

  1. Update postal code targeting, using the targeting resource (see previous topic). Set the type to ALL, without passing a value for collection (i.e. collection = null):
POST /backstage/api/1.0/demo-advertiser/campaigns/1234/targeting/postal_code
{
    "type": "ALL",
    "collection": null
}
{
    "collection": [],
    "type": "ALL"
}
  1. View the updated campaign object, using the campaigns resource. Notice that type is now ALL for postal code targeting:
GET /backstage/api/1.0/demo-advertiser/campaigns/1234
{
   "id": "1234",
   // other Campaign fields...
   "country_targeting": {
      "type": "INCLUDE",
      "value" : ["US"],
      "href": null
   },
   // other Campaign fields...
   "postal_code_targeting": {
      "type": "ALL",
      "value": null,
      "href": "https://backstage.taboola.com/backstage/api/1.0/demo-advertiser/campaigns/1234/targeting/postal_code"
   }
}
  1. Invoke the endpoint reference stored in the href property of postal_code_targeting. The same Target ALL response (from Step 2) is returned:
GET https://backstage.taboola.com/backstage/api/1.0/demo-advertiser/campaigns/1234/targeting/postal_code
{
    "collection": [],
    "type": "ALL"
}