Documentation

Quickstart

Paste this. There is nothing to install and no build step.

<div id="soul"></div>
<script src="https://www.soulverified.com/sdk.js"></script>
<script>
  Soul.init({
    partner: 'YOUR_SLUG',
    key:     'YOUR_PUBLISHABLE_KEY',
    user:    currentUser.id,
    city:    'New York',
  });
  Soul.Community({ el: '#soul' });
</script>

If your platform lets you paste HTML but not write JavaScript, the markup path does the same thing:

<script src="https://www.soulverified.com/sdk.js"></script>
<div data-soul partner="YOUR_SLUG" data-user="123" data-city="New York"></div>

Or scaffold a real component with curl soulverified.com/install | sh. Try any of it against the free sandbox first: an unregistered slug needs no key, reads are real, and writes are inert.

How it works

An agent reads who your users are, programs real gatherings for them at free public walk-in places, fills them, and reads its own results to decide what to program next. Nothing waits for anyone on your side to have an idea.

The parts that are not a model

Worth stating plainly, because it is the first thing a technical evaluator tries to work out. Deciding which gathering surfaces for which person is deterministic whole-word comparison over a fixed vocabulary of traits, plus a bias toward the hours someone actually keeps. It is inspectable and the same every time. Models write the gatherings and read each person into that vocabulary; they do not do the matching.

The vocabulary is closed on purpose. Free text would be fluent and useless, because “loves early mornings” and “morning person” do not match each other. A fixed set is the only way two people arriving from different products land on the same word. The agent, in full.

Sandbox and live

• Sandbox is any unregistered slug. Free forever, no key, no card. Reads are real; writes are created inactive so nothing you make in a sandbox reaches a real person.
• Live is a registered slug plus your key. Writes are real, webhooks are available, and the board is programmed for your users specifically.
• Lapsed returns 402 on reads and writes. A partner who stops paying is never quietly downgraded to the sandbox.

Authentication

Two keys. The publishable key is scoped to your slug and is safe in a browser, which is what the snippet above uses. The secret key is for server-to-server calls, including registering a webhook, and must never ship to a client.

Soul.config() never returns a key. Ask us to set an origin allowlist and a leaked publishable key stops working from anywhere but your own hosts.

SDK reference

Full types at /soul.d.ts. Every call resolves to an object rather than rejecting, so our downtime cannot break your interface.

Building your own interface

const { events } = await Soul.events({ limit: 5 });

events.forEach(e => {
  console.log(e.title, e.when, e.where, e.going, e.why);
  // e.checkin === 'open'  ->  show your "I'm here" control
});

REST reference

Everything the SDK does, over HTTP, with CORS. Use this if you would rather not run our script at all.

Webhooks

So your backend learns what happened without polling us. Register one endpoint from your server.

curl -X POST https://www.soulverified.com/api/embed/webhook \
  -H 'content-type: application/json' \
  -d '{
    "partner": "YOUR_SLUG",
    "key":     "YOUR_SECRET_KEY",
    "url":     "https://yourapp.com/hooks/soul"
  }'

# -> { "ok": true, "url": "...", "secret": "whsec_...", "events": [...] }
# Store that secret now. It is never returned again.

Events

What a delivery looks like

POST /hooks/soul
Soul-Signature: t=1785000251,v1=6f2a...c91d
Soul-Event:     rsvp.created
Soul-Delivery:  evt_9f2c4a1b8e6d

{
  "id": "evt_9f2c4a1b8e6d",
  "type": "rsvp.created",
  "created": "2026-07-29T18:04:11.220Z",
  "partner": "acme",
  "data": {
    "user": "u_123",
    "meetupId": "cmrwfqtk2000377jf",
    "title": "Sunrise run, the bridge",
    "startsAt": "2026-08-02T10:30:00.000Z",
    "city": "New York",
    "going": 6
  }
}

Verify every delivery

Soul-Signature is t=<unix>,v1=<hex>, an HMAC-SHA256 over <t>.<raw body> using your secret. The timestamp is inside the signed payload, so a delivery captured today cannot be replayed at you tomorrow.

import crypto from 'crypto';

// rawBody must be the UNPARSED request body. A re-serialised object will not
// match, and it is the most common reason a first integration fails.
export function verifySoul(rawBody, header, secret) {
  const t  = /t=(\d+)/.exec(header)?.[1];
  const v1 = /v1=([a-f0-9]{64})/.exec(header)?.[1];
  if (!t || !v1) return false;

  // Reject anything older than five minutes, or a delivery captured today can be
  // replayed at you tomorrow.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(v1, 'hex'),
  );
}

import hmac, hashlib, time, re

def verify_soul(raw_body: bytes, header: str, secret: str) -> bool:
    t  = re.search(r"t=(\d+)", header)
    v1 = re.search(r"v1=([a-f0-9]{64})", header)
    if not t or not v1:
        return False
    if abs(time.time() - int(t.group(1))) > 300:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{t.group(1)}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, v1.group(1))

Delivery contract

• Reply 2xx. Anything else is a failure.
• Retried twice on a 5xx, a 429 or a timeout, backing off 2s then 8s. A 4xx is treated as your answer and is not retried.
• At least once. Dedupe on id. We will not promise exactly once, because we could not keep it.
• We time out after 5 seconds. Acknowledge first, do your work after.
• Redirects are not followed. Give us the final URL, on a public host, over HTTPS.
• GET /api/embed/webhook returns your last twenty attempts, so a broken integration is debuggable without reading your own logs.

Errors and limits

Rate limits are per IP per minute and listed against each endpoint above. Requests abort after eight seconds. The SDK retries reads and idempotent writes twice with backoff; host() is never retried, because a repeat after a reply we did not see would put the same gathering on your board twice with no undo.

Data and privacy

Security

Versioning

The rolling /sdk.js is cached for five minutes and always carries the current version. Pin with /v/<version>/sdk.js, which is immutable and cached for a year. A published version is never overwritten: the build fails rather than replace one, so a pinned customer cannot be changed underneath.

Fields are added to responses, never renamed or removed without a new major version. Webhook event names are added, never renamed, because a rename breaks every customer’s switch statement at once and silently. Everything we ship is listed on the changelog, generated from the commit history rather than written by hand.