Skip to main content
POST
Submit a lead form

Authorizations

Authorization
string
header
required

API Key Authentication

Use your API key in the Authorization header:

Key Types:

Secret Keys (Server-Side Only):

  • Format: tybrite_sk_live_* (production) or tybrite_sk_test_* (sandbox)
  • Full read/write access to all endpoints
  • ⚠️ NEVER expose in client-side code or public repositories
  • Required for: every write a shopper does not make for themselves, authentication, payment verification, AI recommendations

Publishable Keys (Client-Safe):

  • Format: tybrite_pk_live_* (production) or tybrite_pk_test_* (sandbox)
  • Catalogue reads, plus the actions a shopper takes for themselves
  • ✅ Safe for client-side JavaScript, mobile apps, and public code
  • Allowed for: browsing products, search, CMS content, pricing queries, cart and wishlist, reviews, storefront events, and the Agent API's quotes, cart drafts and checkout intents

Endpoint-Specific Requirements:

  • Authentication endpoints (/v1/auth/*): Secret key required
  • Payment verification (POST /v1/payments/verify): Secret key required
  • AI Recommendations (POST /v1/recommendations): Secret key required
  • Semantic Search (POST /v1/search): Both key types allowed (read-only operation)
  • Shopper actions (cart, wishlist, reviews, storefront events, Agent API quotes, cart drafts and checkout intents): Both key types allowed
  • All other write operations: Secret key required
  • All read operations: Both key types allowed

Using a publishable key for restricted operations returns 403 Forbidden.

Headers

Idempotency-Key
string

A unique string of 1 to 255 printable characters that identifies this submission.

Required string length: 1 - 255
X-Forwarded-Shopper-Ip
string

The shopper's IP address. Honoured on a secret key only.

Path Parameters

slug
string
required

The form's address.

Pattern: ^[a-z][a-z0-9-]{0,62}$

Body

application/json

Up to 16 KB of JSON, sent as application/json.

email
string<email>
required

The shopper's email address.

Example:

"john.doe@example.com"

answers
object

Answers keyed by field name, at most 30. A multiselect answer is an array.

Example:
consents
object

The consents the shopper gave.

captcha_token
string

The challenge widget's result. Required when the form's captcha.required is true, or when a refusal with reason captcha_required asks for it.

form_token
string

The token returned by POST /v1/lead-forms/{slug}/token. A submission with an invalid token is acknowledged and discarded; one with no token is accepted but held to a tighter per-address limit and answers 429 past it.

website_url
string

The hidden field named by the form's hp_field. Leave empty.

source
string

A label for where the signup happened. At most 200 characters.

Example:

"post:summer-style-guide"

page_url
string

The page the form was on. At most 500 characters.

Example:

"https://shop.example.com/pages/lookbook"

utm
object

Campaign parameters, up to 10 string entries.

Example:

Response

The submission was accepted.

submitted
boolean
required
Example:

true

pending_confirmation
boolean
required

True when the signup is waiting for the shopper to confirm from an email.

Example:

false

message
string
required

The form's success message, for display.

Example:

"Thanks, check your inbox."

submission_id
string<uuid>
required
Example:

"7c1f6a52-3b0e-4d8e-9d55-0f4a9a2c3e11"