Skip to main content
POST
/
api
/
v2
/
offers
curl --request POST \
  --url https://zeroclick.dev/api/v2/offers \
  --header 'Content-Type: application/json' \
  --header 'x-zc-api-key: <api-key>' \
  --data '
{
  "method": "server",
  "ipAddress": "your-user-ip-address",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "query": "cloud hosting solutions",
  "limit": 5,
  "userId": "user-12345",
  "groupingId": "premium-tier"
}
'
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Nike Air Zoom Pegasus 40",
    "subtitle": "Premium running shoe for daily training",
    "content": "Responsive cushioning and breathable mesh upper for comfortable miles.",
    "cta": "Shop Now",
    "clickUrl": "https://https://zeroclick.dev/api/v2/clicks?id=a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "imageUrl": "https://example.com/pegasus40.jpg",
    "brand": {
      "name": "Nike",
      "description": "Global sports and athletic footwear brand",
      "url": "https://nike.com",
      "iconUrl": "https://example.com/nike-logo.png"
    },
    "product": {
      "productId": "nike-pegasus-40",
      "title": "Air Zoom Pegasus 40",
      "category": "Running Shoes",
      "availability": "in_stock"
    },
    "price": {
      "amount": "129.99",
      "currency": "USD",
      "originalPrice": "139.99",
      "discount": "7%"
    }
  }
]

Documentation Index

Fetch the complete documentation index at: https://developer.zeroclick.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
x-zc-api-key
string
header
required

Tenant API key for authentication. Obtain from https://developer.zeroclick.ai/ under API Keys in the Organization API Keys tab. Ensure the key has the required scope (e.g., developer:data:read for analytics endpoints). This is a private key and must be stored securely, never expose it in client-side code.

Headers

​
x-zc-llm-model
string

The LLM model used to parse signals (if any) sent inline in the request body. For consistency, we recommend using the model identifiers listed by Vercel (https://vercel.com/ai-gateway/models).

Maximum string length: 64

Body

application/json
​
method
enum<string>
required

Determines how IP address and User-Agent are sourced. Use "client" when making requests directly from the browser (IP/UA extracted from request headers). Use "server" when making requests from your backend (must provide ipAddress in body).

Available options:
client,
server
​
ipAddress
string | null

Client IP address. Required when method is "server". Ignored when method is "client" (extracted from request headers).

​
userAgent
string | null

Client User-Agent string. Optional when method is "server". Ignored when method is "client" (extracted from request headers).

​
origin
string | null

Request origin/referer URL. Optional when method is "server". Ignored when method is "client" (extracted from request headers).

​
query
string | null

Search query for offers. Example: "best running shoes", "cloud hosting solutions"

​
limit
integer | null

Maximum number of offers to return. Defaults to tenant settings or 1.

Required range: 0 < x <= 8
​
userId
string | null

Tenant-defined user ID for analytics and personalization

​
userSessionId
string | null

Tenant-defined session ID for session-level tracking

​
userLocale
string | null

User locale/language code (e.g., "en-US", "es-MX")

​
userEmailSha256
string | null

SHA-256 hash of user email address for identity matching (lowercase, trimmed before hashing)

​
userPhoneNumberSha256
string | null

SHA-256 hash of user phone number for identity matching (E.164 format before hashing)

​
groupingId
string | null

Tenant-defined grouping ID for analytics segmentation

​
signals
object[] | null

Array of real-time signals about the user's current context or intent. This facilitates offer matching and is useful for providing additional context about the query.

Required array length: 1 - 10 elements

Response

Array of personalized offers

​
title
string | null
required

Title of the offer

​
subtitle
string | null
required

Optional subtitle or brief description of the offer

​
content
string | null
required

Detailed content or description of the offer

​
cta
string | null
required

Call to action text for the offer, to be used for links or buttons

​
clickUrl
string<uri>
required

URL to navigate to when the offer is clicked

​
imageUrl
string<uri> | null
required

Optional image URL representing the offer

​
metadata
object
required

Any additional metadata specific to the offer

​
context
string | null
required

Any additional context about the offer such as "great for gifts", "popular", etc.

​
brand
object
required
​
product
object
required
​
price
object
required
​
location
object
required
​
media
object
required
​
rating
object
required
​
id
string
required

Unique identifier for the offer, scoped to the request

​
activation
object
​
ui
object