Developer documentation

Palyri Leads API

Send leads into Palyri from any source: your own funnel, Make.com, n8n, Zapier or your backend. Report back which lead converted and how much it was worth. Everything counts in Palyri statistics exactly the same way as leads from our own funnels.

Start here

You need a single token. Generate it in the panel: Settings → Integrations → API tokens. The token is shown once. We only store its hash.

curl -X POST 'https://app.palyri.com/api/leads/make-ingest' \
  -H 'X-Palyri-Token: pal_xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "Quiz",
    "external_id": "zgloszenie-8842",
    "ads_consent": true,
    "data": {
      "imię": "Anna",
      "telefon": "500600700",
      "email": "anna@example.com",
      "Jaki masz problem?": "Zmarszczki"
    },
    "campaign_attribution": {
      "utm_campaign": "Botoks Q3",
      "utm_content": "Kreacja A",
      "ad_id": "120210000000000000"
    }
  }'

Authentication

Every request carries the X-Palyri-Token header. A token belongs to one clinic and has a permission scope: leads:write (creating leads) and optionally conversions:write (reporting revenue).

For integrations with higher requirements, enable HMAC signing when creating the token. The token alone then stops being enough: the request must also carry X-Palyri-Timestamp (unix time in seconds) and X-Palyri-Signature. The signature binds the request to its body and time, so a captured request cannot be replayed after 5 minutes.

// Node.js
const crypto = require("crypto")

const body = JSON.stringify(payload)
const timestamp = Math.floor(Date.now() / 1000)
const signature = crypto
  .createHmac("sha256", SIGNING_SECRET)
  .update(`${timestamp}.${body}`)
  .digest("hex")

await fetch("https://app.palyri.com/api/leads/make-ingest", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Palyri-Token": TOKEN,
    "X-Palyri-Timestamp": String(timestamp),
    "X-Palyri-Signature": `sha256=${signature}`,
  },
  body,
})

Creating leads

We accept three payload shapes and normalize them ourselves: the native Meta Lead Ads format (field_data), the Make.com Facebook Lead Ads module format (mappable_field_data) and the simplest one, a data object with field/value pairs. Field names are recognized in both Polish and English.

Response:

HTTP 200
{ "ok": true, "accepted": true }

We reject duplicates three ways: by Meta's leadgen_id, by your external_id, and, as a safety net for submissions without any identifier, by the same phone number within a 10 minute window.

Ad attribution

This is the part that decides whether Palyri can compute your cost per lead. We need the ad identifier, not just its name: a name can be changed in Meta on the fly, the identifier never changes.

In Ads Manager, set the URL parameters for the ad pointing at your funnel:

utm_source=facebook
utm_medium=paid
utm_campaign={{campaign.name}}
utm_term={{adset.name}}
utm_content={{ad.name}}
ad_id={{ad.id}}
adset_id={{adset.id}}
campaign_id={{campaign.id}}

Your funnel reads these parameters from the URL and passes them to us with the lead, either inside the campaign_attribution object or as top-level fields. Both forms work.

Consent & conversion feedback to Meta

Palyri sends events back to Meta through the Conversions API, so the campaign optimizes on what actually happened, not just on clicks. We send three events:

You improve match quality by sending fbp, fbc and fbclid. A deposit lands in the CRM days after the submission, when there is no browser and no cookies left, so we store them at submission time and replay them with every later event.

If your funnel fires its own pixel, send us the same event_id. Meta deduplicates the pair and counts one conversion instead of two.

Reporting revenue

Deposits and revenue entered in Palyri flow to Meta automatically. This endpoint is for sales that close outside Palyri: in your system, at your register. It requires a token with the conversions:write scope.

curl -X POST 'https://app.palyri.com/api/leads/conversion' \
  -H 'X-Palyri-Token: pal_xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "external_id": "zgloszenie-8842",
    "event_name": "Purchase",
    "value": 2400,
    "currency": "PLN",
    "update_lead": true
  }'

HTTP 202
{ "ok": true, "lead_id": "…", "event_name": "Purchase", "event_id": "purchase-…", "queued": true }

Outgoing webhooks

The other direction of the integration: Palyri sends a request to you when something happens to a lead. You register the endpoint in the panel (Settings → Integrations → Outgoing webhooks) and receive a secret for signature verification.

An example request we will send:

POST https://your-server.example/palyri
Content-Type: application/json
X-Palyri-Event: lead.status_changed
X-Palyri-Delivery: 3f2b…            // delivery id, stable across retries
X-Palyri-Timestamp: 1787327270
X-Palyri-Signature: sha256=…

{
  "event": "lead.status_changed",
  "delivery_id": "3f2b…",
  "sent_at": "2026-08-21T15:44:15.155Z",
  "clinic_id": "…",
  "data": {
    "lead": {
      "id": "…",
      "name": "Anna Kowalska",
      "phone": "+48500600700",
      "email": "anna@example.com",
      "status": "deposit_paid",
      "source": "Meta Ads",
      "ad_name": "Kreacja A",
      "external_id": "zgloszenie-8842",
      "treatment_value": null,
      "campaign_attribution": { "utm_campaign": "Botoks Q3" }
    },
    "status": "deposit_paid",
    "previous_status": "contacted"
  }
}

Verifying the signature on your side:

// Node.js: the comparison MUST be constant-time
const crypto = require("crypto")

function verify(req, rawBody, SECRET) {
  const ts = Number(req.headers["x-palyri-timestamp"])
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false

  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(`${ts}.${rawBody}`)
    .digest("hex")

  const got = String(req.headers["x-palyri-signature"]).replace(/^sha256=/, "")
  const a = Buffer.from(expected), b = Buffer.from(got)
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

A failed delivery is retried six times with growing backoff (1 min, 5 min, 25 min, ~2 h, ~10 h). X-Palyri-Delivery stays the same across retries, so use it as an idempotency key, because the same event can reach you twice.

Limits & errors

After rotating a token in the panel, the old one keeps working for 48 hours, so you can swap it in your scenarios without interrupting lead intake. The response then carries a warning field. If the token leaked, revoke the old one immediately. The button sits next to the warning in the panel.