API ReferenceScholarships

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. <b>Idempotency:</b> 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.

Authentication

X-Spring-API-Keystring
Secret API key issued per institution. Send it on every request.

Request

Scholarship payload — see CreateScholarshipV1Request for field documentation.

scholarship_namestring or nullRequired

Human-readable name of the scholarship. Required, non-whitespace. Example: "Spring 2026 STEM Award".

scholarship_descriptionstring or nullRequired

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.".

award_cycle_idintegerRequired

AwardSpring award-cycle identifier this scholarship belongs to. Required. Example: 12.

application_start_datestring or nullRequired

ISO 8601 datetime when applicants can begin applying. Example: "2026-08-01T00:00:00". Interpreted in the tenant’s configured time zone.

application_end_datestring or nullRequired

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.

disbursement_datestring or nullRequired

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".

fund_idstring or nullOptional

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".

is_special_fundsbooleanOptional

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.

first_disbursement_term_namestring or nullOptional

Optional label for the first disbursement’s academic term, shown alongside the disbursement date. Maximum 50 characters. Example: "Spring 2027".

total_awards_numberinteger or nullOptional

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.

total_scholarship_valuedouble or nullOptional

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.

payments_per_awardinteger or nullOptional

Optional number of payments each recipient receives. Must be 1 or greater when supplied. Example: 2.

department_idinteger or nullOptional

Optional AwardSpring department ID the scholarship is owned by. Used for Department Admin scoping. Example: 3.

donor_idslist of integers or nullOptional

Optional list of donor or donor-organization user IDs associated with the scholarship. Example: [101, 102].

is_deactivate_scholarshipbooleanOptional

Whether the scholarship is deactivated on create (rare — typically left false). Example: false.

is_institutional_award_scholarshipbooleanOptional

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.

internal_notesstring or nullOptional

Optional internal notes for admin staff. Not shown to applicants. Example: "Cycle 2026 STEM partnership with ACME Corp.".

Response

Created
scholarship_idintegerOptional

AwardSpring-assigned identifier of the newly created scholarship (Opportunity.Id). Stable for the lifetime of the scholarship. Example: 1234.

Errors

400
Bad Request Error
403
Forbidden Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error