Skip to main content
Soventro

Registration on your own website

Four ways to take registrations outside Soventro. Every one uses the same server-side rules, so prices, invitations, approvals and the one-registration-per-person rule hold whichever you choose.

Choosing a method

What each method supports
FeatureHosted linkEmbed scriptPlain iframeJSON API
SetupNoneAdd your site, paste a snippetAdd your site, paste a tagTurn the API on, write code
Types, questions and conditionsYesYesYesYou render them from the form we return
Invitations and discount codesYesYes, from the page address or data-codeYes, in the frame addressYes, as request fields
Approval and waitlistsYesYesYesYes
Card paymentOn the pageOpens the hosted pageOpens the hosted pageSend people to continueUrl
Automatic heightNot neededYesNo, set a heightNot needed
Completion eventsNoYesNoThe response itself
Return to your siteStatus page link, if configuredYesLink in the frameYes, confirmationUrl
Your brandingFull event themeLogo, colors, optional transparent backgroundSame as scriptEntirely yours

Setup

In Soventro, open the event and choose Embed & API. You need permission to manage the event. Both embedding and the API are off until you turn them on, and a cloned event starts with them off.

Embed script

Paste this where the form should appear. The link inside is what people get if the script can't run.

<div data-soventro-event="ORG/EVENT">
  <a href="https://soventro.com/e/ORG/EVENT">Register</a>
</div>
<script src="https://soventro.com/soventro-embed.js" async></script>

Optional attributes on the div:

code, invite, ref and utm_* in your page's address are passed to the form, so existing direct links and campaign tracking keep working. To add a form after the page has loaded:

Soventro.mount(document.getElementById("signup"), {
  event: "ORG/EVENT",
  type: "vip",
});

The form takes your organization's logo and brand colors from Soventro. If a site isn't allowed, the browser refuses the frame. After ten seconds the script replaces it with a link to the hosted page and fires an error event.

Events

Events carry the reference, status, event slug and type key. They never carry names, emails or answers, so they're safe to pass to analytics.

Soventro.on("submitted", (e) => console.log(e.reference, e.status));
Soventro.on("completed", (e) => gtag("event", "registration", { ref: e.reference }));

// Or, on the element or anything above it:
document.addEventListener("soventro:payment_required", (e) => console.log(e.detail.status));

No event fires after payment, because the person has left your page by then. Payment success comes back as a visit to your confirmation page, with soventro_reference and soventro_status in its address. These parameters are a courtesy for your page and analytics, not proof of payment. For that, use webhooks.

Plain iframe

For site builders that don't allow scripts. Allowed sites only. There's no automatic height and there are no events.

<iframe
  src="https://soventro.com/embed/ORG/EVENT"
  title="Event registration"
  style="width:100%;height:1100px;border:0">
</iframe>

Don't add a sandbox attribute, because it can stop the button that opens the payment page.

Payment

Card details are never taken inside a frame or through the API. After submit, a paid registration gets a continueUrl that opens the hosted payment page, where the payment provider handles bank authentication such as 3-D Secure and any redirects, and invoices can be chosen if the event offers them.

Public API

No keys: it exposes only public event data and does what the public form does. Turn it on per event. Browser calls work only from allowed sites, and servers may call it without an Origin header. It doesn't read registrations back; for that, use the API with keys from your server.

1. Read the event and its public options

curl https://soventro.com/api/public/v1/events/ORG/EVENT

Types by invitation only aren't listed.

2. Read an option's questions and price

curl "https://soventro.com/api/public/v1/events/ORG/EVENT/options/vip?code=EARLY20"

Returns form (questions, with their conditions), price in minor units, discount and blocked, which says why it can't be used right now. An invitation-only type answers 403 invite_required unless you add a valid invite. Show the total you get here and send it back on submit.

3. Submit

const res = await fetch("https://soventro.com/api/public/v1/events/ORG/EVENT/registrations", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    typeKey: "vip",
    identity: { email: "ada@example.com", firstName: "Ada", lastName: "Lovelace" },
    answers: { job_title: "COO", terms: true },
    discountCode: "EARLY20",     // optional
    expectedTotalMinor: 80000,   // optional: refused if the price moved
    inviteToken: undefined,      // optional
    source: { utm_source: "newsletter" }, // optional
  }),
});
const body = await res.json();
if (!res.ok) showErrors(body.error.message, body.error.fields);
else if (body.next === "payment") location.assign(body.continueUrl);
else showThanks(body.reference, body.status);

A success is 201:

{
  "registrationId": "0193…",
  "reference": "REG-7K2M9Q",
  "status": "awaiting_payment_method",
  "next": "payment",
  "continueUrl": "https://soventro.com/e/ORG/EVENT/r/0193…/continue?t=…",
  "continueExpiresAt": "2027-03-01T15:00:00.000Z",
  "confirmationUrl": null
}

Answers use question ids from the form. Multiple choice takes an array, and consent takes true. Question conditions are applied on the server, and answers to hidden questions are dropped.

Each person has one registration per event, so retrying a success doesn't make a second one. It answers 409 already_registered, and we email that address a sign-in link. A cancelled or rejected registration is reopened, as on the hosted form.

Errors

Errors look like { "error": { "code", "message", "fields" } }, where fields maps a field or question id to its message.

API with keys

For your own servers: read events, attendee types and registrations, and create registrations, across your organization. An owner or admin creates keys under Integrations and chooses what each may do. The key is shown once; Soventro keeps only a hash of it. Revoking takes effect at once. Each key shows when it was last used, and creating and revoking are in the audit log.

Keys are server secrets. The API sends no CORS headers, so a web page can't read its answers. Don't put a key in a browser or an app.

curl "https://soventro.com/api/v1/events?limit=25" \
  -H "Authorization: Bearer sov_…"

Endpoints

API endpoints
RequestPermissionReturns
GET /api/v1/eventsevents:readEvents, oldest first. Filter with status.
GET /api/v1/events/{id}events:readOne event.
GET /api/v1/events/{id}/attendee-typesevents:readTypes with price, capacity, access and approval.
GET /api/v1/events/{id}/registrationsregistrations:readRegistrations with person, type, answers and money. Filter with status and updatedSince.
GET /api/v1/registrations/{id}registrations:readOne registration.
POST /api/v1/events/{id}/registrationsregistrations:writeCreates one, under the public rules.
GET /api/v1/meanyThe key's id, organization and permissions.

Pages

Lists take limit (1 to 100, default 25) and cursor, and answer { "data": [...], "hasMore": true, "nextCursor": "…" }. Pass nextCursor back as cursor until hasMore is false. For an incremental sync, note the time you started and pass it as updatedSince next time.

let cursor;
do {
  const url = new URL("https://soventro.com/api/v1/events/EVENT_ID/registrations");
  url.searchParams.set("limit", "100");
  url.searchParams.set("updatedSince", lastRun);
  if (cursor) url.searchParams.set("cursor", cursor);
  const page = await fetch(url, {
    headers: { Authorization: "Bearer " + process.env.SOVENTRO_KEY },
  }).then((r) => r.json());
  for (const r of page.data) save(r);
  cursor = page.nextCursor;
} while (cursor);

Creating registrations

The body is the same as the public API's, and the same server rules apply: dates, invitations, eligibility, approval, capacity, discounts, required questions, and one registration per person per event. Keys get no staff overrides, and the event's public API switch doesn't apply to them. Paid registrations come back with next: "payment" and a one-time continueUrl for the attendee. Someone already registered gets 409 already_registered, with the existing registrationId if the key can read registrations, and no email is sent.

Send an Idempotency-Key header (any unique string up to 255 characters) so a retry after a timeout can't act twice. For 24 hours, the same key and body get the first answer again, with Idempotent-Replayed: true. The same key with a different body is refused with 422 idempotency_mismatch; while the first request is still running, a repeat gets 409 idempotency_in_progress.

curl -X POST https://soventro.com/api/v1/events/EVENT_ID/registrations \
  -H "Authorization: Bearer sov_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-sync-8841" \
  -d '{"typeKey":"vip","identity":{"email":"ada@example.com","firstName":"Ada","lastName":"Lovelace"},"answers":{"terms":true}}'

Errors have the same shape as the public API's. Also: 401 unauthorized for a missing, wrong or revoked key, and 403 insufficient_scope when the key lacks the permission. Ids from another organization answer 404.

Webhooks

Soventro can POST a JSON event to your server when something happens. Add an endpoint under Integrations, choose its events, and keep the signing secret, which is shown once.

POST /your/endpoint
Content-Type: application/json
Soventro-Signature: t=1793606400,v1=5f2b…
Soventro-Event-Id: 0193…
Soventro-Event-Type: registration.confirmed
Soventro-Delivery-Id: 0193…

{
  "id": "0193…",
  "type": "registration.confirmed",
  "apiVersion": "2026-11-01",
  "createdAt": "2026-11-02T10:00:00.000Z",
  "data": { "registration": { "id": "0193…", "reference": "REG-7K2M-9QXA", "status": "confirmed", … } }
}

Checking the signature

v1 is the hex HMAC-SHA256, keyed with your secret, of the timestamp t, a dot, and the raw request body. Compute it over the body exactly as received, compare in constant time, and refuse timestamps more than 5 minutes from your clock, so a captured request can't be replayed later.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body exactly as received, before any JSON parsing.
function verify(secret, header, rawBody) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
  const got = Buffer.from(parts.v1 ?? "");
  return got.length === expected.length && timingSafeEqual(got, Buffer.from(expected));
}

Delivery

Limits

Limits by method
LimitApplies toValue
ReadsAPI120 a minute per IP address
Discount code checksAPI, embed30 a minute per IP address
Page loadsEmbed, iframe240 a minute per IP address
SubmissionsAPI, embed, iframe20 a minute per IP address
Submissions per emailAPI, embed, iframe5 in 10 minutes for each event
Submissions per eventAPI, embed, iframe120 a minute
Request sizeAPI64 KB
Allowed sitesEmbed, iframe, browser API calls20 per event
Continue linkAll but the hosted linkOne use, 60 minutes
Reads with a keyAPI with keys600 a minute per key
Writes with a keyAPI with keys120 a minute per key
Request size with a keyAPI with keys64 KB

If you submit from your own server, every attendee shares your server's IP address, so the per-address limit applies to all of them. Calling from the attendee's browser avoids that. Tell us if a large on-sale needs more.

Security