Help Center · Integrations
Connect Your CRM
Send candidates, shortlists, submissions and placements from PlacementFlow into your CRM, ATS or a spreadsheet: set up the Zapier app step by step, pick the right events, and meet the consent and erasure duties that come with the data.
18 min readOn this page
PlacementFlow can feed your CRM or ATS as work happens. A person engages, a recruiter shortlists them, a submission goes to a client, a placement is recorded. Each of these can create or update a record in the tool you already use.
This page covers:
- the three ways to connect
- how to set up the PlacementFlow Zapier app, step by step
- which events to use and what each one carries
- what you are responsible for once the data leaves PlacementFlow
Three ways to connect
| Way | Best for | Needs |
|---|---|---|
| 1. The PlacementFlow Zapier app | Most agencies. Ready-made triggers, no URLs to copy. | A Zapier account and an invite from us |
| 2. A generic webhook step | Make, n8n, or Zapier without our app | A tool that can receive webhooks |
| 3. Your own endpoint and the API | Agencies with a developer | An HTTPS endpoint you run |
1. The PlacementFlow Zapier app (invite-only)
PlacementFlow's Zapier app is invite-only. It is not listed in Zapier's public app directory, so searching Zapier for it will not find it until you accept the invite. Ask us for the invite link.
The app gives you:
- Triggers: Candidate Engaged, Candidate Shortlisted, Screening Completed, Submission Sent, Interview Scheduled, Placement Created, BD Prospect Qualified, Candidate Erased
- Action: Set Candidate External ID (writes your CRM's record id back onto the PlacementFlow candidate)
- Search: Find Candidate by Email
Setup is below, in Set up the Zapier app. Ready-made recipes:
- Zapier recipe: Google Sheets (the simplest place to start)
- Zapier recipe: Bullhorn
- Zapier recipe: Atlas
2. A generic webhook step (Webhooks by Zapier, Make, n8n)
If you would rather not use the Zapier app, point a generic webhook step at a PlacementFlow webhook:
- Zapier: "Webhooks by Zapier" with the Catch Hook trigger (Webhooks by Zapier is not on every Zapier plan; check Zapier's current plans)
- Make: the Webhooks → Custom webhook module
- n8n: the Webhook node
Copy the URL the tool gives you. Then create a webhook in Settings → Webhook Management with that URL and the events you want. There is no PlacementFlow app for Make or n8n; this generic path is the way to use them. Steps for Make and n8n are at the end of this page.
A webhook you create this way leaves out the private links described under Private links are off by default, like every other webhook, unless you turn them on.
3. Your own endpoint, through the API
If you have a developer, point a webhook at your own HTTPS endpoint and call the PlacementFlow REST API for anything else. Every delivery is signed (a legacy HMAC header and the Standard Webhooks headers). Every event's payload is described in the OpenAPI document at https://placementflow.com/api/v1/openapi.json. The API reference covers signature verification, secret rotation, retries and replays.
Set up the Zapier app
Before you start
- A Zapier account. Every useful recipe has at least one filter step plus an action, which makes it a multi-step Zap. Multi-step Zaps need a paid Zapier plan or a Zapier trial. Check Zapier's current plans before you build.
- The invite link to PlacementFlow's Zapier app. Ask us for it.
- Admin access in PlacementFlow, to create an API key, and a connected mailbox on your account (PlacementFlow asks for one before it issues a key).
- The tool you are sending to (Google Sheets, Bullhorn, Atlas), connected to Zapier under your own login.
Step 1: Accept the invite
- Open the invite link while signed in to Zapier.
- Accept the invite. PlacementFlow now appears when you search for apps inside the Zap editor.
Step 2: Create an API key
- In PlacementFlow, go to Settings → Integrations → API Settings.
- Click Generate API Key.
- Give it a name you will recognise later, for example "Zapier: Sheets log".
- Under Environment, pick Live for a Zap that feeds your real records. The environment is a label that helps you tell keys apart; it shows in Zapier's connection name.
- Under Access, pick Automation (Zapier/Make). This preset lets the key manage its own webhooks and read and write candidates. It cannot touch interviews or placements.
- Copy the key straight away. It is shown once. If you lose it, generate a new one.
Treat the key like a password. Anyone holding it can read your candidates.
Step 3: Connect PlacementFlow in Zapier
- In Zapier, create a Zap and choose PlacementFlow as the trigger app.
- Pick a trigger event, for example Candidate Shortlisted.
- When Zapier asks for an account, click to connect a new one and paste the API key.
- The connection appears as your agency's name followed by the key's environment, for example Acme Recruiting (live). If you see that name, the key works.
Step 4: Test the trigger
- Click Test trigger.
- Zapier pulls a sample record, not a real candidate. For Candidate Shortlisted it shows a record named "Candidate Shortlisted A" for "Sample Candidate" (candidate@example.com), with a score of 78, a summary, and representation consent "given".
- Use this sample to map fields in the next steps. Nothing about a real candidate is sent while you build or test.
The sample is a test event: its Test field is true. A filter that stops test events (every recipe has one) will report that the sample would not have continued. That is correct.
Step 5: Add your filter and action, then publish
- Add a Filter step (see Consent and erasure for what to filter on).
- Add the action in your target tool, and map one PlacementFlow field to each box.
- Click Publish. A draft Zap never runs. Until you publish, real shortlists do not reach it.
Publishing turns the Zap on. When a Zap is turned on, the app registers its own webhook in PlacementFlow; you can see it in Settings → Webhook Management, named after the trigger (for example "Zapier: Candidate Shortlisted"). When you turn the Zap off, that webhook is removed.
To stop a Zap, turn it off. Revoking the API key does not stop a Zap that is already on: its webhook keeps delivering until you turn the Zap off or delete the webhook in Settings → Webhook Management.
When real events arrive
- Candidate Shortlisted reaches Zapier about 45 seconds after a recruiter shortlists from the review screen. That delay is the undo window: if the recruiter clicks Undo, nothing is sent at all. A shortlist recorded from a phone screen has no undo, and is sent straight away.
- Other events are sent as soon as the thing they describe happens.
- Each event has a stable id, so if PlacementFlow retries a delivery, Zapier drops the duplicate instead of running the Zap twice.
How fields appear in Zapier
Zapier shows each PlacementFlow field with a readable label, for example Candidate First Name. If a label in your editor reads slightly differently, type a word from the table below into the field picker.
| What you want | Type in the picker | Payload key |
|---|---|---|
| First name | first name | candidate__first_name |
| Last name | last name | candidate__last_name |
| candidate email | candidate__email | |
| Phone | candidate phone | candidate__phone |
| LinkedIn profile | candidate__linkedin_url | |
| Link to the candidate in PlacementFlow | placementflow url | candidate__pf_url |
| Consent state | consent | candidate__representation_consent |
| Your CRM's id for the candidate | crm id | candidate__external_id |
| PlacementFlow's candidate id | candidate id | candidate_id |
| Job title | job title | job__title |
| Client name | client name | client__name |
| Is this a test? | test | test |
Some fields only appear when a real event carries them. For example, must-know flags are only on a shortlist that has them, so they are not in the sample. Build your Zap with the fields the sample shows.
The CRM-feed events
In Settings → Webhook Management, the CRM feed preset selects exactly the events below. They are the ones that record a durable fact a CRM keeps as a record or an activity. Scheduling negotiation (slot proposals, expiries), internal failures and raw message content are left out.
| Event | Label | What it means |
|---|---|---|
candidate.engaged | Candidate engaged | The first time PlacementFlow engaged a person (a cold reply, a screening, a booking, a submission). This is the "create person" moment, once per person. |
candidate.shortlisted | Candidate shortlisted | A screening response was shortlisted and the decision stands. A recruiter's shortlist is sent after its undo window closes, never after an undo. |
candidate.created | Candidate created | A recruiter created a candidate from the form or a dropped CV. For a CRM feed, prefer candidate.engaged, which also covers sourced people. |
candidate.updated | Candidate updated | A recruiter edited a candidate profile, by hand or from a dropped CV. |
candidate.erased | Candidate erased | A candidate was erased under GDPR. Carries ids and the external reference only. |
pipeline.status_changed | Pipeline status changed | A candidate moved stage on a job pipeline. |
screening.completed | Screening completed | A finished screening was processed, before any human decision. It carries any must-know flags, and a score only when the questions were tied to a job. Nothing here is a decision: only a recruiter declines. |
screening.disqualified | Screening declined by recruiter | A recruiter declined a screening response. Scoring never fires this. |
submission.sent | Submission sent | An identified submission's first email to one client left the agency's mailbox, under the consent authority it names. One event per client. |
placement.created | Placement created | A placement was recorded (offer acceptance, manual entry, or the reconciliation re-send). |
interview.scheduled | Interview scheduled | An interview has a confirmed time for the first time. |
interview.rescheduled | Interview rescheduled | A scheduled interview moved to a new time. |
interview.completed | Interview completed | An interview took place (bot transcript, time-based auto-completion, or a manual or API completion). |
interview.cancelled | Interview cancelled | An interview was cancelled. A candidate withdrawal fires interview.rejected instead. |
interview.no_show | Interview no-show | A no-show was confirmed by a recruiter, the API or the recording bot. |
interview.rejected | Interview rejected | A party definitively declined the interview. |
interview.decision_made | Client decision made | The client gave post-interview feedback on the portal: proceed to offer, another interview, on hold, or not a fit. |
bd_prospect.qualified | BD prospect qualified | A business-development conversation became qualified (taken over), once. Lead, company and contact ids, the company and the contact, never the email thread. |
meeting.scheduled | Meeting scheduled | A BD or discovery meeting has its first confirmed time. |
meeting.rescheduled | Meeting rescheduled | A meeting that already had a confirmed time got a new one. |
meeting.cancelled | Meeting cancelled | A meeting was cancelled by the host or the guest, or a booking request was declined. |
meeting.completed | Meeting completed | The host marked a meeting complete. |
The Settings page lists every other event too, grouped, if you need more than the CRM feed. The Zapier app offers the eight triggers listed above; for any other event, use a generic webhook step.
What every candidate event carries
Events about a candidate (candidate.engaged, candidate.shortlisted, candidate.created, candidate.updated, screening.completed, screening.disqualified, submission.sent, pipeline.status_changed, placement.created, and every interview.* event) carry the same reference block, so a CRM can always file the event against the right record:
candidate_id,agency_id,job_idandclient_id(the last two are null when the event has no job or client)candidate:id,first_name,last_name,email,phone,linkedin_url,location,headline, and:pf_url: a link to the candidate's record in PlacementFlow (sign-in required)external_sourceandexternal_id: the CRM record this person is linked to, once you have written it back (see below), otherwise nullrepresentation_consent: one ofgiven,not_yet,missingorwithdrawn, read from the consent recordrepresentation_consent_at: when that consent state was recorded (null whenmissing)
jobandclient:id,titleorname, and their ownexternal_sourceandexternal_id, or null
A generic webhook step receives the full envelope instead of the flat Zapier record: id, event, occurred_at, test, and the event's fields under data.
Payloads never carry raw screening answers or transcripts, reviewer notes, email bodies, CV files, or business-development email threads. A screening score and summary are advisory: PlacementFlow never rejects anyone on a score, and only a recruiter declines.
Consent and erasure: your duties
Consent is about representing a candidate to employers. representation_consent tells you whether the candidate has agreed to be put forward to clients. Writing a candidate into your own CRM is your agency's own processing, but PlacementFlow cannot see where a webhook leads. So every candidate event carries the consent state, and every recipe filters on it.
- Filter on consent before anything that reaches an employer. If a Zap sends a candidate to a client, a shared sheet, or a client-facing system, continue only when the consent field exactly matches
given. - Never forward a withdrawn candidate. Every Zap, even an internal log, should stop when the consent field is
withdrawn. candidate.engagedfires early, before a candidate has been asked for consent, sonot_yetandmissingare normal there. Treat them as "not cleared to represent yet".submission.sentonly exists because PlacementFlow's consent check passed at send time.consent_authoritysays whether that was the candidate's own consent or a recorded recruiter attestation.- Filter out test events too. Continue only when Test is false, so a sample never creates a real record.
A copy in a CRM or a spreadsheet is a new copy of personal data. You are responsible for it: its security, its retention, and answering access and erasure requests for it.
Erasure reaches your copy through candidate.erased. When a candidate is erased in PlacementFlow (on request or by the retention schedule), this event tells you so. It carries only candidate_id, agency_id, external_source, external_id, erased_at and reason (request or retention), and no other personal data. The copy in your CRM is yours to delete. Find it by external_id (or by candidate_id if you stored that) and delete it, or create a task for someone to do so. Every recipe includes this erasure Zap: keep it on for as long as the Zap that copies the data is on.
The external-id round trip
Once your CRM has a record for the candidate, write its id back to PlacementFlow:
- In Zapier: the Set Candidate External ID action. It asks for the Candidate ID, the CRM (Bullhorn, Atlas, Ezekia, HubSpot or Other) and the External ID.
- Through the API:
PUT /api/v1/candidates/{id}/external-refwith a body ofsourceandexternal_id.sourceis one ofbullhorn,atlas,ezekia,hubspotorother. The key needs thecandidates:writescope. - To remove it (the CRM record was deleted, or you linked the wrong one):
DELETE /api/v1/candidates/{id}/external-ref. Nothing to remove is still a success.
What this gives you:
- Every later event about that candidate carries
candidate.external_sourceandcandidate.external_id, so your Zap can update the right CRM record directly instead of searching by email. candidate.erasedcarries the same reference, so deletion targets the right record.
How it behaves:
- It is idempotent: writing the same reference again changes nothing.
- If another PlacementFlow candidate already holds that same reference, the step fails with a message naming that candidate, so you can see which record is the duplicate. (Through the API, this is a
409response.) - Writing the reference back sends no webhook, so a Zap that listens for candidate events and writes the reference back cannot trigger itself in a loop.
Private links are off by default
No webhook receives these unless you turn on Include private links for it (in Settings → Webhook Management, or includePrivateLinks through the API):
- self-service reschedule and cancel links for interviews
- booking and slot-selection links
- the text of email replies (
reply_textonemail.replied; the short preview is still sent)
These links work like keys to someone's interview. Turn the setting on only for a system that emails candidates or clients itself. A webhook the Zapier app or a Make trigger manages can never turn it on.
Revoking an API key stops its webhooks
When you revoke an API key, every webhook that key registered (a Zap, for example) is disabled in the same step, so a key that leaked or belonged to someone who left cannot keep a Zap receiving your data. Settings → Webhook Management shows these as disabled because the key was revoked; resume one only if it should keep running.
Test deliveries
A test delivery is marked twice: "test": true in the body, and an X-Webhook-Test: true header. It also shows in the webhook's delivery log with a Test chip, and never counts toward the delivered rate. The Send a test button (the test-tube icon) in Settings → Webhook Management can send the sample payload of any event, so you can map fields without waiting for real activity. Sample payloads contain made-up data.
Add a filter on test (only continue when it is false) to any Zap or scenario that writes to a live system, so a test never creates a real CRM record.
Troubleshooting
"Your PlacementFlow API key was rejected" (401) The key was revoked, deleted, or pasted with a missing character. Generate a new key with the Automation (Zapier/Make) preset, then reconnect the account in Zapier (in the Zap's trigger step, or under your Zapier app connections).
"Your PlacementFlow API key does not have permission for this step" (403) The key was made with a narrower set of permissions. Generate a new key with the Automation (Zapier/Make) preset and reconnect.
No sample found when you test the trigger The sample comes from PlacementFlow, not from your real data, so it does not depend on recent activity. Check that the step uses your PlacementFlow connection (it shows your agency's name), then click Test trigger again. If it still fails, reconnect with a fresh key.
Real events are not arriving
- Is the Zap published? A draft Zap never runs. Open it and check it is on.
- Is the key still active? Publishing a Zap registers its webhook with the key. If the key was revoked first, that registration fails and nothing arrives. Reconnect with a new key, then turn the Zap off and on again.
- Did you wait out the undo window? A shortlist reaches Zapier about 45 seconds after the click. If the recruiter clicked Undo, nothing is sent, by design.
- Is the Zap's webhook still there and active? Look for it in Settings → Webhook Management. If someone paused it, resume it. If someone deleted it, turn the Zap off and on again; it registers a new one.
- Is a filter stopping it? Open the Zap's history in Zapier. A run marked as filtered reached Zapier and was stopped by your filter, often the consent or test filter doing its job.
"Already linked to another PlacementFlow candidate" The CRM id you tried to write back already belongs to another PlacementFlow candidate. That usually means a duplicate in one of the two systems. Sort out the duplicate, then replay the Zap run.
Make
- In your scenario, add Webhooks → Custom webhook as the first module and create a new webhook. Copy its URL.
- In PlacementFlow, create a webhook in Settings → Webhook Management with that URL and the events you need (or the CRM feed preset). Leave Include private links off.
- Click Send a test on the PlacementFlow webhook so Make learns the payload shape, then build the rest of the scenario.
- Add a filter after the webhook:
testequals false, anddata.candidate.representation_consentis notwithdrawn(or equalsgiven, if the scenario reaches an employer).
n8n
- Add a Webhook node (method POST) and copy its production URL.
- Create a PlacementFlow webhook with that URL, in Settings → Webhook Management or through the API with
sourceset ton8n. - Verify the signature before you trust the payload. Two options:
- Crypto node: compute an HMAC-SHA256 (hex) over the text
<X-Webhook-Timestamp header>.<raw request body>, keyed with your webhook secret, and compare it with theX-Webhook-Signatureheader. The HMAC must run over the raw body exactly as received, so enable the Webhook node's raw body option. - Code node: use the
standardwebhookspackage with thewhsec_form of your secret to verify thewebhook-id,webhook-timestampandwebhook-signatureheaders (self-hosted n8n has to allow the package in its Code node settings).
- Crypto node: compute an HMAC-SHA256 (hex) over the text
- Add an IF node:
testis false, anddata.candidate.representation_consentis notwithdrawn(or equalsgiven, if the workflow reaches an employer).