Create a scholarship.
Creates a scholarship with its name, description, dates, financial totals, payment schedule,
department and donor associations, custom-field answers, and applicant-notification settings.
Errors come back with a stable code, a readable message, and per-field
details, so a caller can tell what to correct.
This endpoint enforces exactly the same rules as creating a scholarship in the AwardSpring admin interface, so anything rejected here would also have been rejected there.
A typical call supplies the award’s name, dates falling inside the active award cycle, a
budget total, and any donor association. The response returns the new
scholarship_id, which you can use in follow-up requests.
Set dry_run=true (query param or Dry-Run: true header) to validate without persisting.
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 scholarship. 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. Only 2xx responses are
cached — 4xx/5xx leave the key available for retry with a corrected payload.
Assistant capability: springiq_create_scholarship. Required permission: Scholarships (applies when called on behalf of a signed-in person).
Authentication
Request
Scholarship payload — see CreateScholarshipV1Request for field documentation.
Human-readable name of the scholarship. Required, non-whitespace. Example: "Spring 2026 STEM Award".
Free-form description of the scholarship. Required, non-whitespace. Shown to applicants in
the scholarship details panel. Example: "Award for incoming STEM majors with financial need.".
The stored ID of the award cycle this scholarship belongs to. Required. Example: "4MZ8QW2TC".
ISO 8601 datetime when applicants can begin applying. Example: "2026-08-01T00:00:00".
Interpreted in the tenant’s configured time zone.
ISO 8601 datetime when applications close. The persistence layer normalizes this to the end
of the chosen day. Example: "2026-10-15T23:59:59". Must be after
ApplicationStartDate and within the parent award cycle’s date range.
ISO 8601 date of the first disbursement to awarded students. Required — the admin UI
requires it on every scholarship, and this endpoint enforces the same rule. Defaults are
not applied server-side; send the institution’s intended first payment date. Example:
"2027-01-15".
Optional external fund identifier (matches a Fund.FundIdName in the tenant’s funds
directory). When Funds Management is enabled and the supplied ID does not match an existing
fund, a new fund row is created automatically. When it matches, the scholarship is linked to
that fund. Example: "GEN-2026".
Whether this is a Special Funds scholarship (a tenant-controlled cap on how many of these
can exist per award cycle). Defaults to false. Cannot be combined with
IsInstitutionalAwardScholarship — a request with both set to true is
rejected with a validation_failed error.
Optional label for the first disbursement’s academic term, shown alongside the
disbursement date. Maximum 50 characters. Example: "Spring 2027".
Optional total number of recipients to award. Combined with TotalScholarshipValue
to derive a per-award amount. Must be a positive integer (1 to 999,999) when supplied. Example: 10.
Optional total dollar value of the scholarship across all recipients. Combined with
TotalAwardsNumber to derive a per-award amount. Must be non-negative when
supplied. Example: 50000.00.
Optional number of payments each recipient receives. Must be 1 or greater when supplied.
When it is 2 or more, payment_schedule_ids must name one payment schedule for each payment
after the first. Example: 2.
The award cycle’s payment schedules used for the second and later payments, one per payment after
the first, in date order. Required when payments_per_award is 2 or more, and must be left out
otherwise. List them with GET /api/v1/payment-schedules?award_cycle_id=; each id must be one of
the schedules configured on the scholarship’s award cycle, and any other id is rejected.
Example: [12].
Optional stored ID of the department the scholarship is owned by. Used for Department Admin
scoping. Example: "9TQ3HX7PD".
Optional list of the stored IDs of donors or donor organizations associated with the scholarship.
Example: ["2KD7RW4MA", "8PX5NT3QF"].
Whether the scholarship is deactivated on create (rare — typically left false).
Example: false.
Whether this is an Institutional Award scholarship (recipients selected by the institution
rather than through a public application flow). Cannot be combined with
IsSpecialFunds — a request with both set to true is rejected with a
validation_failed error. Example: false.
Optional internal notes for admin staff. Not shown to applicants. Example:
"Cycle 2026 STEM partnership with ACME Corp.".
Response
The stored ID of the newly created scholarship. Stable for the lifetime of the scholarship. Null on
a dry run, which creates nothing. Example: "7HQ2KW9XR".