Leads

Leads are potential patients captured before they book - a website form submission, a bot conversation, a Facebook Lead Ad. The API is create-only: external channels push leads in with the leads:write scope, and the clinic qualifies, assigns and converts them inside SmileCloud. There is no leads:read - lead data stays in the clinic.

#Create a lead

POST

Field	Type	Description
`first_name`	string, required	Max 120.
`last_name`	string	Max 120.
`phone`	string	Required unless `email` is given.
`email`	string	Required unless `phone` is given.
`source`	string, required	`facebook`, `website`, `phone`, `walk_in`, `referral`, `bot`, or `other`.
`note`	string	Free text (the form message, a bot conversation summary) — lands as a note on the lead's activity timeline. Max 2000.
`external_id`	string	Idempotency key, unique per clinic — e.g. the Meta leadgen id or your form submission id. Strongly recommended.
`attribution`	object	Marketing attribution — see below.
`meta`	object	Free-form payload stored on the lead (form answers, custom fields). Max 50 top-level keys.

curl -X POST https://api.smile-app.co.il/v1/leads \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Dana",
    "last_name": "Levi",
    "phone": "0501234567",
    "source": "website",
    "note": "Interested in teeth whitening",
    "external_id": "form-8817",
    "attribution": {
      "utm_source": "google",
      "utm_campaign": "summer-whitening",
      "gclid": "Cj0KCQjw..."
    }
  }'

{
  "data": {
    "id": "112",
    "first_name": "Dana",
    "last_name": "Levi",
    "phone": "0501234567",
    "email": null,
    "source": "website",
    "status": "new",
    "attribution": { "utm_source": "google", "utm_campaign": "summer-whitening", "gclid": "Cj0KCQjw..." },
    "created_at": "2026-08-02T14:05:00+03:00"
  }
}

201 means the lead was created. 200 means it already existed - either the same external_id was replayed, or the phone/email matched an open lead (not converted or lost); the submission is then preserved on that lead's activity timeline instead of creating a duplicate, and the matched lead is returned (its status shows where it already got to).

#Attribution

attribution is a flat key→value map recording where the lead came from. It is deliberately generic - any key is accepted (values max 512 chars, max 30 keys), so every channel a clinic pipes leads through can attach whatever it knows. Conventional keys:

Key	Meaning
`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`	Standard UTM parameters.
`gclid`	Google Ads click id.
`fbclid` / `ctwa_clid`	Meta click id / click-to-WhatsApp click id.
`ttclid`	TikTok click id.
`referrer_url`, `landing_page_url`	Where the visitor came from and landed.
`campaign_name`	Human-readable campaign label.

Send it if you have it

Attribution can't be reconstructed later. Pass click ids and UTM tags at capture time even if you don't use them yet - they make conversion reporting and offline-conversion feedback possible down the road.

#Connecting channels with Zapier

The recommended way to connect Facebook Lead Ads, Google Ads lead forms, landing-page builders and similar channels is Zapier (or any equivalent automation platform):

Create a Zap with the channel as the trigger (e.g. Facebook Lead Ads → New Lead).
Add a Webhooks by Zapier → POST action to https://api.smile-app.co.il/v1/leads.
Set the Authorization: Bearer sk_live_... header with an API key that carries only the leads:write scope.
Map the form fields to first_name, phone, email, set source accordingly, and map the platform's lead/submission id to external_id so retried deliveries never create duplicates.
Map ad/campaign fields into attribution (e.g. campaign_name, fbclid).

Least privilege

Mint a dedicated key holding only leads:write for each automation. A leaked form-integration key then can't read a single patient record.