Skip to main content

Creating Campaigns

Overview​

Nearly all Campaign management is performed with the Job Campaigns endpoints. Campaigns utilize the Job Campaign object (Events also utilize the Job Campaigns object). The following pages describe the different settings that we can declare for a Campaign. While it is possible to create a Campaign with most, if not all, of these settings in one call, for clarity, this guide details the declaration of these settings as updates to an already created Campaign.

Decide which Job Pool​

Before creating a Campaign you will need to pick which Job Pool you would like to create your Campaign in. You can view the Job Pools in your Job Customer with the GET /customers/me/pools endpoint. The example call below would return your Job Pools:

curl -X 'GET' \
  'https://api.talroo.com/v5/customers/me/pools?page=0&size=20' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {Access Token}'
note

If you do not have a Job Pool in your Job Customer to create a Campaign under, please work with your Talroo POC to have one created. Additionally, please confirm with your Talroo POC which Job Pool should be used for Campaign creation.

Create Campaign​

Once you have your Job Pool Id that you would like to create your new Campaign under, you can use the POST /pools/{poolId}/campaigns endpoint to create your new Campaign. Campaigns require values for the name and adType fields on creation.

The following example request to the POST /pools/{poolId}/campaigns endpoint would create a new Campaign Job Campaign under the Job Pool with Id:1234 with the name "New Test Campaign":

curl -X 'POST' \ 'https://api.talroo.com/v5/pools/1234/campaigns' \ 
-H 'accept: application/json' \ 
-H 'Authorization: Bearer {accessToken}' \ 
-H 'Content-Type: application/json' \ 
-d '{ 
      "name": "New Test Campaign",
      "adType": "JOB" 
    }'
note

It is the adType value of "JOB" that designates this Job Campaign object as a Campaign.

Campaign Statuses​

All Campaigns will have a status that can help you determine what state a Campaign is in. For example, all Campaigns are created in a draft state and will have a Status value of UNDER_DEVELOPMENT. This status can be found in the jobCampaign.status field. The full list of Campaign Statuses and their implications can be seen below:

  • UNDER_DEVELOPMENT: This is the status Campaigns will have only after they are initially created and before they are either launched or archived. After a Campaign leaves the UNDER_DEVELOPMENT status, it cannot return to the UNDER_DEVELOPMENT status.
  • LIVE: This status indicates a Campaign is live within the Talroo Marketplace. Jobs in this Campaign (that are not in Segments with a nonlive Status) will be live and able to receive traffic. Campaigns are set to the LIVE status when:
    • they are launched with the POST /campaigns/{campaignId}/launch endpoint
    • they have a One Time Budget with launchOnStart set to true which will set them LIVE as soon as the One Time Budget period starts.
  • PAUSED: This status indicates a Campaign has been manually paused by either a scheduled pause or a direct pause using the POST /campaigns/{campaignId}/pause endpoint. Jobs in a paused campaign are not advertised on the Talroo Marketplace and will not receive traffic.
  • OUT_OF_BUDGET: This status indicates a Campaign has depleted its budget. Jobs in an OUT_OF_BUDGET campaign are not advertised on the Talroo Marketplace and will not receive traffic.
  • ARCHIVED: This status indicates a Campaign has been manually archived with the POST /campaigns/{campaignId}/archive endpoint. Once a Campaign is archived, it cannot be unarchived.