RamenID

Base URL, authentication, request format and error handling for the RamenID REST API.

The API lets your server create a single-use verification link for one student and check how it went. Students still verify on a RamenID page with your branding; the API decides who the link is for.

Endpoint	What it does
`POST /api/v1/verify/{workspace}`	Create a link for one student's email
`GET /api/v1/verify/{workspace}/{id}`	Get a link's status, and its discount code once created

Results can also be pushed to you with webhooks.

Base URL

https://ramenid.com/api/v1

Authentication

Send your API key as a bearer token on every request:

Authorization: Bearer rmn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Call the API from your server only. Keys are not meant for browsers or apps, and the API does not send CORS headers.

{workspace} is your workspace address from Settings → Links, for example acme. It must match the workspace the key belongs to, otherwise you get 403 wrong_workspace. If you change your address, update your integration at the same time.

Requests

Send bodies as JSON. We recommend Content-Type: application/json.
Unknown fields are rejected, so typos fail loudly instead of being ignored.
Times are ISO 8601 strings in UTC, like 2026-10-26T18:00:00.000Z.
IDs are UUIDs.

Errors

Errors return a non-2xx status and a JSON body with a stable error code and a readable message:

{
  "error": "wrong_workspace",
  "message": "This API key does not belong to the workspace \"acme\"."
}

Server errors also include "retryable": true. Branch on error, not on message; messages may be reworded. All codes are listed in Errors.

Limits and usage

The API itself has no rate limit, and creating or reading links does not count toward your plan.
Usage is counted when the student asks for an email code on the link, and when a new discount code is created. See Plans and limits.
At a plan limit, the API still creates links; the student's page explains that the offer has reached its limit.

What the API does not do

It does not choose a discount per request. Every link gets what API links give students is set to in Settings.
It does not check the email's school when you create the link. That happens when the student opens it.
It does not let you send or check the 6-digit code yourself; the student always verifies on the RamenID page.
There are no endpoints to list, change or cancel links, or to manage rules. Links expire on their own after 7 days.
There are no SDKs yet. Any HTTP client works.

API overview