Move your registrant list to WebinarStack with the bulk registrations API
Load a CSV of registrants into a WebinarStack webinar over the REST API, 100 rows per call, with retry-safe idempotency keys. API only, no dashboard uploader.
Registrant lists move into WebinarStack over the REST API, not the MCP server: send your CSV rows to POST /api/v1/webinars/{id}/registrations/bulk in batches of up to 100, with an API key that has the registrations:write scope. Add an Idempotency-Key header to each batch so a retry is safe. Each row in the response reports its own result, so one bad row does not lose the batch.
Who is this page for?
This page is for someone with a CSV of registrants and an API key, comfortable running a short script. If you were looking for a drag-and-drop CSV uploader in the dashboard, WebinarStack does not have one today, and the endpoint below is the supported route. Other webinar platforms document an uploader in their help centres. Goldcast's "Import registrants using bulk registration" page, checked on 14 November 2026, describes uploading a CSV through its dashboard. We would rather say that plainly in the first screen than have you read to the end to find out.
If you are moving from another platform, the registrant list is a separate job from rebuilding the webinar. The guide to switching webinar platforms covers the rebuild, and the platform-specific walkthroughs for EasyWebinar and EverWebinar or WebinarJam point here for the list.
Why can't an AI assistant do this over MCP?
Because the MCP server can only create test registrations, and that is deliberate. The create_test_registration and register_test_attendees tools exist so you can walk your own funnel as an attendee. They are not for loading real people, and there is no bulk-registration tool on the server's allowlist at all.
If you arrived from the MCP articles and assumed the assistant could load your list as well, it cannot. The assistant can rebuild the webinar. Real registrants go through this endpoint. The MCP server guide covers what the assistant can and cannot touch.
What do you need?
Two things: an API key with the registrations:write scope, and the webinar's UUID. Create the key in the dashboard and pick the scope when you do. The key goes in an Authorization: Bearer header, and you should keep it out of your repository and your shell history. The webinar's UUID is its id, which the webinars_list tool returns if you are using an assistant to look it up.
The base URL is https://webinarstack.co/api/v1.
What does the request look like?
curl -X POST "https://webinarstack.co/api/v1/webinars/$WEBINAR_ID/registrations/bulk" \
-H "Authorization: Bearer $WEBINARSTACK_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2a52-0f3e-4c1b-9d57-3a8e2b7d9c10" \
-d '{
"registrations": [
{
"email": "ada@example.com",
"name": "Ada Lovelace",
"sessionTime": "2026-12-03T15:00:00Z",
"viewerTimezone": "Europe/London"
},
{
"email": "grace@example.com",
"name": "Grace Hopper",
"sessionTime": "2026-12-03T15:00:00Z",
"utmSource": "everwebinar-import",
"utmMedium": "migration",
"utmCampaign": "2026-12-move"
}
]
}'
The fields on each row, copied from the API's schema:
| Field | Required | Notes |
|---|---|---|
| email | yes | A valid email address. |
| sessionTime | yes | An ISO 8601 date and time with a timezone, such as 2026-12-03T15:00:00Z. |
| name | no | 1 to 200 characters. |
| viewerTimezone | no | An IANA timezone name such as Europe/London. |
| utmSource, utmMedium, utmCampaign | no | Up to 200 characters each. The source tag is how you tell imported registrants from organic ones later. |
The body is a single object with one key, registrations, holding the array. Tag imported rows with a utmSource such as everwebinar-import, because it is the only way to find them afterwards in your reporting.
One caution on sessionTime. As of 14 November 2026 the bulk endpoint checks that it is a valid date and time, and we found no check in the code that a session starts at that moment. A typo registers someone for a session that does not exist. Take the times from your webinar's schedule, and run a small test batch first.
How many rows can you send at once?
Between 1 and 100. The limit is checked at the route before any work happens, so a batch of 101 comes back as a validation error with nothing created, rather than being half-processed.
For a longer list, split it into batches of 100 or fewer. A 2,400-row CSV is 24 requests. Use a different idempotency key for each batch, because the key identifies the batch, not the import. This script reads a CSV with email, name and session_time columns and sends it in batches:
import csv, os, sys, uuid, requests
BASE = "https://webinarstack.co/api/v1"
URL = f"{BASE}/webinars/{os.environ['WEBINAR_ID']}/registrations/bulk"
HEADERS = {
"Authorization": f"Bearer {os.environ['WEBINARSTACK_API_KEY']}",
"Content-Type": "application/json",
}
with open(sys.argv[1], newline="") as f:
rows = [
{
"email": r["email"].strip(),
"name": r["name"].strip() or None,
"sessionTime": r["session_time"].strip(),
"utmSource": "everwebinar-import",
}
for r in csv.DictReader(f)
]
failed = []
for start in range(0, len(rows), 100):
batch = rows[start:start + 100]
resp = requests.post(
URL,
headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
json={"registrations": batch},
timeout=60,
)
resp.raise_for_status()
for row, result in zip(batch, resp.json()["data"]):
if not result["ok"]:
failed.append((row["email"], result["error"]["code"]))
print(f"{len(rows) - len(failed)} registered, {len(failed)} failed")
for email, code in failed:
print(email, code)
The script generates a fresh key per batch, which is right for a first run and wrong for a retry. The next section explains why.
How does the idempotency key protect a retry?
The Idempotency-Key header is optional, and the API documentation calls it strongly recommended. With it, a retry cannot create a second set of registrations. Without it, sending the same batch twice is two requests.
What the server does with a key, for 24 hours after it is first used:
- Same key, same body: the original response is replayed, with an
X-Idempotent-Replayed: trueheader. Nothing new is created. - Same key, different body: the request is rejected with
409and the codeIDEMPOTENCY_KEY_CONFLICT. - Same key while the first request is still running: also a
409with the same code. Wait a moment and send the identical request again.
Two details that matter if an import fails partway. A server error (a 5xx response) releases the key, so a retry of that batch with the same key runs normally. And a key is tied to the exact body, so if your script crashed after batch 11, you can rerun it with the same keys and the same batches and the first 11 will replay rather than repeat. To do that, derive each key from the batch, for example a hash of the batch's emails, instead of generating a random one.
What does a partial failure look like?
A 200 means the batch was accepted. It does not mean every row succeeded. The response is an array with exactly one result per row, in the order you sent them:
{
"data": [
{
"ok": true,
"id": "0b7e4d5e-5f0f-4e0a-8f43-5c7f6a1d2e90",
"email": "ada@example.com",
"accessUrl": "https://webinarstack.co/watch/…"
},
{
"ok": false,
"error": {
"code": "DUPLICATE_IN_BATCH",
"message": "Row matches an earlier row in the batch with the same email and session time."
}
}
]
}
A failed row has one of three error codes:
DUPLICATE_IN_BATCHmeans an earlier row in the same batch has the same email and session time. The first one wins.VALIDATION_ERRORis returned when the database already holds a registration for that person and session, for example from an earlier batch.INTERNAL_ERRORmeans the row failed to insert for another reason.
The rule for handling the response is simple. Check every row. Collect the failures, fix them, and send only those rows as a new batch with a new idempotency key. Do not resend the whole batch with a new key, because the rows that already succeeded will come back as duplicates.
A 200 with failed rows is cached and replayed exactly like a clean one. If you retry with the same key you get the same failures back. That is why the retry has to be a new batch under a new key.
Failures that affect the whole request return an error status instead: 400 for a body that fails validation, 401 for a missing or bad key, 404 when the webinar does not exist or has been deleted, 409 for the idempotency conflicts above, and 429 when you are rate-limited.
What does an imported registrant get?
Each successful row creates a registration with its own access link. The row's result includes it as accessUrl, which points to the watch page for that person. Keep it if you need to send the link yourself.
What we have not verified is whether a registrant created through the bulk endpoint receives your registration confirmation email or triggers registered automation rules. The service code that inserts the rows does not itself send either. Before you load a real list, send one batch containing a single address you own and see what arrives. That also tells you whether a 2,400-person import will email 2,400 people.
For a rehearsal that does not look like real traffic, send the header X-Test-Mode: true. It stamps every row in the request as a test registration, with the UTM source api-test-registration.
What is the whole migration, end to end?
- Export the registrant list from the old platform as a CSV.
- Map its columns to
email,nameandsession_time. If the old platform has no session time, pick the session you want each person registered for. - Send a one-row batch with an address you own, and check what arrives.
- Run the script above over the full file.
- Read the failures, fix them, and send only those rows as a new batch.
The API's OpenAPI specification is available to an assistant as the MCP resource webinarstack.openapi.v1. For everything else the platform does, see the features page, or go back to the home page.
Frequently asked questions
- How many registrants can I add in one call?
- Between 1 and 100 rows per request. The limit is checked before any work happens, so a batch of 101 is rejected with a validation error instead of being half-processed. To load a longer list, split it into batches of 100 or fewer and send each one as its own request with its own idempotency key.
- What does a 409 IDEMPOTENCY_KEY_CONFLICT mean?
- It means the Idempotency-Key you sent has been used before with a different request body, or the first request that used the key is still being processed. Use a new key for a new batch. If you are retrying a batch that is still in flight, wait a moment and send the same body with the same key again.
- If a request returns 200, did every registrant get added?
- Not necessarily. A 200 means the batch was accepted, and the response holds one result per row in the order you sent them. Each row is either a success with an access link or a failure with an error code. Read every row, fix the failures, and send only those rows again as a new batch with a new key.
- Can an AI assistant import my registrant list over MCP?
- No. The MCP server can create test registrations for checking a funnel, but it has no tool for loading real registrants. That is a deliberate boundary. Real lists go through the REST bulk endpoint with an API key that has the registrations write scope.
- Not today. The supported route for loading a list is the REST bulk registrations endpoint described on this page. If you need to do this without writing any code, a short script that reads your CSV and posts it in batches of 100 is the whole job, and the example below is one.