# Using FieldSwap with Zapier

FieldSwap doesn't have an official Zapier app yet, but you can call it from any
Zap today using the built-in **Webhooks by Zapier** action. This guide wires a
single enrichment lookup into a Zap — no code required.

This covers the enrichment (action) direction only: something happens in another
app → FieldSwap resolves a field → the result is used downstream. A
FieldSwap-as-a-trigger integration isn't available yet.

---

## What you'll build

A Zap that takes an identity value from an earlier step — say the email address
on a new CRM lead — sends it to FieldSwap, and gets a resolved field back (a
phone number, an employer, a deliverability score, …) to use in later steps such
as updating the record or routing the lead.

FieldSwap is the **action** in the middle of your Zap. The trigger ("new lead in
HubSpot", "new row in Google Sheets", …) and the final write-back step are
whatever apps you already use.

---

## Before you start

You need two things:

- A FieldSwap workspace with available credits.
- An API key. Create one in the **API keys** tab of the dashboard — it looks
  like `fs_live_…` and is shown only once, so paste it somewhere safe before
  leaving the page.

> **Keep the key in Zapier, not in a spreadsheet.** Once you paste it into the
> action's header field, Zapier stores it for you. Treat it like a password —
> anyone with the key can spend your credits.

---

## Add the FieldSwap action

In the Zap editor, add an action step and pick
**Webhooks by Zapier → Custom Request**. Use *Custom Request* (not the simpler
"POST" event): FieldSwap expects a nested JSON body with an `input` object, which
the flat key/value fields of the POST event can't express cleanly.

Configure the request like this:

| Field | Value |
|---|---|
| Method | `POST` |
| URL | `https://api.fieldswap.founderscale.com/v1/lookup` |
| Data Pass-Through? | No (false) |
| Data | The JSON body below, with the trigger field mapped into `input.value`. |
| Headers | `Authorization`: `Bearer fs_live_<your_key>` and `Content-Type`: `application/json` |

In the **Data** field, paste the JSON below, then use Zapier's `+` insert button
to replace the email value with the field from your trigger step (shown here as
`{{lead_email}}`):

```json
{
  "input":  { "type": "email", "value": "{{lead_email}}" },
  "output": "phone"
}
```

Set `input.type` to whatever you're sending (`email`, `phone`, `linkedin`,
`full_name`, `ip`) and `output` to the field you want back. The full list is in
the [Field types](/docs#fields) reference.

> You can send the key as the `X-Api-Key` header instead of `Authorization` —
> the two are equivalent. Use whichever Zapier lets you enter more easily.

---

## Use the result

Click **Test action**. FieldSwap returns a JSON response that Zapier parses into
fields you can map into later steps:

```json
{
  "request_id": "8f1d2c20-…",
  "person_id":  "0a4e5b66-…",
  "output": {
    "type": "phone",
    "value": { "phone_e164": "+14155551234" },
    "fresh": true
  },
  "hit_source": "vendor",
  "credits_remaining": 9847,
  "status": "ok"
}
```

The resolved value lives under `output → value`. For a phone lookup it shows up
in Zapier as `Output Value Phone E164`; map that into your write-back step. Each
output type has its own shape — see [Field types](/docs#fields).

---

## Guard against empty results

FieldSwap returns `200 OK` even when it has no data, so always check the `status`
field rather than relying on the HTTP status. Add a **Filter by Zapier** step
after the action that only continues when:

```
Status   (Text)   (Exactly matches)   ok
```

A status of `not_found` means we identified the person but no vendor had the
requested field; `opt_out` means the person opted out of enrichment. In both
cases `output` is empty and there's nothing to write back.

---

## Credits & rate limits

Every lookup costs **1 credit**, whether or not a value comes back — you pay per
query, not per match. To avoid burning credits on rows that can't be enriched,
put a Filter *before* the FieldSwap action (e.g. only run when the email field
isn't empty).

Requests are rate-limited to **60 per minute per workspace**, shared across all
your API keys. If a Zap processes large batches, Zapier's automatic retries
handle the occasional `429`; for sustained higher volume, contact us to raise
the limit.

---

## Troubleshooting

| You see | What it means |
|---|---|
| `401` | API key missing, mistyped, or revoked. Re-check the `Authorization` header. |
| `400` | The input value couldn't be parsed (e.g. not a valid email or phone). Check the field you mapped. |
| `402` | Out of credits, or your daily provider spend cap was reached. Top up or raise the cap in Billing. |
| `429` | Rate limit hit. Zapier retries automatically; honor the `Retry-After` header if you script your own delays. |

Every response carries an `x-request-id` header — quote it when you email
[support@fieldswap.io](mailto:support@fieldswap.io).