Integration guideZapier
Capture leads from Facebook Lead Ads, Typeform, Webflow and 6000+ other apps via Zapier — step-by-step with screenshots.
Setup
Create a Zap with Facebook Lead Ads as source and Webhooks by Zapier as action.
Create a new Zap
In Zapier, click Create Zap. Name your Zap (e.g. Facebook Leads → Capturia).
Configure the Facebook Lead Ads trigger
As Trigger app, choose Facebook Lead Ads. Connect your Facebook Business account, select the Page and the Lead Form you want to route to Capturia. Click Test trigger — Zapier pulls a test lead from the form.
Add the Webhooks by Zapier action
As Action app, choose Webhooks by Zapier. As Event, select POST (not Custom Request, not GET).
Configure URL and authentication
URL: https://app.capturia.io/api/v1/leads/capture
Payload Type: JSON (not Form, not XML)
Headers: add Authorization with the value Bearer cap_live_xxxxxxxx (your full Capturia API key).
Map the fields
In the Data section, add the Capturia fields (see the mapping table below). Drag the matching Facebook Lead fields from the right-hand panel.
Important: for utm (nested object) and pipeline, use the format utm.source, utm.medium, pipeline.id, etc. Zapier flattens them by default — you must enable Unflatten = Yes in advanced options.
Capture SMS consent
Recommended pattern: add a custom SMS consent question to your Facebook Lead Form (Custom Question type "Yes/No" or checkbox). Map this field to sms_consent.
Alternative pattern: if the custom question isn't possible, hardcode sms_consent: true but keep proof of consent (checkbox on the landing page, archived copy). See the LCAP section below.
Test and publish
Click Test action to send the test lead to Capturia. A 200 OK response with status: created or status: idempotent_replay confirms the connection. In My Prospects on Capturia, the test lead appears immediately. If everything is OK, click Publish Zap to activate the connection in production.
Field mapping
Recommended mapping for Facebook Lead Ads → Capturia. Adapt source field names to your form — phone_number in some forms becomes phone in others.
| Capturia field | Required | Source field | Notes |
|---|---|---|---|
| phone | Yes | phone_number | E.164 (+15145551234), NANP 10 or 11 digits, or formatted (514) 555-1234 / 514-555-1234. 10-digit numbers auto-prefixed with +1. |
| sms_consent | Yes | consent_yes_no (custom question) | Boolean true OR string 'true' / 'yes' / 'oui' / 'vrai' / '1' / 'on' / 'checked' (case-insensitive). Accepted at the body root or inside the `customData` object (GoHighLevel webhooks). |
| first_name | No | first_name | Lead's first name |
| last_name | No | last_name | Last name |
| No | RFC 5322 valid email | ||
| source_label | No | (littéral) fb_lead_ads | Free-form tag (e.g. 'webflow_form', 'fb_lead_ads') |
| utm.source | No | (littéral) facebook | Nested utm object (not flat) |
| utm.medium | No | (littéral) cpc | Nested utm object |
| utm.campaign | No | campaign_name | Nested utm object |
| tags | No | [] | Array of strings |
| pipeline.id | No | (optionnel) | Target pipeline UUID |
| pipeline.stage_id | No | (optionnel) | Target stage UUID |
SMS Consent — CASL / Quebec Law 25
The sms_consent field is required. Canada's Anti-Spam Law (CASL) and Quebec's Law 25 require explicit consent before any commercial SMS. Capturia stores a timestamped record of this attestation for your legal protection.
Recommended pattern — consent captured at source
Add a custom consent question directly in the source form (FB Lead Form custom question, Typeform field, GHL form checkbox). Map this field to sms_consent. Consent is explicit, dated, and tied to the lead who gave it.
Alternative pattern — checkbox on the landing page
If the source form doesn't allow custom questions, add a consent checkbox on the landing page before the ad. Keep a copy of the page (Wayback Machine, dated screenshot) as evidence.
Legal grey area
Hardcoding sms_consent: true without real lead attestation = legal risk. In case of complaint, Capturia may be required to provide proof of consent. Without proof, liability falls on the SMB owner.
Step-by-step test
In Zapier, click Test trigger to pull a test lead from Facebook (use Meta's "Lead Ads Testing Tool"). Then Test action to send the lead to Capturia. A 200 OK response with status: created or status: idempotent_replay confirms it works. Then check My Prospects in Capturia to see the lead.
Error catalog
| Code | Error | Cause | Fix |
|---|---|---|---|
| 401 | missing_api_key | Authorization header absent or malformed | Add the header Authorization: Bearer cap_live_... |
| 401 | invalid_api_key | Key revoked, expired, or typo | Check the key in the dashboard, generate a new one if needed |
| 403 | terms_acceptance_required | ToS not accepted (or version bump forced re-consent) | The SMB owner must re-accept ToS in the dashboard |
| 403 | insufficient_scope | Key lacks the leads:capture scope | Create a new key with the 'Lead capture' preset |
| 422 | invalid_phone | Phone format not recognized | Use E.164 (+15145551234) or NANP 10 digits (5145551234) |
| 422 | missing_consent | sms_consent absent, false, or unrecognized value — the field is looked up at the body root AND inside the customData object (GHL) | Map the consent field to sms_consent (true / yes / oui). From GHL: fixed value true behind a condition on the consent checkbox |
| 422 | invalid_payload | Other field malformed (email, utm object vs flat, etc.) | Check the body format — see the leads:capture API doc |
| 429 | rate_limited_key | Per-key quota exceeded (often 100 req/min) | Throttle at source, or request a tier upgrade from support |
| 429 | rate_limited_ip | Per-IP quota exceeded | Reduce the rate or contact support |
| 400 | invalid_payload | Body is not valid JSON (Form or form-urlencoded sent instead) | Configure Payload Type = JSON / Content-Type = application/json |
FAQ — common pitfalls
| Symptom | Cause |
|---|---|
| Platform test green (200 OK) but lead doesn't show up in pipeline | Phone matches an existing contact — response status: idempotent_replay. The lead exists but isn't duplicated. Test sandboxes often reuse the same number. |
| 400 "Body is not valid JSON" | Payload Type set to Form instead of JSON, or body sent as x-www-form-urlencoded instead of application/json. |
| 200 OK response but no SMS sent to lead | sms_consent: true but AI agent not configured, or SMS AI agent disabled, or no Twilio number provisioned for the client. |
| Lead created without UTM tracking | utm field sent as flat (utm_source) instead of nested object (utm.source). Server expects an object. |
| 403 terms_acceptance_required after an update that used to work | ToS version bump on Capturia side forces the SMB owner to re-accept in the dashboard before the key works again. |
| UTM lost despite mapping | In Zapier, the Unflatten = Yes option is required for utm.source to be sent as a nested object. Otherwise Zapier flattens to utm_source which Capturia rejects. |