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": "client",
  "query": "best running shoes",
  "limit": 3
}
'
[
  {
    "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%"
    }
  }
]

Authorizations

​
x-zc-api-key
string
header
required

Tenant API key for authentication. Obtain from https://developer.zeroclick.ai/ under API Keys. This key should be kept secure and not exposed in client-side code when using server-side integration.

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

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

​
userAgent
string

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

​
origin
string

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

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

Required range: 0 < x <= 8
​
userEmailSha256
string

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

​
userPhoneNumberSha256
string

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

​
groupingId
string

Tenant-defined grouping ID for analytics segmentation

​
userId
string

Tenant-defined user ID for analytics and personalization

​
userSessionId
string

Tenant-defined session ID for session-level tracking

​
userLocale
string

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

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