# Zapier

Source: https://locator.handledlocal.com/docs/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](https://locator.handledlocal.com/docs/webhooks).
- **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](https://locator.handledlocal.com/docs/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](https://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](https://locator.handledlocal.com/docs/webhooks#payload).

## 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](https://locator.handledlocal.com/docs/webhooks) and [Location API](https://locator.handledlocal.com/docs/location-api). For lists that live in Google Sheets, the built-in [Google Sheets sync](https://locator.handledlocal.com/docs/google-sheets-sync) needs no automation tool at all.
