API Reference

Everything you need to integrate Proffer's autonomous offer engine.

Ingest Customer Events

Send behavioral data (page views, purchases, clicks, etc.) for a customer. Proffer automatically creates or updates the customer profile.

Request Body

{
  "customer": {
    "id": "user_12345",           // Your external customer ID (required)
    "email": "sarah@example.com", // Optional
    "name": "Sarah Chen",         // Optional
    "metadata": {                 // Optional — any extra context
      "plan": "free",
      "signup_source": "google_ads"
    }
  },
  "events": [
    {
      "type": "page_view",
      "data": { "page": "/pricing", "duration_seconds": 45 },
      "occurred_at": "2026-03-17T10:00:00Z"
    },
    {
      "type": "purchase",
      "data": { "amount": 29.99, "product": "starter_plan" }
    },
    {
      "type": "click",
      "data": { "element": "upgrade_button", "page": "/pricing" }
    }
  ]
}

Event Types

You can send any event type you want. Common ones:

Type	Description	Useful Data Fields
page_view	Customer viewed a page	page, duration_seconds
purchase	Customer made a purchase	amount, product, currency
click	Customer clicked something	element, page
feature_use	Customer used a feature	feature, times_used
cart_abandon	Customer abandoned cart	items, total
signup	Customer signed up	plan, source

Response

{
  "success": true,
  "customer_id": 1,
  "events_ingested": 3,
  "message": "Events ingested successfully"
}

Generate an Offer

Trigger the AI engine to analyze a customer's behavioral signals and generate a personalized offer with copy, terms, and channel recommendation.

Request Body

{
  "customer_id": 1,                    // Internal customer ID
  // OR
  "external_customer_id": "user_12345" // Your external ID
}

Response

{
  "success": true,
  "offer": {
    "id": 1,
    "customer_id": 1,
    "headline": "Sarah, unlock Pro analytics — 30% off this week",
    "body_copy": "We noticed you've been spending time on our pricing page and exploring analytics features. Here's an exclusive 30% discount to upgrade to Pro and get the full analytics suite.",
    "offer_type": "discount",
    "offer_terms": {
      "discount_percent": 30,
      "code": "SARAH30PRO",
      "valid_days": 7,
      "conditions": "First-time Pro upgrade only"
    },
    "channel": "email",
    "status": "generated",
    "ai_reasoning": "Customer shows strong upgrade intent — viewed pricing 3 times, clicked upgrade button, and has been an active free user for 30 days. Email is the right channel since they have a verified email and engage with product notifications.",
    "expires_at": "2026-03-24T11:00:00.000Z",
    "generated_at": "2026-03-17T11:00:00.000Z"
  }
}

Generate Batch Offers

Generate offers for all eligible customers who haven't received one in the last 24 hours.

Request Body

{
  "min_events": 1,  // Minimum events required (default: 1)
  "limit": 10       // Max customers to process (default: 10, max: 50)
}

List Offers

Query Parameters

Param	Type	Description
status	string	Filter by status: generated, approved, sent, redeemed, expired
channel	string	Filter by channel: email, sms, push, in_app
customer_id	integer	Filter by internal customer ID
limit	integer	Results per page (default: 50, max: 100)
offset	integer	Pagination offset

Get Offer Detail

Update Offer Status

Transition an offer through its lifecycle: generated → approved → sent → redeemed (or expired at any stage).

Request Body

{ "status": "approved" }

Valid Status Transitions

From	To
generated	approved or expired
approved	sent or expired
sent	redeemed or expired

Customers

Quick Start (cURL)

Here's everything you need to go from zero to a generated offer in 60 seconds.

1. Create an API Key

curl -X POST https://proffer-c2hu.polsia.app/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "My Key"}'

2. Send Customer Events

curl -X POST https://proffer-c2hu.polsia.app/api/webhook/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "customer": {
      "id": "user_001",
      "email": "alex@startup.com",
      "name": "Alex Rivera"
    },
    "events": [
      {"type": "page_view", "data": {"page": "/pricing"}},
      {"type": "click", "data": {"element": "start_trial"}},
      {"type": "feature_use", "data": {"feature": "reports", "times_used": 8}}
    ]
  }'

3. Generate an Offer

curl -X POST https://proffer-c2hu.polsia.app/api/offers/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"external_customer_id": "user_001"}'

4. Retrieve the Offer

curl https://proffer-c2hu.polsia.app/api/offers/1