IDs | AwardSpring API

Every record ID the API returns is a string of 9 characters, made from the digits 2 to 9 and the capital letters A to Z without I, L and O. There is no prefix.

{
  "id": "7HQ2KW9XR",
  "user_id": "4MZ8RT2PW",
  "scholarship_id": "9AB3CD4EF",
  "award_cycle_id": "C7RJ3M9QV"
}

Treat an ID as opaque text. Store it as text, compare the whole value, and pass it back exactly as you received it, in a path, a query parameter or a request body. Do not read meaning into it, shorten it, or build one yourself. Lower-case letters and spaces around the value are forgiven, but there is no reason to send anything other than what you were given.

An ID never changes. A record keeps its ID for as long as it exists, including after it is archived or deactivated, so an ID you stored last year still names the same record.

Different kinds of records never share an ID. An ID taken from one endpoint will not accidentally match a different kind of record on another.

Where IDs appear

Field	What it names
`id`	The record the object describes: a donor, gift, activity, scholarship, award cycle, fund, department, student, application, award or person
`user_id`, `donor_id`, `assigned_to_user_id`	A person: a student, a donor or donor organization, or a staff member
`scholarship_id`	A scholarship
`award_cycle_id`	An award cycle
`campaign_id`	A campaign
`department_id`	A department

An award has the same id as the application it was awarded on. The award’s own 8-character code, the one your institution sees on award letters, is the separate award_code field, and it may be empty on awards made before codes were issued.

Webhooks carry the same IDs as the REST API, so you can pass an ID from an event straight back to an endpoint. A webhook’s tenant_id is your institution’s ID, in the same 9-character form. Event types lists which field carries which.

Values your institution owns

Not every field whose name ends in _id is an AwardSpring ID. Values your institution owns are plain text, exactly as your institution entered them:

Field	What it holds
`student_id`	The student number your institution assigned. It is not guaranteed to be unique.
`fund_id`	Your institution’s code for a fund. A fund’s AwardSpring ID is its `id`.

Payment schedules use numbers

Payment schedules do not have a 9-character ID yet. A payment schedule’s id, and the payment_schedule_ids you send when you create a scholarship, are whole numbers, exactly as the payment schedules endpoint returns them.

When an ID names nothing

An ID that is not one of your institution’s records is treated as a record that does not exist. That covers an ID from another institution, a value in the wrong form, and the whole-number IDs older versions of this API used.

Where the ID was	Result
In the address, such as `/api/v1/donors/{id}`	`404` with that record’s not-found code, such as `donor_not_found`. `param` names the part of the address that held it.
In a query filter, such as `award_cycle_id`	The same answer the filter gives for a record that does not exist: the record’s not-found code naming the filter, or, on a filter that only narrows a list, an empty list.
In a request body	`400 validation_failed`, with `param` naming the field. One exception: `donor_id` on a new gift is `404 donor_not_found`, with `param` naming `donor_id`.

See Errors for the shape of the response.

A dry run of a create returns "id": null, because nothing was saved and no ID was assigned.

Older endpoints keep integer IDs

This documentation covers the endpoints whose address starts with /api/v1/. AwardSpring also has older endpoints whose address has no version in it. They are not part of this reference, and they still use whole-number IDs. A whole number sent to a /api/v1/ endpoint as an ID names no record.