The Vouchfield API

Getting started

The API lets your own systems, Zapier or Make start website audits for your workspace and read the results. Webhooks send your system a signed message when an audit finishes, so you do not have to keep asking.

1. The workspace owner opens Settings → API keys and makes a key. It is shown once, so copy it straight away.
2. Check the key works by asking who you are:

curl https://vouchfield.com/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

Every address in this reference starts with https://vouchfield.com. Requests and answers are JSON. Times are UTC.

Your API key

Send the key in the Authorization header of every request, after the word Bearer and a space:

Authorization: Bearer YOUR_API_KEY

• Main key. Can do everything below, including making and switching off extra keys, setting the webhook address and connecting Slack. Keep it for yourself.
• Extra keys. Up to 25 switched on at once, each with its own name. They can start and read audits through the API, and use your workspace credits. They don't open the workspace pages: a teammate signs in with their own email instead. Give each tool its own key, so you can switch one off or replace it without touching the others.
• Keys are made, replaced and switched off by the workspace owner in Settings → API keys. We keep only a fingerprint of each key, so a lost key is replaced, never recovered.
• API access and webhooks are part of the Agency plan. GET /v1/me and GET /v1/plan work on every plan, so a key can always see why it was refused.
• Never put a key in a web page, an email or a shared document.

Speed limit

Each key can make 120 requests a minute (counted over the last 60 seconds). The main key and each extra key have their own allowance.

• Beyond it the answer is 429 with error.code rate_limited and a Retry-After header: the number of whole seconds to wait.
• Every answer to a request with a key has X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until there is room again).
• Requests with a key we do not recognise are limited to 30 a minute from each network address.
• Credits are separate: each audit uses one credit from your plan, and your plan has a daily limit. When credits run out the answer is 429 with error.code limit_reached, and nothing is charged for that request.
• Request bodies can be up to 16 KB of JSON.

Endpoints

Replace YOUR_API_KEY, AUDIT_ID and the other capitals with your own values. Where an example says YOUR_MAIN_API_KEY, only the main key works.

curl https://vouchfield.com/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

curl https://vouchfield.com/v1/plan \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST https://vouchfield.com/v1/scan \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-row-1042" \
  -d '{"url": "example.com", "name": "Example Bakery", "town": "Newark", "st": "NJ"}'

curl https://vouchfield.com/v1/scan/AUDIT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://vouchfield.com/v1/scans?status=done&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

# the next page: send next_cursor back as cursor, with the same filters
curl "https://vouchfield.com/v1/scans?status=done&limit=25&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl https://vouchfield.com/v1/seats \
  -H "Authorization: Bearer YOUR_MAIN_API_KEY"

curl -X POST https://vouchfield.com/v1/seats \
  -H "Authorization: Bearer YOUR_MAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Zapier"}'

curl -X DELETE https://vouchfield.com/v1/seats/KEY_ID \
  -H "Authorization: Bearer YOUR_MAIN_API_KEY"

curl -X POST https://vouchfield.com/v1/integrations/slack \
  -H "Authorization: Bearer YOUR_MAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "YOUR_SLACK_INCOMING_WEBHOOK_ADDRESS"}'

curl https://vouchfield.com/v1/openapi.json

Pages of results

Lists (GET /v1/scans and GET /v1/seats) come a page at a time. Each answer has has_more and next_cursor. To get the next page, send next_cursor back as cursor, with the same filters. On the last page next_cursor is null.

• A page can hold fewer items than limit, even none, while next_cursor is set. Keep following it.
• GET /v1/scans lists audits by when they last changed, newest first. An audit that changes while you page may move to the top, so use its id to skip repeats.

Safe retries

When you start an audit with POST /v1/scan, add an Idempotency-Key header with a value that is unique to that job, for example the id of the row or record it came from (up to 100 characters).

• If your request times out and you send it again with the same key, you get the same audit back (202, with the header Idempotent-Replayed: true) and no second credit is used, even at your daily limit.
• Sending the same key with a different url is refused with 409. Changed settings are not applied to the first audit.

Errors

Every error is JSON of one shape:

{"detail": "A sentence you can show a person.",
 "error": {"status": 404, "code": "not_found", "message": "A sentence you can show a person."}}

error.code is a fixed word your program can check. detail is the same sentence, except for 422, where it lists the fields that were missing or not valid.

Webhooks

When an audit for your workspace finishes, we send a POST with a JSON body to your webhook address. It does not matter how the audit was started: in the workspace, through your website widget or through the API.

1. The workspace owner opens Settings → Webhooks, pastes the address and saves. The address must be a public https:// address.
2. Tick the events you want, then click Send a test message.
3. With your main key you can also set the address with webhook_url when you start an audit. If messages were switched off after failed deliveries, this does not turn them back on: do that in Settings → Webhooks.

Events

A test message always has this body:

{"event": "webhook.test", "test": true, "message": "This is a test message from Vouchfield. It is not an audit."}

Headers

Answering and retries

• Answer with a 2xx status within 10 seconds, as soon as you have stored the message. Do the slow work afterwards.
• Anything else counts as a failure. We try again after about 1 minute, 5 minutes, 25 minutes and 2 hours (5 tries in all), then stop. Every retry keeps the same X-Audit-Id, so you can skip a message you already have.
• If 3 messages in a row fail every try, we switch messages off and email the workspace owner. Fix the address, then turn them back on in Settings → Webhooks.
• Redirects are not followed. Settings → Webhooks shows every try with the status your address answered, and can send a finished message again.

Checking a webhook message

Each message is signed with your workspace's signing secret, so you can check it came from us. The owner can reveal or replace the secret in Settings → Webhooks. It is not your API key, and a replaced secret stops working at once.

1. Read the raw body exactly as it arrived, as bytes, before any JSON parsing.
2. Refuse the message if X-Audit-Timestamp is more than 300 seconds (5 minutes) old, or more than 300 seconds in the future.
3. Join the timestamp, a full stop and the raw body: timestamp + "." + raw_body.
4. Make an HMAC-SHA256 of that with your signing secret and write it as lowercase hex. Put v1= in front.
5. Compare it with X-Audit-Signature using a constant-time comparison.
6. Skip a message whose X-Audit-Id you have already stored.

A retry is signed again with a fresh timestamp, so it is never refused by the 5-minute window.

In Python

import hashlib, hmac, time

def is_from_vouchfield(secret, raw_body, headers):
    ts = headers.get("X-Audit-Timestamp", "")
    sig = headers.get("X-Audit-Signature", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    mac = hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256)
    return hmac.compare_digest("v1=" + mac.hexdigest(), sig)

In Node

const crypto = require('crypto')

function isFromVouchfield(secret, rawBody, ts, header) {
  const mac = 'v1=' + crypto.createHmac('sha256', secret).update(ts + '.').update(rawBody).digest('hex')
  return Math.abs(Date.now() / 1000 - Number(ts)) <= 300 && header.length === mac.length &&
         crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(header))
}

Zapier's and Make's catch hooks cannot check a signature. There, treat the message as a tip-off and fetch the audit with GET /v1/scan/{id} and your key before acting on it. The Zapier and Make guide shows each step.

Machine-readable description

The same endpoints as an OpenAPI 3 file, for Postman and other API tools: /v1/openapi.json. No key needed.

Questions? Ask us.