Data Sharing Files

Overview

ZipRecruiter shares click, cost, and conversion data with 3rd party campaign management platforms via CSV files delivered over (S)FTP, and accepts conversion data back via a REST API.

Data Exchange

XML Feed from 3rd Party to ZipRecruiter

Client XML feeds should match ZipRecruiter's XML Feed specs. See the Feed Import documentation for details.

The ZipRecruiter Account Manager is responsible for uploading client XML feeds into ZipRecruiter Marketplace.

Setting Bids at the Job Level (Per-Job CPC Bids)

You must add <cpc>value</cpc> to each job within the feed.

CPC formatting rules

• Bids with or without decimal places are accepted (e.g., <cpc>1.00</cpc> and <cpc>1</cpc>).
• Max CPC is $100.00 (USD). Values above this are ignored.
• Maximum precision is a tenth of a penny (e.g., <cpc>0.163</cpc>).
• If the CPC value is missing or empty (<cpc></cpc>), it defaults to the campaign's CPC at send-time.

Currency considerations

While bids with three digit currency code or currency symbol prepended are accepted, the currency associated with the campaign is assumed. For example, <cpc>USD1.00</cpc> and <cpc>$1.23</cpc> are accepted, but the campaign's currency is used.

Billing considerations

The CPC charged is based on send-time of the alert, not click-time.

Options for Handling "Below Floor" Job-Level Bids

1. Bid up to the floor — If the CPC value in the feed is less than the floor bid/minimum bid set at the campaign level, the floor bid will override all lower bids within the feed.
2. Dropped — If the CPC value in the feed is less than the floor bid set at the campaign level, those roles will be excluded from the sponsored campaign.

note

Bid Management settings are set by ZipRecruiter account manager during campaign set up.

ZipApply Feed Requirement

For ZipApply campaigns, each job should include a <partner_attributes> tag with a <tracking_code>. The tracking code is a unique identifier derived from the third party system.

Example XML

<partner_attributes>
  <tracking_code>am-334kt_1</tracking_code>
</partner_attributes>

ZipRecruiter will pass this data back to the third party in both the click and conversion files, within the tracking_code column.

---

Click Data from ZipRecruiter to 3rd Party

Enabled for External Apply and ZipApply campaigns.

Feed Frequency

Two core tenets drive the approach for data frequency:

1. Share data as quickly as possible after events are logged and validated.
2. Share updates to data as quickly as possible in cases where data must be re-stated or re-published.

Supported data sharing schedules

Schedule	Description
Intra-day	Events in batches of 15 minutes of activity, delivered as frequently as possible. Files always contain exactly 15 minutes worth of events.
Trailing 7-day	Events from the last 7 complete days, shared daily. Allows for a true-up of re-published data within a day of the re-publication. Can also be used without intra-day feeds.
Monthly	Events from the previous calendar month, shared in a single large feed. Useful for auditing and true-up of intra-day feeds.

Feed Naming Conventions

File naming format

Feed Frequency	File Name Format	Example (using 'dsp' as vendor name)
Intraday	vendor-BEGIN-END.csv	dsp-20170120T2300-20170120T2315.csv
Trailing 7 day	vendor-BEGIN-END.csv	dsp-20170119T0800-20170120T0800.csv
Monthly	vendor-BEGIN-END.csv	dsp-20161201T0800-20170101T0800.csv

Feed Content

Click feed columns

Column Name	Data Type	Description	Example
campaign_id	hexadecimal	ZipRecruiter campaign identifier	abcd1234
campaign_name	string	ZipRecruiter (mutable) campaign name	agency_client_name_cpc
user_agent	string	Click browser user_agent string	Mozilla/5.0 (Windows NT 6.1; WOW64) ...
timestamp	date time	Click timestamp	2016-01-01 08:00:17
click_cost	currency/float	Rate assigned at time of click. If cost_model is CPA then click_cost will be 0.	1.07
job_id	string	The <referencenumber> provided in the partner's XML feed.	campaignname-10ab9480
click_id	string	ZipRecruiter unique identifier for click	20613789540
job_url	string	External apply job URL
currency_code	string	Currency for click_cost	USD
tracking_code	string	A unique job identifier provided by partner in job feed, for ZipApply tracking
cost_model	string	Campaign cost model. Possible values: cpc (cost per click), cpa (cost per apply), none (no active budget).	cpc

Timezone Considerations

All dates/times in the feeds and file names are in UTC. However, the day/month ranges used to generate the files are based on Pacific Time. ZipRecruiter Marketplace dashboard reporting is based on Pacific Time.

Feed Transmission

ZipRecruiter will push data files to an (S)FTP location determined by the campaign management platform. ZipRecruiter does not host an (S)FTP server.

FTP details required

• Hostname
• Username
• Password
• Path (optional)

---

Conversion Data from ZipRecruiter to 3rd Party

Feed Frequency

Same as click data.

Feed Naming Conventions

File naming format

Feed Frequency	File Name Format	Example (using 'dsp' as vendor name)
Intraday	vendor-BEGIN-END_conv.csv	dsp-20170120T2300-20170120T2315_conv.csv
Trailing 7 day	vendor-BEGIN-END_conv.csv	dsp-20170119T0800-20170120T0800_conv.csv
Monthly	vendor-BEGIN-END_conv.csv	dsp-20161201T0800-20170101T0800_conv.csv

Feed Content

Conversion feed columns

Column Name	Data Type	Description	Example
campaign_id	hexadecimal	ZipRecruiter campaign identifier	abcd1234
campaign_name	string	ZipRecruiter (mutable) campaign name	agency_client_name_cpc
user_agent	string	Browser user_agent string. For ZipApply conversions, this field will be null.	Mozilla/5.0 ...
timestamp	date time	Conversion timestamp	2016-01-01 08:00:17
cpa_cost	currency/float	Rate assigned at time of conversion. If cost_model is CPC then cpa_cost is 0.	2
job_id	string	The <referencenumber> provided in the partner's XML feed.	campaignname-10ab9480
conversion_id	string	ZipRecruiter unique identifier for conversion	20613789540
job_url	string	External Apply job URL
currency_code	string	Currency for cpa_cost (always USD)	USD
tracking_code	string	A unique job identifier provided by partner in job feed, for ZipApply tracking
cost_model	string	Campaign cost model. Possible values: cpc, cpa, none.	cpc
delivered	string	Confirmation signal if the application was successfully delivered or not to ATS (not yet available for all integrations). Values: skip, true, false, n/a.	skip
ext_application_id	string	The returned external application id from the ATS (not yet available for all integrations).	id value or NA

Timezone / Transmission / Feed Requirement

Same as click data.

---

Conversion Data from 3rd Party to ZipRecruiter

For External Apply (or ZipApply-Lite) campaigns.

In cases where the advertiser is unable to implement a ZipRecruiter conversion tag, we support a server-to-server conversion data integration. ZipRecruiter appends a unique click identifier to the job URL, and the advertiser sends back a file of each successful conversion.

Campaign Setup

The ZipRecruiter account manager must ensure that each campaign is configured to append the appropriate query argument name and value. Typically we recommend cid as the argument name:

&cid=[click_id]

Upon a job seeker click, the [click_id] macro is replaced in real-time with a unique click ID.

Additional supported macros

• &bid=[cpc] (format: decimal)
• &time=[time] (format: Epoch time in seconds)

Upon a job seeker click, the [cpc] and [time] macros are replaced in real-time with a base64 URL-safe encoded CPC and click timestamp.

note

The &bid=[cpc] value represents the expected bid for each click. However, these are unprocessed clicks. During click processing, some clicks may be flagged as invalid (e.g., bots, duplicates, exhausted budget, foreign, etc.), meaning they could be marked as unpaid ($0) in your click cost sharing files. The click cost sharing files remain the definitive source of truth for all click accounting and billing.

Feed Frequency

ZipRecruiter prefers to receive the data as close to real time as possible via a webhook-style REST API endpoint.

HTTPS Request Parameters

Request parameters

Field	Type	Description	Required
ts	date time	Timestamp of apply, in epoch seconds, in UTC	Yes
click_id	string	ZipRecruiter's click identifier	Yes
apply_id	string	Apply identifier, as defined by the sender of the apply data	Yes
job_id	string	Job reference, as provided to ZipRecruiter in the client feed	No
user_agent	string	User agent	No
vendor	string	Name of vendor (i.e., the sender of the apply data)	Yes
paid	boolean	Signals if a conversion is considered paid or unpaid in the agency's platform (only true/false; null is not valid)	No
default_campaign	boolean	Signifies if the conversion occurred within the default campaign, a catch-all, non-billable campaign (only true/false; null is not valid)	No

API Examples

Example conversion API call

Template:

https://track.ziprecruiter.com/marketplace/v1/conversion?ts={timestamp}&click_id={cid}&apply_id={id}&job_id={job_reference}&user_agent={user_agent}&vendor=name&paid={true/false}&default_campaign={true/false}

Example with values:

https://track.ziprecruiter.com/marketplace/v1/conversion?ts=1478332620&click_id=36c743d7-17d3-4b02-b65f-ab13715e4508&apply_id=5320410666&job_id=1071_683506&user_agent=Mozilla%2F5.0+%28Windows+NT+6.1%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F54.0.2840.71+Safari%2F537.36&vendor=name&paid=true&default_campaign=false

Timezone Considerations

Timestamp of the apply, in epoch seconds, in UTC.