Candidate/Submission Source Tracking

Released with version 3.5.0, the Candidate/Submission Source Tracking feature is available automatically to all users of Matador Jobs Pro and Matador Jobs Pro All-Access, and is included in the core Matador Jobs plugin.

This feature requires PHP 7.0, and will not load if your server is still on PHP 5.6.x or prior versions.


The Candidate/Submission Source Tracking feature helps to communicate to the recruiter where a candidate and/or job submission originated from.

Prior to this feature’s release, when a candidate, job submission, or web response was created in Bullhorn by Matador, the “source” for the candidate was listed as “XYZ Website,” where XYZ was the name of website as set in the WordPress settings.

Our users wanted to know more, including and especially “how did this user end up on my website?” We were also often asked “is Google for Jobs working for my jobs?” and “I’m driving paid traffic to my site, so how can I tell if the applications are from paid or organic traffic?”

When Matador Jobs Pro 3.5.0 or higher is installed and the setting is turned on, Matador will attempt to gather information about a user who visits the site and then append the “source” for the candidate, web response, or job submission in Bullhorn with useful data. Now, the “source” will be listed something like “XYZ Website (” or “XYZ Website (advertiser/ppc/campaign name).”

How it Works

  • When a user visits a Matador-enabled site, Matador will try to determine their source.
    • Matador will create a cookie on the user’s browser to temporarily store this data for up to 48 hours, if Javascript is enabled.
    • If an application form is on the page, Matador will pass this data along with any form submission as well.
  • When an application form is submitted, Matador will first attempt to read the cookie. If it can’t, it means the user has Javascript disabled or cookies blocked, and Matador will fall back to reading the hidden form data, if present. This information will be saved into the application data object.
  • Either immediately or in a batch process later, when the application data object is processed into a Candidate and/or a Job Submission or Web Response, Matador will read any Source data and generate a descriptive string based on the data present. This will be set as the source for both the Web Response or Job Submission as well as the Candidate, if the candidate was newly created.


  • In order to honor user privacy requests, Matador will fully abide by a web browser Do Not Track (DNT) setting. In the web development community, there is often disagreement on the application of the DNT setting. While some argue that it should be only apply for 3rd-party tracking while same-site tracking is okay as a trade off for using the services provided by the site, we chose to responsibly accept the DNT setting, and when a user has DNT set to on or true, Matador will not create the cookie, thus limiting Matador’s ability to track a user. This can be overridden with code, but we discourage it.
  • Same goes for if should a user choose to block cookies, has a browser plugin that blocks/accepts cookies on a per-cookie basis, or altogether disables Javascript. In those cases, the cookie also will not be created, thus limiting Matador’s ability to track a user.
  • Matador detects the world’s 6 largest search engines and the world’s 6 largest social networks when detecting if a medium is “organic,” or search traffic, or “social.” It is important a website operator adds locally popular search engines or social networks to the list of known search engines and social networks if this feature will be accurate for your locale.
  • In order to prevent bad input data, this feature is turned off for logged in users, which also makes it difficult to test. Site operators who wish to test this feature should use their site in incognito mode and/or enable WP_DEBUG.
  • Bullhorn limits the source field to 200 characters for Candidate objects and 100 characters for Job Submissions and Web Responses, which may result in truncated data. Use provided filters to shorten your website name, and ensure you use succinct UTM parameters to prevent running up against the character limit.
  • At this time, individual data points cannot be saved into their own candidate fields, ie customText1-30, etc, but the feature is on the roadmap.

Setting Up the Feature

In Matador settings, scroll down to the section Applications Privacy Settings. Toggle on the setting Collect User Traffic Information. That’s it!

Please note, upon turning this feature on, you should and/or may become obligated by local laws to update your Privacy Policy regarding how your site, via this Matador feature, tracks the user on your site.

Further, if you live in a jurisdiction where website visitors are presented with a choice allow or disallow cookies on your site, and your site uses site-level code to track that choice, you may need to extend Matador to ‘teach’ it how to listen to and honor a user’s choice.

Example Usage

This feature works two ways. The first is the automatic way, where it detects incoming traffic and makes assumptions about it. The second is the deliberate way, by which the site operate generates links that inform the source of the user.


Let’s say you, a site operator, just had a new job added to your Matador-enabled site. You think it is a great opportunity, so you copy-and-paste its URL and post it to Facebook. Someone in your network clicks on it and applies. The “source” for that candidate will look something like this:

XYZ Website (

Around the same time, a user on your site saw this job opportunity. They have access to a trade group discussion board. They post the job there. Someone clicks on it and applies. The “source” for that candidate will look something like this:

XYZ Website (

Deliberate (via UTM parameters)

The automatic source tracking is already incredibly useful, but it can get way more powerful when you create links deliberately. Since before Google purchased Google Analytics, a concept was proposed to help site operators track the efficiency of links, especially paid ads. These were the UTM parameters.

Lets say a job on your site has the following url:

If you are about to share this post on social media, you might want to track this effort. Let’s name this effort “Social Shares Sept 1 2019.” To make that name URL-safe, we will make everything lowercase and replace spaces with dashes, resulting in “social-shares-sept-1-2019.” This is “campaign” and we will append our original URL with a “utm_campaign” key and the name of your campaign:

Now let’s say this effort results in an application from your Facebook share! The “source” in your Bullhorn account for this applicant will be:

XYZ Website ( shares sept 1 2019)

You might be thinking, “oh, I don’t need to do all this work just for a Facebook share!” and you’re right. But, let’s say you are about to launch a $1000 ad spend for your job board. What if all of your jobs were appended with UTM parameters to track the efficiency of your ad spend?

This would result in the following source field:

XYZ Website (adsense/paid/sept ad spend)

There are many UTM link builder tools available for free all over the internet. Further, many WordPress plugins provide tools as well, including the popular Google Analytics and Traffic monitoring plugin Monster Insights. You might consider building custom URLs for your jobs for any of the following reasons:

  • A paid marketing campaign
  • A physical mailer that sends users to a special URL shortened link and redirects them to a fully realized URL with terms like “utm_campaign=mailer” and “utm_campaign=trades-jobs-mailer”.
  • All links in your newsletter (“utm_source=mail”).
  • All links in text messages (“utm_source=text”).
  • Any “share this job with a friend” feature on your website.

And so much more.

Related Actions & Filters

To support this feature, there are a number of actions and filters a developer or site operator might employ to extend or customize its usefulness.

matador_load_module_campaign_tracking (filter)

This filter controls whether the feature is loaded at all. Return false to turn off the feature completely, including hiding relevant settings.

matador_campaign_tracking_should_not_track (filter)

After the settings load but before the module truly kicks off, the module checks if the site should track. This is where a logged in user (administrator, editor, or author), for example, can disable the feature. Return true to this filter to disable tracking. This is useful if you have a server-level reasoning to disable tracking, ie: a user is logged in as another capability.

matador_campaign_tracking_cookie_options (filter)

The script that manages the tracking cookie has a robust number of options that site operators can adjust to customize its function. This filter allows a site operator to modify the options via PHP array operators, which are then converted into a JSON string and passed into the javascript class instantiator.

Note: use the specific filters to modify the source labels, query string keys, known social networks, and known search engines, as these are shared by the “backup” behavior of the feature when javascript is disabled.

matador_campaign_tracking_inline_javascript (filter)

When the site uses some Javascript level setting to track a user’s do not track setting, use this filter to add logic to the inline Javascript that initializes Matador Traffic monitoring. You must, in this script, set ‘matador_traffic’ to false if the desired result is to prevent loading. This is also where you can override Matador’s default adherence to DNT settings by setting ‘matador_traffic’ to true.

matador_campaign_tracking_source_separator (filter)

Change the separator character used in separating the data points in the source string. Default is a forward slash.

Note: Bullhorn limits the length of a source field to 40 to 80 characters depending on the entity. We discourage your use of such separators like space-dash-space as this may result in your string being truncated.

matador_data_source_description (filter)

While not new with this feature, this filter allows the modification of the source description, including sensitive to context. Traffic Source applies this filter at priority 25. Companies with long names for their website, ie: “Advanced Hiring Solutions Inc” could run this filter at priority 20 to make their name “AHS Inc” and then allow the Traffic Source feature to append traffic data to something like “AHS Inc (AdSense/paid/campaign name)”. This is especially useful when long company names are causing the campaign data to be shortened due to character limits.

matador_campaign_tracking_check_{$field}_against_whitelist (filter)

This filter turns on a whitelist for a given UTM_field. Since UTM_* parameters are public, some malicious users may try to send gibberish words in the parameters. While Matador includes security protections to prevent your site being compromised in this way, the gibberish could still be saved into your dataset. You can manage a whitelist of allowed terms and enable the whitelist by passing true to this filter (for the given $field).

matador_campaign_tracking_{$field}_whitelist (filter)

Pass an array of whitelisted terms to this filter. The whitelist for the field must be enabled first.

matador_campaign_tracking_cookie_name (filter)

Change the name of the cookie. Some users may install tools that block cookies with words that imply they are being tracked. The cookie name is ‘matador_traffic’ by default.

Note: Use this to modify cookie name instead of modifying the cookie name in the cookie options filter to ensure the cookie created can also be read.

matador_campaign_tracking_query_string_keys (filter)

Change the query string keys, if you’d like to use something other than UTM_*.

Note 1: Google for Jobs sends referrals with fully-formed UTM parameters, so this not advised.

Note 2: Use this to modify query string keys instead of modifying only the cookie with the cookie options filter.

matador_campaign_tracking_source_labels (filter)

Change the common values for source when auto-detected by matador. IE: when referral is from a known search engine, set source to ‘social’. It’s generally recommended you match your language’s Google Analytics labels if using Google Analytics.

Note: Use this to modify tracking source labels instead of modifying only the cookie with the cookie options filter.

matador_campaign_tracking_known_search_engines (filter)

Add/remove known search engines from the list a referrer will be checked against. This is a key/value array where the key is the name of the search engine and the value is an array of regex rules that detect the key’s common urls.

Default known search engines are: Google, Bing, Yahoo, AOL, Baidu, and DuckDuckGo.

Note: Use this to modify the known search engines instead of modifying only the cookie with the cookie options filter.

matador_campaign_tracking_known_social_networks (filter)

Add/remove known social networks from the list a referrer will be checked against. This is a key/value array where the key is the name of the social network and the value is an array of regex rules that detect the key’s common urls.

Default known Social Networks are: Facebook, LinkedIn, Twitter, Reddit, Instagram, and YouTube.

Note: Use this to modify the known search engines instead of modifying only the cookie with the cookie options filter.

Was this article helpful?
Yes 1 No 0