Lucida

Connect a Lucida project and Referalli sends each new referral and each earned commission to it as a product event, on the referred customer, so funnels and cohorts in Lucida can split by partner and program.

Connect

curl -X PUT https://referalli.com/v1/integrations/lucida \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"apiKey": "lc_sk_...", "host": "https://capture.example.com"}'

• apiKey: a Lucida project key (a secret lc_sk_… key, or the public lc_pk_… one). Write-only, stored encrypted.

• host: your Lucida capture gateway (your own host when self-hosted). Events go to {host}/v1/batch.

• status: "paused" stops sending; DELETE /v1/integrations/lucida disconnects.

POST /v1/integrations/lucida/test sends one referalli_connection_test event and answers { "ok": true } or the error. Owners and admins only.

Events

Properties are the event's fields (referralId, partnerId, programId, amountMinor, currency, …) plus:

• anonId: the visitor id the customer's sign-up was matched from (the anonId of associate, or the tracking script's), or null.

• referalliEventId: the Referalli event id.

Use your app's user id as customerRef (the id you pass to Lucida's identify), and Lucida joins the referral to the visitor's anonymous history from before sign-up. Each event carries a stable uuid, so a retried delivery is counted once. Deliveries retry with backoff for 3 days; GET /v1/integrations/deliveries?kind=lucida lists them.

Pay a bounty on a Lucida activation

When your app sees the moment Lucida calls activation (for example the activated event you capture), report it to Referalli too and the program's activation bounty pays the partner once per referral:

lucida.capture({ distinctId: user.id, event: 'activated' });
await fetch('https://referalli.com/v1/track/events', {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.REFERALLI_API_KEY}`, 'content-type': 'application/json' },
  body: JSON.stringify({ type: 'event', programId: process.env.REFERALLI_PROGRAM_ID, customerRef: user.id, event: 'activation', idempotencyKey: `activation:${user.id}` }),
});

Add an activation entry to the program's commission rule first. See Report a product event.