Documentation
Browse documentation

Integrations

Zapier

Send new leads and location changes to any app, and create locations from any app, with Zapier's built-in Webhooks step.

What a Zap can do with a locator

Two directions, and both work today with Zapier's built-in steps.

  • Out of Handled. A new enquiry from the locator becomes a row in a sheet, a card in a CRM, a message in Slack. A location added or changed in Handled is mirrored somewhere else. These start from a webhook.
  • Into Handled. A record created or changed in another app, a CRM, Airtable, a form tool, becomes a location in the locator. These end in a call to the Location API.

You need a Pro or Business account with an API key that allows writes.

The Handled app for Zapier

The quickest route is the Handled Locator app for Zapier, which has named triggers and actions instead of URLs and JSON. It is available by invitation while it goes through Zapier's public listing:

  1. Open the invite link: zapier.com/developer/public-invite/246556/513002/fc875a79720ffeb678d035b8d875ce3f and accept. Handled Locator then appears when you search for an app in a Zap.
  2. When Zapier asks you to connect, paste an API key from Settings → API & developer tools → REST API with Allow writes ticked; triggers subscribe a webhook, which is a write.

What it offers:

  • Triggers: New Lead, New Location, Updated Location, Deleted Location. Each one registers a webhook for exactly its event when the Zap is turned on and removes it when the Zap is turned off, so nothing is left subscribed to a retired URL.
  • Actions: Create Location, Update Location, Delete Location, and Find Location, which pairs with Create as Find or Create Location so the same store in your other app never becomes two pins.

The sections below do the same jobs with Zapier's built-in Webhooks step, for a Zapier plan without it or for a tool other than Zapier.

A Zap that starts from a new lead, without the app

  1. In Zapier, create a Zap and choose Webhooks by Zapier as the trigger, event Catch Hook. Copy the hook URL it gives you.
  2. In Handled, open Settings → API & developer tools → Webhooks, paste the URL, tick only lead.created, and press Add endpoint.
  3. Back in Zapier, press Test trigger. The ping Handled sends on creation arrives at once; send a real enquiry from your locator to get a lead.created sample instead, which is the one to map fields from.
  4. Add the action: a row in Google Sheets, a contact in HubSpot, a message in Slack. Map data__lead__name, data__lead__email, data__lead__message, data__lead__searchAddress and data__lead__locationId.
  5. Add a Filter step between trigger and action: continue only if event exactly matches lead.created. This keeps the setup ping and any other event you add to the endpoint later out of the action.

The same shape gives you a Zap for location.created, location.updated or location.deleted: tick that event on the endpoint and map from data__location__*. The full payload is on the webhooks page.

A Zap that creates or updates a location, without the app

  1. Choose the trigger in your source app: a new row in Airtable, a new company in HubSpot, a form submission.
  2. Add Webhooks by Zapier with the event Custom Request.
  3. Set the method to POST, the URL to https://app.handledlocal.com/api/v1/locations, and add a header Authorization with the value Bearer followed by a space and your key. Add Content-Type application/json.
  4. Set Data to a JSON body that maps your fields:
Body
{
"name": "{{Store name}}",
"address": "{{Street}}, {{City}} {{Postcode}}",
"phone": "{{Phone}}",
"website": "{{Website}}",
"visibility": "hidden"
}

An address without coordinates is geocoded on save. Leave visibility as hidden while testing and switch it to visible once the Zap has produced one correct location.

To update rather than create, the Zap needs the Handled id of the location. Store it back in the source app when the create step runs (the response includes data.id), then a later Zap sends PATCH to https://app.handledlocal.com/api/v1/locations/<id> with only the fields that changed. Absent fields are left as they are.

To delete, send DELETE to the same URL.

Keeping one location per record

With the Handled app, use Find or Create Location with the store's name. With Custom Request there is no find-or-create, so the reliable pattern is to keep Handled's id on the source record. A column called Handled ID in the sheet or the CRM, written by the create Zap and read by the update Zap, means the same store never becomes two pins.

Where that is not possible, a GET to https://app.handledlocal.com/api/v1/locations?search=<name> returns matches by name or address, and a Paths step can branch on whether the result is empty.

When a step fails

Handled answers every error with a JSON body naming the problem, for example validation_failed with the field, or location_limit_reached with the plan's cap. Zapier shows that body on the failed run. The most common one is a key without write access: create a new key with Allow writes ticked.

If you would rather not use Zapier

Everything above is plain HTTP. Make, n8n, Pipedream and a scheduled script all do the same with the same webhooks and Location API. For lists that live in Google Sheets, the built-in Google Sheets sync needs no automation tool at all.