Data Integrations with Campaign Management Platforms

Overview

ZipRecruiter exchanges data with 3rd party campaign management platforms to enable click tracking, conversion reporting, and bid management. This document covers the bidirectional data feeds between ZipRecruiter and campaign management systems.

Data Flows at a Glance

Data Flow	Direction	Format	Delivery	Frequency
Job Feed with CPC Bids	Partner → ZR	XML feed	Hosted URL	4x daily (Feed Import)
Click Data	ZR → Partner	CSV	(S)FTP push	Intraday (15 min), trailing 7-day, monthly
Conversion Data	ZR → Partner	CSV	(S)FTP push	Intraday (15 min), trailing 7-day, monthly
Conversion Reporting	Partner → ZR	HTTPS GET	REST API	Real-time

Getting Started

To set up data integrations with ZipRecruiter:

1. Contact your ZipRecruiter Account Manager to request click and/or conversion data feeds. If you don't have an Account Manager, reach out to atsintegrations@ziprecruiter.com.
2. Provide (S)FTP credentials (hostname, username, password, optional path) where ZipRecruiter should push click and conversion CSV files.
3. Configure your XML job feed with per-job <cpc> bids and, for ZipApply campaigns, <tracking_code> in <partner_attributes>.
4. Set up campaign-level settings with your Account Manager — including floor bids, below-floor handling, bid management preferences, and feed frequency.
5. For inbound conversion reporting, configure your campaigns to append &cid=[click_id] to job URLs and implement the conversion API endpoint.

tip

Your Account Manager handles campaign setup, bid management configuration, and feed activation. All technical specifications are documented below.

---

XML Feed Requirements

Client XML Feeds

Client XML feeds should match ZipRecruiter's standard Feed Import spec. Your ZipRecruiter Account Manager is responsible for uploading client XML feeds into the ZipRecruiter Marketplace.

Per-Job CPC Bids

You can set cost-per-click bids at the job level by adding <cpc>value</cpc> to each job in your feed.

Formatting requirements

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

Currency considerations

• Bids with a 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 regardless.

Billing considerations

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

Below-floor bid handling

When a job-level CPC is below the campaign's floor bid (minimum bid), one of two behaviors applies:

1. Bid up to the floor — The floor bid overrides the lower bid in the feed. The job is included in the campaign at the floor price.
2. Dropped — Jobs with bids below the floor are excluded from the sponsored campaign entirely.

The bid management setting is configured by your ZipRecruiter Account Manager during campaign setup.

ZipApply Feed Requirement

Required for ZipApply Campaigns

Without a tracking_code, ZipRecruiter cannot attribute spend at the job level. Click and conversion feed files will have an empty tracking_code column, making it impossible to reconcile costs per job.

Each ZipApply job in your XML feed must include a <partner_attributes> tag with a <tracking_code> sub-tag. The tracking code is a unique identifier from the 3rd party system.

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

ZipRecruiter passes this tracking code back in both click and conversion feed files, within the tracking_code column.

---

Feed Delivery

Click and conversion data feeds share the same delivery schedule, transmission method, and timezone conventions.

Feed Frequency

Schedule	Description
Intraday	Events in batches of 15 minutes, delivered as frequently as possible. Files always contain exactly 15 minutes of events.
Trailing 7-day	Events from the last 7 complete days, shared daily. Allows re-stated or re-published data to be available within a day. Can also be used without intraday feeds.
Monthly	Events from the previous calendar month in a single file. Useful for auditing and true-up of intraday feeds.

Feed Naming Conventions

Click feeds use the format vendor-BEGIN-END.csv. Conversion feeds append _conv: vendor-BEGIN-END_conv.csv.

Feed Frequency	Click Feed Example	Conversion Feed Example
Intraday	dsp-20170120T2300-20170120T2315.csv	dsp-20170120T2300-20170120T2315_conv.csv
Trailing 7-day	dsp-20170119T0800-20170120T0800.csv	dsp-20170119T0800-20170120T0800_conv.csv
Monthly	dsp-20161201T0800-20170101T0800.csv	dsp-20161201T0800-20170101T0800_conv.csv

Feed Transmission

ZipRecruiter pushes 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)

Timezones

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 also based on Pacific Time.

---

Click and Conversion Feed Schemas

Both feeds share a set of common columns. The conversion feed includes additional columns for delivery tracking.

Common columns (shared by click and conversion feeds)

Column	Data Type	Description	Example
campaign_id	hexadecimal	ZipRecruiter campaign identifier	abcd1234
campaign_name	string	ZipRecruiter campaign name (mutable)	agency_client_name_cpc
user_agent	string	Browser user agent string	Mozilla/5.0 ...
timestamp	date time	Event timestamp (UTC)	2016-01-01 08:00:17
job_id	string	The <referencenumber> provided in the partner's XML feed.	campaignname-10ab9480
job_url	string	External apply job URL
currency_code	string	Currency for cost field	USD
tracking_code	string	Job identifier provided by partner in feed, for ZipApply tracking
cost_model	string	Campaign cost model: cpc (cost per click), cpa (cost per apply), or none (no active budget)	cpc

Click-specific columns

Column	Data Type	Description	Example
click_cost	currency/float	Rate assigned at time of click. If cost_model is cpa, this is 0.	1.07
click_id	string	ZipRecruiter unique identifier for click	20613789540

Conversion-specific columns

Column	Data Type	Description	Example
cpa_cost	currency/float	Rate assigned at time of conversion. If cost_model is cpc, this is 0.	2
conversion_id	string	ZipRecruiter unique identifier for conversion	20613789540
delivered	string	Whether the application was successfully delivered to the ATS. Values: skip (not supported), true (delivered), false (failed), n/a (external applies).	skip
ext_application_id	string	External application ID returned by the ATS	id value or NA

note

For ZipApply conversions, user_agent is null in the conversion feed — the application is submitted through ZipRecruiter rather than via an external click.

---

Conversion Reporting (3rd Party → ZipRecruiter)

For External Apply (or ZipApply-Lite) campaigns, partners can report conversions back to ZipRecruiter via a REST API.

Campaign Setup

For server-to-server conversion tracking, ZipRecruiter appends a unique click identifier to each job URL. When a conversion occurs, the partner sends the click identifier back to ZipRecruiter with the conversion details.

Your Account Manager must configure each campaign to append the click ID macro to job URLs. The recommended parameter name is cid:

&cid=[click_id]

On each job seeker click, [click_id] is replaced with a unique click ID.

Additional macros for partner tracking:

Macro	Description
&bid=[cpc]	Expected bid for the click (base64 URL-safe encoded)
&time=[time]	Click timestamp in epoch seconds (base64 URL-safe encoded)

note

The &bid=[cpc] value is the expected bid, not the final charged amount. Some clicks may be invalidated during processing (bots, duplicates, exhausted budget, etc.) and marked as unpaid ($0) in click feed files. The click feeds are the definitive source of truth for billing.

HTTPS Request Parameters

Send conversion data as an HTTPS GET to:

https://track.ziprecruiter.com/marketplace/v1/conversion

Request parameters

Field	Type	Required	Description
ts	integer	Yes	Timestamp of apply, in epoch seconds (UTC)
click_id	string	Yes	ZipRecruiter's click identifier
apply_id	string	Yes	Apply identifier, as defined by the sender
vendor	string	Yes	Name of vendor sending the apply data
job_id	string	No	Job reference, as provided in the client feed
user_agent	string	No	User agent string
paid	boolean	No	Whether this conversion is billable in the agency's platform. Only true/false accepted.
default_campaign	boolean	No	Whether this conversion is in the default (catch-all, non-billable) campaign. Only true/false accepted.

Example

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