Start free trial

Zapier & API keys: the Zapier and How it works tabs

Help Center

New to VisionScaper?
Start here

Help Center › Admin screens, field by field › Zapier & API keys: the Zapier and How it works tabs

Zapier & API keys: the Zapier and How it works tabs

The read-only addresses on the Zapier and How it works tabs, what each is for, and how to use them with a key.

On this page

Where to find it: Contractor Hub → Settings & Integrations → Zapier & API keys, tabs Zapier and How it works. Owner screen. The four tabs are Access keys, Alerts to other tools, Zapier, How it works. Use the arrow keys to move between them.

What it controls: nothing is typed or saved on these two tabs. They hold read-only addresses (each with a Copy button) and instructions. Every address is specific to your website.

Before you start

  • Make a key first, with “Set up alerts (needed by Zapier)” ticked. See zapier-and-api-keys-access-keys-and-alerts.
  • VisionScaper has no published Zapier app. The tab says so: “VisionScaper does not have a published Zapier app. You connect it with Zapier’s ‘Webhooks by Zapier’ (or your own private Zapier app) using an access key.” You set the connection up yourself in Zapier. For Zapier’s own screens, follow Zapier’s current instructions, and see get-zapier-setup.

Tab: Zapier

Field (exact label) What it does for VisionScaper What to do with it Default / notes
Subscribe address (read-only + Copy) Where Zapier sends a POST to start receiving an event. VisionScaper then creates an alert for it (shown with a “From Zapier” tag). Paste into Zapier’s Custom Request step. Specific to your site.
Unsubscribe address (read-only + Copy) Where Zapier sends a POST when the Zap is turned off. Paste into Zapier.
Sample address (add the event name) (read-only + Copy) Lets you test a trigger before real data exists. Add the event name at the end, for example lead.created. It lists your newest real records, or one clearly marked example if you have none yet. Paste and add the event name. The box already ends in lead.created.

The tab’s numbered steps:

  1. On the Access keys tab, make a key named Zapier. Tick “Set up alerts (needed by Zapier)” and what you want Zapier to look at or add.
  2. In Zapier, add a step using “Webhooks by Zapier” (or your own private Zapier app). Choose “Custom Request”.
  3. To react to something in VisionScaper, have Zapier send a POST to the Subscribe address with your key in a header named Authorization (the word Bearer, a space, then the key). Send the event name and the address Zapier gave you. Do the same with the Unsubscribe address when the Zap is turned off.
  4. To test a trigger before it has real data, ask the Sample address for the event.
  5. To add a lead or customer from Zapier, send a POST to the leads or customers address on the How it works tab.

The tab ends with “Events you can use:” and the list: lead.created, customer.created, quote.sent, quote.accepted, job.completed, invoice.paid.

Tab: How it works

Field (exact label) What it does for VisionScaper What to do with it Default / notes
Starting address (read-only + Copy) The base address for the whole programming interface. Add a name on the end, for example customers. Use as the start of every request. Specific to your site.

Rules on the tab (all JSON):

Topic What it says
Sending your key Send it in a header: Authorization: Bearer <your key>.
Example curl <starting address>customers -H "Authorization: Bearer YOUR_KEY"
Lists customers, quotes, invoices, jobs, payments. Add ?limit=25 and for the next page ?cursor= with the next_cursor you were given. The server accepts a limit from 1 to 100; the default is 25.
Adding things POST to customers or leads. A person with the same email or phone is never added twice; you are told who already exists.
Retrying safely Add an Idempotency-Key header to anything that adds or changes data.
Limits and plan Over the hourly limit you get a 429 answer with a Retry-After header. If your plan does not include this you get 402.
Signed alerts Each alert carries an X-VisionScaper-Signature header: t=<time>,v1=<code>. The code is HMAC-SHA256 of <time>.<body> using your signing secret. A failed alert is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then given up. After 10 failures in a row the alert is switched off and you are emailed.

Steps

  1. Make a key (Access keys tab). Copy it.
  2. Open the Zapier tab. Click Copy next to the Subscribe address.
  3. In Zapier, add a Custom Request step with that address and your key in the Authorization header.
  4. Use the Sample address to test.
  5. Check the Alerts to other tools tab: the Zapier alert appears with a “From Zapier” tag.

Tips

  • Keep the signing secret private. Only use it to check signatures.
  • The same key and the same hourly limit apply to Zapier and to your own programs.

If something goes wrong

  • 401 or 403 from VisionScaper: the key is wrong, off, or missing a needed box. Make a new one.
  • 402: your plan does not include this.
  • 429: wait for the number of seconds in Retry-After.
  • No Zapier alert appears: the key lacks “Set up alerts (needed by Zapier)”, or the POST had no valid event.

Related articles

Still need help?

Tell us what you were trying to do and a person will reply.

Contact support