> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.awardspring.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.awardspring.com/_mcp/server. # Create a scholarship. POST https://api.awardspring.com/api/v1/scholarships Content-Type: application/json 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). Reference: https://docs.awardspring.com/api-reference/scholarships/create ## Authentication - `X-Spring-API-Key` header (required) — Secret API key issued per institution. Send it on every request. ## Servers - `https://api.awardspring.com` (UnitedStates, default) - `https://api.awardspring.ca` (Canada) ## Request ### Body (application/json) This endpoint expects a CreateScholarshipV1Request. - `scholarship_name` (string, required, nullable) — Human-readable name of the scholarship. Required, non-whitespace. Example: `"Spring 2026 STEM Award"`. - `scholarship_description` (string, required, nullable) — 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_id` (string, required, nullable) — The stored ID of the award cycle this scholarship belongs to. Required. Example: `"4MZ8QW2TC"`. - `application_start_date` (string, required, nullable) — ISO 8601 datetime when applicants can begin applying. Example: `"2026-08-01T00:00:00"`. Interpreted in the tenant's configured time zone. - `application_end_date` (string, required, nullable) — 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_date` (string, required, nullable) — 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_id` (string, optional, nullable) — 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_funds` (boolean, optional) — 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_name` (string, optional, nullable) — Optional label for the first disbursement's academic term, shown alongside the disbursement date. Maximum 50 characters. Example: `"Spring 2027"`. - `total_awards_number` (integer, optional, nullable) — 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_value` (double, optional, nullable) — 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_award` (integer, optional, nullable) — 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`. - `payment_schedule_ids` (list of integer, optional, nullable) — 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]`. - `department_id` (string, optional, nullable) — Optional stored ID of the department the scholarship is owned by. Used for Department Admin scoping. Example: `"9TQ3HX7PD"`. - `donor_ids` (list of string, optional, nullable) — Optional list of the stored IDs of donors or donor organizations associated with the scholarship. Example: `["2KD7RW4MA", "8PX5NT3QF"]`. - `is_deactivate_scholarship` (boolean, optional) — Whether the scholarship is deactivated on create (rare — typically left `false`). Example: `false`. - `is_institutional_award_scholarship` (boolean, optional) — 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_notes` (string, optional, nullable) — Optional internal notes for admin staff. Not shown to applicants. Example: `"Cycle 2026 STEM partnership with ACME Corp."`. ## Response ### 201 Created - `scholarship_id` (string, optional, nullable) — 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"`. ## Errors ### 400 Bad Request Error Bad Request - `error` (V1ErrorBody, optional) — Stripe-shaped error object for the `/api/v1/*` surface. Serialized snake\_case (via V1SnakeCaseNamingStrategy) and always nested under the `error` key of a V1ErrorEnvelope: `{ "error": { "type": "...", "code": "...", "message": "...", "param": null, "doc_url": null, "recovery": "..." } }` ### 403 Forbidden Error Forbidden - `error` (V1ErrorBody, optional) — Stripe-shaped error object for the `/api/v1/*` surface. Serialized snake\_case (via V1SnakeCaseNamingStrategy) and always nested under the `error` key of a V1ErrorEnvelope: `{ "error": { "type": "...", "code": "...", "message": "...", "param": null, "doc_url": null, "recovery": "..." } }` ### 409 Conflict Error Conflict - `error` (V1ErrorBody, optional) — Stripe-shaped error object for the `/api/v1/*` surface. Serialized snake\_case (via V1SnakeCaseNamingStrategy) and always nested under the `error` key of a V1ErrorEnvelope: `{ "error": { "type": "...", "code": "...", "message": "...", "param": null, "doc_url": null, "recovery": "..." } }` ### 422 Unprocessable Entity Error Unprocessable Content - `error` (V1ErrorBody, optional) — Stripe-shaped error object for the `/api/v1/*` surface. Serialized snake\_case (via V1SnakeCaseNamingStrategy) and always nested under the `error` key of a V1ErrorEnvelope: `{ "error": { "type": "...", "code": "...", "message": "...", "param": null, "doc_url": null, "recovery": "..." } }` ### 429 Too Many Requests Error Rate limit exceeded for this API key. Retry after the interval in the `Retry-After` header. - `error` (V1ErrorBody, optional) — Stripe-shaped error object for the `/api/v1/*` surface. Serialized snake\_case (via V1SnakeCaseNamingStrategy) and always nested under the `error` key of a V1ErrorEnvelope: `{ "error": { "type": "...", "code": "...", "message": "...", "param": null, "doc_url": null, "recovery": "..." } }` ## Types ### V1ErrorBody Stripe-shaped error object for the `/api/v1/*` surface. Serialized snake\_case (via V1SnakeCaseNamingStrategy) and always nested under the `error` key of a V1ErrorEnvelope: `{ "error": { "type": "...", "code": "...", "message": "...", "param": null, "doc_url": null, "recovery": "..." } }` - `type` (string, optional, nullable) — Coarse error category from V1ErrorType (e.g. `invalid_request_error`). - `code` (string, optional, nullable) — Stable fine-grained machine code from ErrorCode (e.g. `donor_not_found`). - `message` (string, optional, nullable) — Human-readable summary safe to surface to the caller. - `param` (string, optional, nullable) — The request parameter the error relates to, when attributable to a single field; otherwise null. - `doc_url` (string, optional, nullable) — Link to documentation for this error, when one exists; otherwise null. - `recovery` (string, optional, nullable) — Plain-language guidance on how to recover from this error, suitable for showing to the person who triggered it. Not present on every error. - `details` (any, optional) — Optional structured payload (e.g. a list of ValidationDetail for validation failures). Omitted from the wire when null so the canonical Stripe shape stays minimal. ## Examples **Request** ```json { "scholarship_name": "string", "scholarship_description": "string", "award_cycle_id": "string", "application_start_date": "string", "application_end_date": "string", "disbursement_date": "string" } ``` **Response** ```json { "scholarship_id": "string" } ``` **SDK Code** ```python import requests url = "https://api.awardspring.com/api/v1/scholarships" payload = { "scholarship_name": "string", "scholarship_description": "string", "award_cycle_id": "string", "application_start_date": "string", "application_end_date": "string", "disbursement_date": "string" } headers = { "X-Spring-API-Key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.awardspring.com/api/v1/scholarships'; const options = { method: 'POST', headers: {'X-Spring-API-Key': '', 'Content-Type': 'application/json'}, body: '{"scholarship_name":"string","scholarship_description":"string","award_cycle_id":"string","application_start_date":"string","application_end_date":"string","disbursement_date":"string"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.awardspring.com/api/v1/scholarships" payload := strings.NewReader("{\n \"scholarship_name\": \"string\",\n \"scholarship_description\": \"string\",\n \"award_cycle_id\": \"string\",\n \"application_start_date\": \"string\",\n \"application_end_date\": \"string\",\n \"disbursement_date\": \"string\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-Spring-API-Key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.awardspring.com/api/v1/scholarships") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-Spring-API-Key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"scholarship_name\": \"string\",\n \"scholarship_description\": \"string\",\n \"award_cycle_id\": \"string\",\n \"application_start_date\": \"string\",\n \"application_end_date\": \"string\",\n \"disbursement_date\": \"string\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.awardspring.com/api/v1/scholarships") .header("X-Spring-API-Key", "") .header("Content-Type", "application/json") .body("{\n \"scholarship_name\": \"string\",\n \"scholarship_description\": \"string\",\n \"award_cycle_id\": \"string\",\n \"application_start_date\": \"string\",\n \"application_end_date\": \"string\",\n \"disbursement_date\": \"string\"\n}") .asString(); ``` ```php request('POST', 'https://api.awardspring.com/api/v1/scholarships', [ 'body' => '{ "scholarship_name": "string", "scholarship_description": "string", "award_cycle_id": "string", "application_start_date": "string", "application_end_date": "string", "disbursement_date": "string" }', 'headers' => [ 'Content-Type' => 'application/json', 'X-Spring-API-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.awardspring.com/api/v1/scholarships"); var request = new RestRequest(Method.POST); request.AddHeader("X-Spring-API-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"scholarship_name\": \"string\",\n \"scholarship_description\": \"string\",\n \"award_cycle_id\": \"string\",\n \"application_start_date\": \"string\",\n \"application_end_date\": \"string\",\n \"disbursement_date\": \"string\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-Spring-API-Key": "", "Content-Type": "application/json" ] let parameters = [ "scholarship_name": "string", "scholarship_description": "string", "award_cycle_id": "string", "application_start_date": "string", "application_end_date": "string", "disbursement_date": "string" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.awardspring.com/api/v1/scholarships")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```