Volunteer police-check screening without middleware infrastructure
A volunteer couldn't start until a police or working-with-children check cleared, and the screening provider ran that verification through a portal disconnected from the CRM. The organisation wouldn't add a server or middleware to bridge the two. We built that bridge inside HubSpot instead: workflows that create the check, store its identifiers on the contact, and poll for an outcome on a schedule.
Executive Summary
Context
An Australian not-for-profit meal-delivery and community-care organisation runs its service through a volunteer branch network, and every volunteer needs a cleared police or working-with-children check before a placement. Its contract with the delivery partner ruled out hosting a server, so the check had to live inside HubSpot instead.
What We Built
We built a two-workflow Operations Hub integration. One opens a police check when application status changes to Submitted. The other polls the status endpoint on a smart list until the check clears, is flagged, or is cancelled. A companion form skips address-history questions for an applicant who already holds a valid check.
Tech Stack
- HubSpot Operations Hub custom code actions, HubSpot Secrets manager, HubSpot smart lists and active lists, HubSpot Marketing Hub forms and workflows, National Crime Check API (consumer_v1.5).
Not a fit if your volunteers can't complete their own identity verification directly with a screening provider. Status only updates at the next scheduled poll, not the instant it clears. It also assumes a branch is ready to act once a volunteer clears; without that, a cleared applicant can sit unclaimed.
The Challenge
Every volunteer applicant needed a current police or working-with-children check before starting, and the organisation ran that verification through a portal that was separate from its CRM. Staff couldn't see where an application stood without logging in to the portal and matching records by name.
A hosted webhook listener would have closed that gap by catching the provider's status updates. But the delivery partner doesn't run client scripts, and the organisation didn't want a server of its own.
Our Approach
We considered a webhook listener to catch the provider's status callback, but dropped it. The delivery partner doesn't run client scripts, and the organisation wanted no server of its own.
Instead, a workflow called Initiate Police Check watches for volunteer_application_status changing to Submitted. It posts the applicant's details to the checks/create endpoint and stores the returned identifier and continuation URL on the contact. A second workflow, Poll NCC Status, re-enrols any contact whose check is still in progress two hours after the last poll. It calls the status endpoint and writes the outcome back onto the record.
That trades immediacy for simplicity, because a change reaches HubSpot only at the next poll. The registration form completes the picture: an applicant who already holds a valid check skips the address-history questions, and everyone else gets the provider's link.
Impact
Check status stays inside the record volunteers are already tracked in
The polling workflow writes the provider's outcome onto the contact record, so staff can see where a check stands without opening the provider's portal. That removes the second login and the manual name-matching the portal required.
Manual processing drops out of the police-check step
The create and poll workflows run the check automatically once a volunteer applies, so nobody opens a case in the provider's portal by hand or chases a status by phone. The conditional form also skips a question set for an applicant who already holds a valid check.
Volunteer approvals move without waiting on a staff member to notice
A volunteer's continuation link and confirmation email go out the moment their status changes, so the next step is already in their inbox instead of waiting for a staff member to notice. The same trigger creates the task their owner needs.
No middleware or server for the team to maintain
Every part of the check, the API call, the poll, and the key that authenticates it, operates inside HubSpot Operations Hub, so there's no listener or server to patch. The key stays in HubSpot's own Secrets manager, and a test-mode flag routes a request to the sandbox.
A custom code action runs when volunteer_application_status changes to Submitted, and posts the applicant's details to the checks/create endpoint. It stores the returned identifier as ncc_request_id and the URL as ncc_continue_url, then tasks the contact owner and emails the volunteer the link.
A contact joins an active list once its check is in progress and the last poll ran over two hours ago, a window the team can widen. The workflow calls the status endpoint and writes the outcome and date back onto the contact.
The registration form checks whether an applicant already holds a valid check from the last twelve months. When they do, the address-history questions are hidden. When they don't, those fields become required and they get the provider's link.
HubSpot's Secrets manager holds the API key as SECRET_NCC_API_KEY, so no workflow carries it directly. A test-mode boolean routes a request to the sandbox instead of production. Both reset like an ordinary contact field.
A volunteer submits the registration form, which writes an application status and a flag for any existing valid check onto their contact record in HubSpot. When the status changes to Submitted, the Initiate Police Check workflow reads the API key from the Secrets manager and creates the check through the National Crime Check API, then emails the volunteer a continuation link and sets a high-priority task for the contact owner. The Poll NCC Status workflow calls the API every two hours for any check still in progress and writes the outcome back to the contact. A clear result notifies the branch, and the dashed webhook listener shows the option we rejected.
FAQ
There's no callback, so a smart list re-enrols any contact whose check is in progress two hours after the last poll. Each run calls the status endpoint and writes the outcome back onto the record, which means that window sets how fresh the status is.
The form checks whether the applicant holds a valid check from the last twelve months. If they do, it skips the address-history questions and sends a clearance email instead of the provider's link.
