Create a student.
Adds one student account, with the same rules as adding a student from the Users list in the AwardSpring
admin interface: a first name, a last name and a well-formed email are required, each at most 50
characters. An optional student_id must not already be on another account. The new student gets the
same welcome email the admin interface sends, with a link to set a password.
An email that already has an account: by default the email must not already be used by any account
at the institution, ignoring upper and lower case; if it is, this returns 400 email_already_exists.
With if_email_in_use set to add_role, this does what the admin interface does instead, and no
second account is made. When an active account at the institution has the email, the student role is added
to that account, which keeps its name, email, password and student ID (a student_id sent with the request
is still checked against other accounts but is not saved), and this returns 200 with that account as
the student. An account that already has the student role is returned unchanged, also with 200. The
role is never added to an account that holds an administrator role, and this returns
400 email_already_exists instead, as it does for an email whose account is deactivated, merged, or one
the admin interface would not change. When only an archived account has the email, that account gets no
role: a new student is made with 201 and the email moves to them, as in the admin interface.
The AwardSpring-Existing-Account header says which of these happened: role_added,
role_already_held or email_moved_from_archived. It is absent for an ordinary create.
Welcome email: the response carries an AwardSpring-Welcome-Email header. It is queued
when the email is on its way, not_sent when it could not be sent, and none when the role went
onto an account that already had the email (if_email_in_use set to add_role), which gets no
welcome email. The student is created either way; for
not_sent, send them a set-password link with Reset Password on their account in the admin
interface. A response replayed for an Idempotency-Key carries neither header.
Idempotency: the request supports an optional Idempotency-Key header (any
printable-ASCII string, 1–255 chars — UUIDs work well). When supplied, the same key plus the same
request body within 24 hours returns the original response verbatim without creating a duplicate
student. The same key with a different body returns 422 idempotency_key_request_mismatch; a
concurrent retry while the first call is still executing returns 409 idempotency_key_in_flight.
Authentication
Request
The student’s first name. Required, at most 50 characters. Example: "Jordan".
The student’s last name. Required, at most 50 characters. Example: "Ellis".
The student’s email, which is also how they sign in. Required, at most 50 characters, and not already
used by any account at the institution, ignoring upper and lower case, unless if_email_in_use is
add_role. Example: "jordan.ellis@school.edu".
Optional. The student number the institution assigned (for example an SIS or campus id), at most 50
characters, and not already on another account at the institution. Example: "20260142".
Optional. What to do when an account at the institution already has the email. error, the default,
returns 400 email_already_exists. add_role does what the Users list’s Add user window does:
the student role is added to that account instead of making a second one. Any other value returns
400 validation_failed.
Response
Stripe-style resource discriminator. Stable, snake_case string naming the resource type. Serialized first so it reads as the leading field of every V1 resource body.
The stored ID of the student’s user record. Use it with GET /api/v1/students/{id} and as the user_id filter on the applications and awards lists.
The student number the institution assigned (for example an SIS or campus id). Not guaranteed unique — two student accounts can carry the same number — and may be empty when the institution has not recorded one.
The student’s enrollment standing with the institution: registered (an active
student account) or prospective (added ahead of enrollment, e.g. a recruit).