Lead Connectors

Current V2 status (2026-09-02): Lead Connectors are live in V2 for API, website form, email-forward, Google Lead Ads, and Meta Lead Ads intake.

Lead Connectors let your workspace accept leads from outside Clean Estimate Pro without a separate import workflow for every source.

Use Settings > Integrations > Lead Connectors to:

• create connector profiles for trusted API imports, website forms, and forwarded emails
• map outside field names onto CE Pro lead fields
• apply defaults like a source label, an assigned rep, and a notes prefix
• test a sample payload before going live
• review incomplete or low-confidence imports before a lead is created
• inspect recent import attempts, replays, and failures

Only members with the manage integrations permission and access to every location can create or change connectors.

What A Connector Does

Every connector turns an outside payload into the same lead the office would create by hand:

• the client is created with the contact details in the payload
• the service address becomes the client's property
• the lead lands on the pipeline's first stage at the connector's location (the workspace default location unless the connector says otherwise)
• the connector's source label, assigned rep, and notes prefix are applied
• the lead.created event fires for automations and outgoing webhooks, exactly as for any other lead

A payload that is missing a name, a contact method, or a service address is not turned into a lead. It waits in the Review Queue with the reason, so nothing is silently dropped and nothing incomplete reaches the pipeline.

Every payload a connector receives is recorded as an import run, whether it imported, replayed, waited for review, or failed.

Connector Types

V2 supports six connector types today. Each provider uses one transport, which the form fills in for you.

API Connector (transport: API key)

Use this for Zapier, Make, middleware, custom CRMs, and any trusted server-to-server integration.

API connectors use a live CE Pro API key plus the connector key shown on the connector card. See API Connector Setup.

Website Form Connector (transport: public form)

Use this when a public website form should post straight into CE Pro without exposing an API key in browser code. The connector card shows the public endpoint for the form.

Email Forward Connector (transport: email inbound)

Use this when a marketing inbox, form-notification inbox, or forwarded lead emails should become leads automatically. The parser extracts the lead fields and scores its confidence; uncertain parses wait in the Review Queue.

Google Ads Connector (transport: native webhook)

Created for you by the guided Google Lead Ads page. The connector carries the Google key Google Ads posts with; the advanced settings (field aliases, assigned rep, notes prefix) stay here. Google's webhook test deliveries are logged as Ignored without a lead.

Meta Connector (transport: native webhook)

Created for you by the guided Meta Lead Ads page, which connects the page through Meta's login and keeps the page token where only the service can read it. The connector cannot be created by hand here (the form does not offer the provider), but its advanced settings (field aliases, assigned rep, notes prefix) are edited here like any other.

Workiz Connector (transport: native webhook)

Created for you when the Workiz page connects the workspace's Workiz account. Every Workiz lead (from the webhook, a pull, or a migration import) arrives through it, keyed by the Workiz lead id so a repeat replays. It cannot be created by hand; its aliases, assigned rep, and notes prefix are edited here like any other.

CE Pro allows one active connector per provider and transport in a workspace. Deactivate the current one before activating another of the same type.

Creating A Connector

1. Open Settings > Integrations > Lead Connectors and select Add connector.
2. Enter a Display Name that tells your team what the source is.
3. Choose the Provider. The Transport is set by the provider.
4. Leave the Status on Draft while you configure it.
5. Add an optional Source Label. It must match the name of one of your active lead sources to be applied; otherwise the lead is created without a source.
6. Choose an Assigned Rep if this connector should default to one person. Without one, the lead goes to the member who created the connector. The rep must be an active office member who can work the connector's location (crew members cannot own leads and do not appear in the picker); a rep who later moves to another location or is deactivated no longer receives the connector's leads, which fall back to the connector's creator.
7. Add a Notes prefix if every imported lead should carry source context in its notes, for example Zapier.
8. For email connectors, set an Email review threshold such as 0.65 or 0.75. Parses below it pause for a person.
9. Fill in Field aliases if the source uses its own field names (see below).
10. Select Create connector.

Leave connectors in Draft until the mapping and a test import look right, then select Activate on the card.

Field Mapping

Outside systems rarely use the same field names CE Pro expects. Field aliases tell CE Pro which incoming fields map to which lead fields. Enter the incoming names comma separated under the lead field they belong to.

Common names are recognized without an alias: name, full_name, email, phone, phone_number, address, street, city, state, zip, zipcode, postal_code, service, message, comments, notes, and id. Matching ignores case, spaces, and punctuation, so Full Name and full_name both work.

The lead fields are:

API Connector Setup

API connectors are the best fit for trusted server-to-server lead intake.

Recommended Request Pattern

• Use a live CE Pro API key with leads:write and access to every location (a key limited to specific locations answers 422, because the connector decides where the lead lands)
• POST to /api/v1/leads
• Include the connector key in connector_key
• Send Idempotency-Key on every request
• Send external_id whenever the upstream system provides a stable id

Example payload:

{
  "connector_key": "lsc_0123456789abcdef0123456789abcdef",
  "customer_name": "Pat Example",
  "customer_email": "pat@example.com",
  "customer_phone": "(717) 555-1212",
  "service_address": "123 Main St",
  "city": "Lancaster",
  "state": "PA",
  "zip": "17601",
  "service_interest": "House Wash",
  "notes": "Requested from landing page",
  "external_id": "lead-12345"
}

A complete payload answers 201 with the lead. An incomplete payload answers 202 with the import id and waits in the Review Queue; a manager completes it there. A connector key that belongs to another workspace, is inactive, or is not an API connector answers 422 on connector_key. The connector's aliases, defaults, and assigned rep apply, and the same Idempotency-Key replays the stored response.

Use the upstream lead id as both external_id and the Idempotency-Key when possible. That gives CE Pro the cleanest replay protection.

Website Form Connector Setup

Website form connectors are meant for browser-based form posts.

The connector card shows the public endpoint:

https://app.cleanestimate.pro/api/public/lead-connectors/<connector key>

Post the form there as JSON, as a regular form submission (application/x-www-form-urlencoded), or as multipart/form-data. The endpoint answers with open CORS headers, so a form on your own site can post to it directly from the browser. An optional Idempotency-Key header makes a repeated post replay instead of importing twice.

The endpoint answers 202 when the payload was accepted, whether it imported straight away or is waiting in the Review Queue. Unknown, inactive, and non-website connector keys all answer 404, so a key cannot be probed.

Best practices:

• keep the connector in Draft until you test the endpoint
• submit a sample through Run Test Import first
• map your website field names before embedding the form live
• include an external id if your frontend or middleware can provide one
• expect throttling: the endpoint allows 10 posts a minute per key and address and 120 a minute per key

Email Forward Connector Setup

Email-forward connectors let CE Pro parse lead information from inbound emails.

Use them for:

• marketing platform notifications
• inbox-forwarded form fills
• referral emails
• vendor or partner lead emails

Each email connector gets its own forwarding address, assigned by CE Pro when the connector is created (it cannot be chosen or changed). The card shows the full address once inbound email routing is configured for your environment; until then it shows the alias that will be used.

The parser reads labelled lines the way notification emails are written:

Name: Kathy Kline
Email: customer@example.com
Phone: (717) 555-1212
Address: 123 Main St
City: Lancaster
State: PA
Zip: 17601
Message: Two-story house, vinyl siding.

Labels may also be separated with a dash (Full name - Kathy Kline), may contain hyphens (E-mail: ...), and may be as long as one of your aliases; a message may run over several lines. Everything after a signature line (a line holding only --) is ignored, while a decorative rule of dashes above the fields does not stop the parser. A label the parser does not know is kept for your connector aliases, and once an alias claims it the parse is rescored, so a complete email is not held for review over an unfamiliar label.

An email with no recognizable labels keeps the sender as the contact when the sender looks like a person, keeps the whole message as notes, and always waits in the Review Queue.

Email Parser Quick Start

1. Open Settings > Integrations > Lead Connectors and create a connector with Provider = Email forward.
2. Set an Email review threshold such as 0.65 if uncertain parses should pause for review.
3. Activate the connector and copy the Forwarding address from its card.
4. Create a forwarding rule in your mailbox provider that sends lead emails to that address.
5. Watch Recent Imports for successful parses and Review Queue for emails that need a person.

Each email is one import run; a redelivered email is replayed, not imported twice.

Review Queue

The Review Queue tab shows imports waiting for a human decision: incomplete payloads from any connector and email parses below the review threshold.

For each pending item you can see the provider and connector, the parse confidence for emails, the sender and subject, the reason it is waiting, the fields the parser recognized, and the body preview.

Choose:

• Approve Import to correct any lead field (contact, address, customer type, service interest, notes, external id, appointment details, and property size) and create the lead through the normal intake
• Reject to discard the candidate and keep it out of the pipeline

Review actions are single-use. Once an item has been approved or rejected, it leaves the queue and stays in Recent Imports as history.

Recent Imports

The Recent Imports tab is your first stop when a connector is not behaving the way you expect.

It lists the last 50 payloads across every connector with Status, Provider, External ID, Lead, and Received.

Status meanings:

• Imported - a lead was created; Open lead takes you to it
• Replayed - the payload repeated an idempotency key or external id, so the earlier import was reused
• Review required - waiting on human approval
• Failed - the intake hit an unexpected error; the message is shown next to the status
• Ignored - the item was rejected during review, or it was a provider's own test delivery (Google's webhook test), which is logged without a lead

Testing Before Go-Live

Each API, website form, and email connector card includes Run Test Import. Google Lead Ads connectors do not offer it, because their door parses Google's webhook envelope rather than a flat payload; test those with Google's own webhook test from the lead form settings. Paste a sample payload the way the source would send it and CE Pro shows how the fields map, which keys it would ignore, and whether the payload would import or wait for review. Nothing is saved.

For API connectors, also run one real end-to-end test from the upstream system with a safe test payload and a stable idempotency key.

Rotating A Connector Key

Rotate key on a connector card issues a new connector key immediately. Anything still posting with the old key stops working, so update the upstream system right after rotating. Email connectors keep their forwarding address.

Troubleshooting

Import shows Review required

The payload was missing a customer name, a contact method (email or phone), or a service address, or an email parse scored below the review threshold. Open the Review Queue, complete the fields, and approve it. Then review the field aliases so the next payload maps cleanly.

Import shows Replayed

CE Pro matched the incoming payload to an earlier one by idempotency key or external id. That is normal for retries.

The website form answers 404

The connector key in the endpoint is wrong, the connector is not active, or it is not a website form connector.

Email imports never appear

Check that the connector is active, that inbound email routing is configured (the card shows a full forwarding address, not just an alias), and that the forwarding rule sends to that exact address.

The lead has no source

The Source Label must match the name of an active lead source in Settings > Lead Sources.

Related Guides

• Connecting Your Integrations
• External API Overview
• Webhook Integrations
• Meta Lead Ads
• Google Lead Ads