Skip to main content

Assigning Jobs to Job Campaign Objects

Overview​

Before you set a Campaign or Event live, you should first assign jobs to your corresponding Job Campaign object. Jobs are filtered into Job Campaigns based on rules contained within the jobCampaigns.jobFilters field. A Job Campaign's job filters are run against the jobs in the Job Campaign's Job Pool and those jobs that match the filter are assigned to the Job Campaign.

Job Filters might overlap between Job Campaigns. To account for this, Job Campaigns have a priority order field that determines the order that Job Campaign filter rules apply. Once a job is assigned to a Job Campaign it cannot be assigned to another Job Campaign.

caution

Job Filters apply to both Campaigns (Job Campaigns with an adType value of JOB) and Events (Job Campaigns with an adType value of EVENT) objects. Furthermore, both Campaigns and Events assigned to the same Job Pool share all the jobs in that pool when applying their filters, effectively competing for the same jobs. You will want to keep this in mind when setting the Priority Order for your Job Campaign objects (see below).

Priority Order​

Within a single Job Pool, Job Campaigns have a priority order that will dictate in what order the Job Campaign objects have their filters applied to the jobs within the Job Pool. Jobs that match a Job Campaign's filter will be assigned to that Job Campaign. This order value is stored in the jobCampaign.applyOrder field. Job Campaigns with the highest priority order value will have their job filters applied first, followed by other Job Campaigns within the same pool in descending order of priority order value.

Filters on Job Campaign Objects​

There are a variety of job fields that can be used as filters to help assign jobs to Job Campaigns. These filters are set within the jobCampaigns.jobFilters field as an array of values. A single Job Campaign can be filtered by multiple fields, and only jobs which haven't already been assigned to a higher-ordered Job Campaign and that meet all of the field filters will be assigned to the Job Campaign. Below are examples of all the different fields on which a Job Campaign can be filtered:

Job Reference​

You can filter jobs into a Job Campaign by their reference number. This is the easiest way to get specific jobs into a specific Job Campaign.

The following example request to PATCH /campaigns/{campaignId} endpoint would update a Job Campaign (Id:12345) to filter in jobs with the reference values of either "abc123" or "def_456":

curl -X 'PATCH' \
  'https://api.talroo.com/v5/campaigns/12345' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "jobFilters": {
        "jobReference": ["abc123" , "def_456"]
    }
    }'

Zip Code​

You can filter jobs into a Job Campaign by their zip code.

The following example request to PATCH /campaigns/{campaignId} endpoint would update a Job Campaign (Id:12345) to filter in jobs with zip code values of either "78745" or "78756":

curl -X 'PATCH' \
  'https://api.talroo.com/v5/campaigns/12345' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "jobFilters": {
        "zipCode": ["78745" , "78756"]
    }
    }'

City, St​

You can filter jobs into a Job Campaign by their "City,ST" values.

The following example request to PATCH /campaigns/{campaignId} endpoint would update a Job Campaign (Id:12345) to filter in jobs with City,ST values of either "Austin,TX" or "Round Rock,TX":

curl -X 'PATCH' \
  'https://api.talroo.com/v5/campaigns/12345' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "jobFilters": {
        "city": ["Austin,TX", "Round Rock,TX"]
    }
    }'

State Id​

You can filter jobs into the campaigns by Talroo State Ids. These State ids can be found with the GET /locations/us/states endpoint.

The following example request to PATCH /campaigns/{campaignId} endpoint would update a Job Campaign (Id:12345) to filter in jobs with stateId values of either 44 or 19:

curl -X 'PATCH' \
  'https://api.talroo.com/v5/campaigns/12345' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "jobFilters": {
        "state": [44, 19]
    }
    }'

Title​

You can filter jobs into a Job Campaign by strings contained in their title.

The following example request to PATCH /campaigns/{campaignId} endpoint would update a Job Campaign (Id:12345) to filter in jobs with titles that contain either the string "merch stocker" or "overnight stocker":

curl -X 'PATCH' \
  'https://api.talroo.com/v5/campaigns/12345' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "jobFilters": {
        "title": ["merchandiser", "overnight stocker"]
    }
    }'

Description​

You can filter jobs into a Job Campaign by strings contained in their description.

The following example request to PATCH /campaigns/{campaignId} endpoint would update a Job Campaign (Id:12345) to filter in jobs with descriptions that contain either the string "hiring now" or "#talroo":

curl -X 'PATCH' \
  'https://api.talroo.com/v5/campaigns/12345' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "jobFilters": {
        "description": ["hiring now", "#talroo"]
    }
    }'

Company Id​

You can filter jobs into a Job Campaign by their Talroo company id. These company ids can be found with the GET /customers/me/companies endpoint.

The following example request to PATCH /campaigns/{campaignId} endpoint would update a Job Campaign (Id:12345) to filter in jobs with companyId values of either 12345 or 567890:

curl -X 'PATCH' \
  'https://api.talroo.com/v5/campaigns/12345' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "jobFilters": {
        "companyId": [12345, 567890]
    }
    }'

Major Category Ids​

You can filter jobs into a Job Campaign by their Talroo Major Category Ids. These Major Category Ids can be found on the jobs themselves using the GET customers/me/jobs endpoint. You can see our list of Major Category Ids here.

The following example request to PATCH /campaigns/{campaignId} endpoint would update a Job Campaign (Id:12345) to filter in jobs with Major Category Id values of either "340000" or "330000":

curl -X 'PATCH' \
  'https://api.talroo.com/v5/campaigns/12345' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "jobFilters": {
        "majorCategory": ["340000", "330000"]
    }
    }'

Minor Category Ids​

You can filter jobs into the campaign by their Talroo Minor Category ids. These Minor Category Ids can be found on the jobs themselves using the GET customers/me/jobs endpoint. You can see our list of Minor Category Ids here. Example value:

The following example request to PATCH /campaigns/{campaignId} endpoint would update a Job Campaign (Id:12345) to filter in jobs with Minor Category Id values of either "340040" or "340060":

curl -X 'PATCH' \
  'https://api.talroo.com/v5/campaigns/12345' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "jobFilters": {
        "minorCategory": ["340040", "340060"]
    }
    }'

Job level Campaign Ids​

You can filter jobs into the campaign with values passed through a <campaign_id> node included in your job feed. You must be passing integer values through a <campaign_id> node within your feed for this filtering method to work.

note

The values passed in the <campaign_id> node and used to filter jobs do not have to match any Talroo Job Campaign Id's

The following example request to PATCH /campaigns/{campaignId} endpoint would update a Job Campaign (Id:12345) to filter in jobs with srcCampId values of either 12345 or 4567:

curl -X 'PATCH' \
  'https://api.talroo.com/v5/campaigns/12345' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "jobFilters": {
        "srcCampId": [12345, 4567]
    }
    }'

Job level Segment Ids​

You can filter jobs into the campaign with values passed through a <segment_id> node included in your job feed. You must be passing integer values through a <segment_id> node within your feed for this filtering method to work.

note

The values passed in the <segment_id> node and used to filter jobs do not have to match any Talroo Job Segment Id's

The following example request to PATCH /campaigns/{campaignId} endpoint would update a Job Campaign (Id:12345) to filter in jobs with srcSegId values of either 12345 or 4567:

curl -X 'PATCH' \
  'https://api.talroo.com/v5/campaigns/12345' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -d '{
    "jobFilters": {
        "srcSegId": [12345, 4567]
    }
    }'