> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paysight.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Leads API

> Create, update, and query tenant-scoped customer leads and correlate them with current Paysight checkout transactions.

Use the Customer Leads API to capture contact and visit data before a customer completes the current Paysight checkout, then retrieve the saved lead and its matched payment details.

## Endpoint

```text theme={null}
POST https://ecom-service.paysight.io/api/public/customer-leads
GET  https://ecom-service.paysight.io/api/public/customer-leads
```

Every request must include `email` and `session_id`. Reusing the same `session_id` updates the existing lead for your tenant instead of creating a duplicate.

<Info>
  Set `session_id` to the same value you send to the current Card Submit or Widget checkout as `partnerSession`. This allows Paysight to mark the lead paid when the successful transaction webhook arrives.
</Info>

## Authentication

Generate API keys from **Tools → Customer Leads → API endpoint** in Platform. Full keys are shown after generation so you can copy them. If a key is lost, generate replacements and update every client because the previous keys stop working immediately.

### Browser

Use the publishable key generated in Platform. The browser origin must exactly match one of the configured allowed origins.

```http theme={null}
X-Paysight-Lead-Key: pk_lead_...
Content-Type: application/json
```

### Server

Use the secret key as a Bearer token. Never expose this key in browser code. Reading leads with `GET` requires this server-only key; publishable browser keys are write-only.

```http theme={null}
Authorization: Bearer sk_lead_...
Content-Type: application/json
```

## Example

```bash theme={null}
curl https://ecom-service.paysight.io/api/public/customer-leads \
  --request POST \
  --header "Authorization: Bearer sk_lead_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "email": "buyer@example.com",
    "first_name": "Jane",
    "last_name": "Customer",
    "session_id": "visit-123",
    "scans": [{"page":"/pricing"}],
    "cfa_device": "mobile"
  }'
```

New leads return `201 Created`; updates return `200 OK`. API clients cannot set `tenant_id`, `status`, or payment fields.

## Query leads

Use exact query parameters with `GET`. Supported filters are `id`, `email`, `session_id`, `transaction_id`, `subscription_id`, and `status`. You can combine filters; all supplied filters must match. Results are ordered by the most recently updated lead and limited to 50 by default or 100 maximum.

```bash theme={null}
curl --get https://ecom-service.paysight.io/api/public/customer-leads \
  --header "Authorization: Bearer sk_lead_YOUR_KEY" \
  --data-urlencode "email=buyer@example.com" \
  --data-urlencode "limit=25"
```

The response always contains an array. Every item is the complete stored lead record, not a summary or excerpt. It includes contact details, scans, pending data, every CFA and D2D field, status, payment identifiers, amount, currency, and timestamps. The tenant ID is intentionally excluded because the secret key already scopes the request to one tenant.

Email addresses are not unique: the same person can have separate lead sessions, so an email lookup may return multiple records. Use `session_id` when you need one specific journey.

Paid records include the transaction, order, application, amount, currency, and subscription identifiers captured when that lead first became paid. This links the lead to the converting payment; it is not a history of every later recurring transaction.

<Info>
  A customer lead is a checkout journey, not a canonical customer profile. Paysight does not currently infer a one-to-one customer relationship from email. If your system needs a permanent customer identity across sessions, keep that mapping in your customer system and use the returned lead, session, transaction, or subscription identifiers.
</Info>

## Paid lead webhooks

When a configured successful transaction matches the tenant, application ID, environment, and `session_id`, Paysight changes the lead to `paid` and sends a `customer_lead.paid` webhook. See [Customer lead integration](/guides/customer-leads) for configuration, payload signing, retries, and verification.