Customers

Customer endpoints sit under /api/brands/{brand}/customers/ with moduleAccess:customers middleware. Authenticate with EF-Access-Key.

Customer records are built from conversion and tracking events (purchases, abandoned carts, chargebacks). They are stored in Elasticsearch and cannot be created via API directly — they are created automatically when conversions are recorded.

List Customers

GET /api/brands/{brand}/customers

per_page

number

Results per page (1–100, default: 25)

type

string

Filter by customer type: customer (purchases only) or abandon (abandoned carts only)

string

Search by email, name, or phone

sort

string

Sort field. Any of the sortable columns below.

sort_direction

string

asc or desc

columns

array

Subset of columns to return. Allowed values: customer_email, customer_name, customer_first_name, customer_last_name, customer_phone, customer_country, customer_state, customer_city, last_order_date, first_order_date, total_orders, total_revenue, total_refunds, total_chargebacks, lifetime_value, order_frequency, products_purchased, is_abandoned_customer, abandoned_value

cURL

curl "https://app.elasticfunnels.io/api/brands/{brand_id}/customers?sort=total_revenue&sort_direction=desc&per_page=50" \
  -H "EF-Access-Key: your_api_key_here"

{
  "current_page": 1,
  "data": [
    {
      "customer_email": "jane@example.com",
      "customer_name": "Jane Doe",
      "customer_first_name": "Jane",
      "customer_last_name": "Doe",
      "customer_phone": "+15551234567",
      "customer_country": "US",
      "customer_state": "CA",
      "customer_city": "Los Angeles",
      "first_order_date": "2024-06-01T00:00:00Z",
      "last_order_date": "2024-12-01T00:00:00Z",
      "total_orders": 3,
      "total_revenue": 207.00,
      "total_refunds": 0,
      "total_chargebacks": 0,
      "lifetime_value": 207.00,
      "order_frequency": 90,
      "is_abandoned_customer": false,
      "abandoned_value": 0
    }
  ],
  "per_page": 25,
  "total": 1842,
  "last_page": 74
}

Quick Access Stats

Returns customer counts by type — useful for dashboard badges.

GET /api/brands/{brand}/customers/quick-access

cURL

curl https://app.elasticfunnels.io/api/brands/{brand_id}/customers/quick-access \
  -H "EF-Access-Key: your_api_key_here"

{
  "all": 1842,
  "customers": 1205,
  "abandons": 637,
  "chargebacks": 14,
  "refunds": 38
}

Get Customer Details

Retrieve the full profile for a single customer by email address — includes lifetime stats, order history, subscriptions, and notes.

GET /api/brands/{brand}/customers/{customerEmail}/details

customerEmail

string

required

Customer’s email address (URL-encoded if it contains special characters)

include_orders

boolean

Include full order history (default: true)

include_subscriptions

boolean

Include active subscriptions (default: true)

cURL

curl "https://app.elasticfunnels.io/api/brands/{brand_id}/customers/jane%40example.com/details" \
  -H "EF-Access-Key: your_api_key_here"

Python

import requests, urllib.parse

email = urllib.parse.quote("jane@example.com", safe="")
r = requests.get(
    f'https://app.elasticfunnels.io/api/brands/{brand_id}/customers/{email}/details',
    headers={'EF-Access-Key': 'your_api_key_here'},
)
print(r.json())

{
  "customer": {
    "email": "jane@example.com",
    "name": "Jane Doe",
    "phone": "+15551234567",
    "country": "US",
    "state": "CA",
    "city": "Los Angeles",
    "address": "123 Main St"
  },
  "stats": {
    "total_orders": 3,
    "total_revenue": 207.00,
    "total_refunds": 0,
    "total_chargebacks": 0,
    "lifetime_value": 207.00,
    "first_order_date": "2024-06-01T00:00:00Z",
    "last_order_date": "2024-12-01T00:00:00Z",
    "average_order_value": 69.00
  },
  "orders": [
    {
      "id": "conv-abc",
      "date": "2024-12-01T00:00:00Z",
      "total": 69.00,
      "products": ["1 Bottle"],
      "status": "approved"
    }
  ],
  "subscriptions": [
    {
      "id": 12,
      "status": "active",
      "product": "Monthly Bundle",
      "next_charge_date": "2025-01-01"
    }
  ]
}

{
  "message": "Customer not found."
}

Export Customers

Queue a CSV export of customer records. An email is sent when the export is ready.

POST /api/brands/{brand}/customers/export

filters

array

Filter conditions (same keys as the list endpoint ?type, ?q, etc.)

selected_emails

array

Limit export to specific email addresses

columns

array

Columns to include (subset of the allowed column list above)

cURL

curl -X POST https://app.elasticfunnels.io/api/brands/{brand_id}/customers/export \
  -H "EF-Access-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "columns": ["customer_email", "customer_name", "total_revenue", "last_order_date"],
    "filters": {"type": "customer"}
  }'

{
  "success": true,
  "message": "Export started. You will receive an email when it is ready."
}

Notes

Customer records are read-only — they are created automatically from conversion events
The {customerEmail} path parameter should be URL-encoded
Sorting and filtering use Elasticsearch under the hood; large result sets may be slightly delayed
The columns parameter controls both what is fetched and what is returned, reducing response size for large lists

Getting Started

Endpoints

List Customers

Quick Access Stats

Get Customer Details

Export Customers

Notes

​List Customers

​Quick Access Stats

​Get Customer Details

​Export Customers

​Notes

List Customers

Quick Access Stats

Get Customer Details

Export Customers

Notes