Presuasion submissions

Submit a pre-suasion tool form

Public endpoint — legacy pre-CAP-440 convention. This endpoint departs from the standard v1 API conventions in several ways, documented below. The pre-suasion gateway (demo.capturia.io) calls it when a visitor completes a pre-suasion tool form published on a Capturia account's custom domain.

Authentication: defense in depth

No Bearer API key (the endpoint is called by a public gateway, not by a third-party client). Three stacked layers protect the endpoint:

1. IP rate limit (RATE_LIMIT_CONFIG.LEAD_CREATION_LIMIT requests per LEAD_WINDOW_SECONDS) — cuts high-frequency noise.
2. HMAC signature X-Capturia-Signature: t=<unix>,v1=<hex> — Stripe webhook pattern, SHA-256 over ${timestamp}.${rawBody}, 5-minute replay window, two-key rotation (PRESUASION_HMAC_SECRET + PRESUASION_HMAC_SECRET_PREVIOUS). Log-only mode by default, switched to fail-closed with PRESUASION_HMAC_REQUIRED=true.
3. Cloudflare Turnstile token (turnstile_token body field) verified through siteverify with idempotency_key = the body's submission_id (stable across retries of the same submission — a token is single-use, and Cloudflare replays the original verdict for the same key), falling back to the request's request_id when the submission carries no submission_id. Log-only mode by default, switched to fail-closed with PRESUASION_TURNSTILE_REQUIRED=true.

In addition, a quota per proposition_slug (100 submissions per UTC day, Upstash KV) limits the blast radius of a targeted attack even if the other layers are bypassed.

The target account is resolved server-side through proposition_slug → presuasion_instances.client_id — client_id is never accepted from the body.

Custom body and response format

The body follows a schema specific to this endpoint (PresuasionSubmissionPayload). The 200 response returns a flat object {success, contact_id, contact_created, activity_id} instead of the standard v1 {data: ...} envelope. Errors return {error: "string", issues?: [...]} instead of ErrorEnvelope.

Behavior

• Resolves the target account through an active proposition_slug.
• Finds the contact with the shared funnel engine: matched by email (case-insensitive, secondary emails included), then by a phone number already known for this account — the existing contact is then enriched with the submitted email as a secondary email, never duplicated and never failing on a uniqueness error. Names are filled in without overwriting, the phone number is set if it was missing (a number already held by another contact stays on the submission), and the implied SMS consent triplet is refreshed on every submission (subject to the STOP guard). On the tokenized path (identity_confirmed), the link's contact receives the same additive enrichment.
• Capture routing set on the tool: a contact created by the submission starts in the tool's entry column; the tool's automatic tags are added to every captured contact (created or matched, through the email or the link path); a matched contact that is in no column enters one through the tool. A contact already placed is never moved.
• Inserts a presuasion_submission activity into the contact's timeline with a formatted human-readable Q/R block + raw metadata (responses, result_data, tool_name, proposition). The tool is identified there by its instance: metadata.tool_id and metadata.proposition_id carry the identifier of the resolved proposal, like captures from embedded tools.

Rate limit

Emits the legacy X-RateLimit-* headers (IP counter) — not the RFC 9331 RateLimit-* headers used by the rest of the v1 API.

curl -X POST 'https://api.capturia.io/v1/presuasion-submissions' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "proposition_slug": "blueprint-ventes-2026",
  "tool_id": "calculateur-roi",
  "tool_name": "Calculateur de ROI",
  "email": "[email protected]",
  "first_name": "Alex",
  "phone": "+15145551234",
  "responses": {
    "budget": "500-1000",
    "timeline": "3-mois"
  },
  "formatted_answers": [
    {
      "question": "Quel est ton défi principal en ventes ?",
      "answer": "Je perds des leads parce que je ne suis pas assez rapide à les rappeler."
    }
  ],
  "result_data": {
    "score": 87,
    "recommendation": "premium"
  },
  "completed_at": "2026-05-04T12:34:56.789Z"
}'