Create a link
POST /api/v1/verify/{workspace} creates a single-use verification link for one student's email.
POST https://ramenid.com/api/v1/verify/{workspace}Creates a link to your branded verification page, locked to one email. Send the student to the returned url. What they get when they finish depends on Settings → Links → API links give students:
- a rule: they get that rule's discount code, and the link reports
minted; - Verification only: they are verified, and the link reports
verified.
That setting is saved onto the link when it is created.
Path parameters
FieldDescription
workspacestring
RequiredYour workspace address, like acme. Must belong to the API key.
Body
FieldDescription
emailstring
RequiredThe student's email. Trimmed and lowercased. Up to 254 characters. The school is checked when the student opens the link, not now.
No other fields are accepted.
Example
curl -X POST https://ramenid.com/api/v1/verify/acme \
-H "Authorization: Bearer $RAMENID_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "ana@mit.edu"}'const res = await fetch("https://ramenid.com/api/v1/verify/acme", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.RAMENID_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ email: "ana@mit.edu" }),
});
if (!res.ok) throw new Error((await res.json()).message);
const link = await res.json();import os
import requests
res = requests.post(
"https://ramenid.com/api/v1/verify/acme",
headers={"Authorization": f"Bearer {os.environ['RAMENID_API_KEY']}"},
json={"email": "ana@mit.edu"},
)
res.raise_for_status()
link = res.json()Response
201 Created
{
"id": "4b8f0c2e-7d1a-4c3b-9e2f-1a6d5c8b7e90",
"url": "https://ramenid.com/acme/k3x9p2m7qa",
"email": "ana@mit.edu",
"mints_discount": true,
"status": "open",
"expires_at": "2026-10-26T18:00:00.000Z",
"created_at": "2026-10-19T18:00:00.000Z",
"completed_at": null
}FieldDescription
idstring (UUID)
The link's id. Save it to look the link up later, and to match webhook events (data.link_id).
urlstring
Send the student here. Works once.
emailstring
The email the link is for, as you sent it (trimmed and lowercased).
mints_discountboolean
true if finishing gives a discount code, false for verification only.
status"open" | "verified" | "minted" | "expired"
Always open for a new link. See Get a link for the others.
expires_atstring
7 days after creation. After this the page shows that the link has expired.
created_atstring
When the link was created.
completed_atstring | null
When the student finished. null until then.
What the student sees
The email field is filled in and locked. If they type a different address, they are told to use the one the link was created for. Plus addressing is ignored when comparing: a link for ana+app@mit.edu accepts ana@mit.edu. See The student experience.
Errors
| Status | error | When |
|---|---|---|
| 400 | invalid_body | The body is not JSON like {"email": "student@school.edu"}, the email is invalid, or there are extra fields |
| 401 | unauthorized | Missing, malformed, unknown or revoked key |
| 403 | wrong_workspace | The key belongs to a different workspace address |
| 409 | discount_off | The rule set for API links is turned off |
| 500 | server_error | Something failed on our side; safe to retry |