Concepts

Leads

Send enquiries from your own forms to the clinic's CRM: field aliases, warnings, strict mode.

A lead is a patient's enquiry. This page explains how to send one from your own form so that it reaches the clinic's CRM exactly like an enquiry from the clinic's site.

Send a lead

Call POST /leads from your server with the form's fields as JSON:

cURL

curl -X POST "https://app.pozyskajpacjenta.pl/api/v1/leads" \
  -H "Authorization: Bearer $PP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Anna Kowalska", "phone": "+48 600 100 200", "message": "Proszę o kontakt w sprawie higienizacji.", "utm_source": "google" }'

200 OK

{
  "ok": true,
  "leadId": "rS2bIhedVSStSQLc7DL_T"
}

The lead lands in the clinic's panel under Zapytania, with its activity history. Reception gets an e-mail at the clinic's notification address (a text message only when the clinic connected its own SMS operator account), and a configured webhook receives lead.created.

Field names

Field names are matched loosely, in Polish or English and in any letter case; the first non-empty alias wins:

Lead field	Accepted names
`name`	`name`, `full_name`, `fullname`, `imie`, `imię`, `imie_nazwisko`
`phone`	`phone`, `tel`, `telefon`, `phone_number`, `numer`
`email`	`email`, `e-mail`, `mail`
`message`	`message`, `wiadomosc`, `wiadomość`, `msg`, `comment`, `opis`

Nothing is lost: fields outside the table are kept with the lead as extra fields and shown in the CRM (for example "formularz": "landing-higienizacja"). Campaign parameters utm_source, utm_medium, utm_campaign, gclid and fbclid are stored as the lead's tracking data too: pass them on from your landing pages.

A lead without a contact

For the clinic to call back, send a phone number (at least 6 digits) or an e-mail address. The server looks for one under the aliases, then in the other fields (for example phoneNumber, or any value that looks like an e-mail). A lead without either is still stored, and the response warns you:

200 OK

{
  "ok": true,
  "leadId": "Sj2mY5tuT1UZP0QfgdvLH",
  "warnings": [
    "missing_contact"
  ]
}

To refuse such a lead instead, add ?strict=1: nothing is stored and you get 400 missing_contact. Your form can then ask for a phone or an e-mail.

Errors

Status	code	Meaning
400	`invalid_json`	The body is not JSON. Nothing was stored.
400	`invalid_body`	The JSON is not an object. Nothing was stored.
400	`missing_contact`	Only with `?strict=1`: no phone and no e-mail.
400	`invalid_time_request`	Only with `?strict=1`: `timeRequest` failed validation.
401		The key is missing or not valid.
429		Over 120 requests in this minute.

Other ways to send a lead

POST /api/v1/leads is the endpoint for new integrations: Bearer header only, counted in the per-key limit.
POST /api/ingest/lead is the older endpoint for form tools and automations that cannot set headers. It takes the same key and the same field mapping, and also accepts the key in the address (?key=…). Use v1 in new code.
The clinic's embed script puts a form on a site that has no backend. It uses a separate public key (ppe_…) from Ustawienia → Integracje → Skrypt embed. Never put the secret pp_live_ key in browser code.

Spam traps (honeypot fields) apply to browser forms only; the API accepts a request with a valid key as it is.

Privacy and a request for a time

Show the clinic's information clause under your form and send its version with the lead: see Privacy. A lead can also carry a request for a time: see Booking modes.