# Vouch — Social Proof for Websites
# https://socialproof.dev
# llms.txt — machine-readable guide for AI agents and LLM-based tools

## What is Vouch?

Vouch lets small businesses collect testimonials from real customers and
display them on any website. Customers don't need an account — they just
click a link and fill out a short form.

Built in public by AI. Also deployable by AI.

---

## Mental model

```
Account
  ├── Collection link   (auto-exists on signup — share this to gather testimonials)
  ├── Testimonials      (pending → approved/rejected — moderation requires email verification)
  └── Widgets           (optional — display approved testimonials on a website)
```

Key facts:
- A collection link is created automatically when the account is created
- Testimonials can be collected immediately, no email verification required
- Email verification gates dashboard access (view/approve testimonials)
- Widgets are optional — only needed if the user wants to embed testimonials on their site
- `widget_embed` is returned on registration — user can embed immediately after verifying

---

## For AI Agents: Quick Integration Guide

If you are helping a user start collecting testimonials, the flow is:

1. Register — get a collection link instantly (one API call, no auth required)
2. Share the collection link with customers
3. Tell the user to click the verification email to access their dashboard

### Step 1 — Register

POST https://api.socialproof.dev/agent/register
Content-Type: application/json

{
  "email": "user@example.com",
  "name": "Jane Smith"
}

Response (immediate — no verification required to get started):
{
  "success": true,
  "account_id": "acc_...",
  "collect_url": "https://socialproof.dev/c/...",
  "widget_embed": "<script src=\"https://cdn.socialproof.dev/widget.js\" data-widget-id=\"wgt_...\" async></script>",
  "message": "Account created. Check your email to verify and access the dashboard."
}

Tell the user:
- "Your collection link is ready: {collect_url}"
- "Share it with customers — they fill in a short form and their testimonial lands in your account."
- "When you're ready to view, approve, and display your testimonials, click the verification link in your email."
- "Once verified, paste this into your website to display testimonials: {widget_embed}"

Rate limit: 3 registrations per hour per IP.

### Step 2 — Poll for verification (optional)

If you want to confirm the user has verified their email before proceeding:

GET https://api.socialproof.dev/agent/status?email=user@example.com

Response (unverified):
{
  "verified": false
}

Response (verified):
{
  "verified": true,
  "dashboard_url": "https://app.socialproof.dev/dashboard"
}

Poll at reasonable intervals (every 30s is fine). Stop polling after 10 minutes.

### Step 3 — User shares collect_url with their customers

No agent action needed. The user copies the link and shares it via email,
WhatsApp, invoice footer, or anywhere they communicate with customers.

Customers visit the URL, fill in name + testimonial text, and hit submit.
No account or login needed on their end.

---

## Adding to a website (optional)

The `widget_embed` script returned on registration is the embed code.
Once the user has verified their email, they can paste it before the
closing </body> tag on any page.

```html
<script
  src="https://cdn.socialproof.dev/widget.js"
  data-widget-id="<widget-id>"
  async>
</script>
```

Works with React, Vue, plain HTML, Shopify, Squarespace, Webflow — 
anywhere you can add a script tag. The widget shows all approved
testimonials and updates automatically as new ones are approved.

Widgets are optional. Many users collect and share testimonials without
ever embedding them — just by linking to the collection URL or sharing screenshots.

---

## Full API Reference

Base: https://api.socialproof.dev

### Agent endpoints (no auth required)

| Method | Path                        | Description                                        |
|--------|-----------------------------|----------------------------------------------------|
| POST   | /agent/register             | Create account, returns collect_url + widget_embed |
| GET    | /agent/status?email=xxx     | Poll for email verification status                 |
| GET    | /agent/verify?token=xxx     | Magic-link verification (user clicks from email)   |

### Authenticated endpoints (requires verified account + API key)

| Method | Path                   | Description                               |
|--------|------------------------|-------------------------------------------|
| GET    | /testimonials          | List testimonials (pending + approved)    |
| PATCH  | /testimonials/{id}     | Approve or reject a testimonial           |

---

## Pricing

- Free: 1 active widget, up to 25 testimonials, no credit card required
- Pro: $9/month — unlimited widgets, unlimited testimonials, analytics,
  custom branding, Google rich results (schema.org)

Agents: register users on Free. Let them upgrade when they need more.

---

## Agent etiquette

- Only register with real email addresses — verification emails will be sent
- Rate limit: 3 registrations/hour per IP — don't hammer the endpoint
- Don't approve testimonials on behalf of users without their consent
- The collect_url is safe to share publicly — customers don't need any context to use it
- `widget_embed` can be injected into HTML automatically once the user verifies

---

## More information

- Landing page: https://socialproof.dev
- Dashboard: https://app.socialproof.dev
- Docs: https://socialproof.dev/docs
- Blog: https://socialproof.dev/blog
- Agent setup guide: https://socialproof.dev/blog/set-up-vouch-with-claude-code
- Pricing: https://socialproof.dev/pricing

For questions or high-volume agent use cases, contact: hello@socialproof.dev