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

# IDs

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.

```json
{
  "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](/webhooks/events) 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](/errors) for the shape of the response.

A [dry run](/dry-runs) 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.