List donors.
Returns one page at a time. With no sort and no q, donors are listed by
id, lowest first.
Sort with sort. name lists donors A to Z, ignoring case: an organization by its
organization name, and a person by last name, then first name. A person with no last name
is listed by first name, and a donor with no name at all comes last. last_contacted
lists the most recently contacted donors first, by last_contacted_at; donors who
have never been contacted come last. Donors who tie are listed by id: lowest first
for name, highest first for last_contacted.
Narrow the list with level to donors at one or more levels, for example
level=major,principal. A donor’s level comes from their giving, so a request made as
a signed-in user who may not see donors’ giving returns 403 permission_denied when
it filters by level. Sorting is open to everyone who can list donors.
Narrow the list with giving_status to donors with one or more giving statuses, for
example giving_status=recurring,new. Recurring: the donor has a recurring gift
that is still running (not cancelled or stopped, and not past its end date) and at least one
payment from it has gone through. New: the donor’s first gift was in the last 12
months. Lapsed: the donor’s last gift was more than 12 months ago. The 12 months count
back from now, not from the start of a fiscal year. A donor who fits more than one takes the
first of Recurring, New, Lapsed. A donor who has never given has no giving
status, and neither does one whose first gift was more than 12 months ago and who has given
again within the last 12 months. With level as well, a donor must match both. A
request made as a signed-in user who may not see donors’ giving returns
403 permission_denied when it filters by giving status.
Search with q (at least 2 characters). Every word you type must match the
start of a word in the donor’s first name, last name or organization, or the start of
their email address, so jane smi finds Jane Smith. Matches inside a word are not
found: co finds Coworking but not Waco. Where digits and letters
touch, a word is also split there, so 25co finds 25N Coworking.
Without sort, search results come in three groups: first, donors whose full name or
organization starts with the search (for a search with no spaces, compared with the spaces
taken out, so janesmith finds Jane Smith); next, donors where every word starts a
word in their name or organization; last, donors matched only through their email address.
Within a group, donors are listed by id, lowest first, so the order holds from one
page to the next. With sort, the search only decides which donors are listed and
the sort decides their order.
sort, level, giving_status and q work together. Send the same ones
on every page: a cursor sent with a different sort, level, giving_status
or q returns 400 invalid_cursor. A search shorter than 2 characters, or an
unknown level, giving_status or sort, returns 400 validation_failed
with param set to the parameter at fault.
Assistant capability: springiq_list_donors. Required permission: Donors (applies when called on behalf of a signed-in person).
Authentication
Query parameters
Search text (?q=), at least 2 characters; a shorter search returns
400 validation_failed. Each word must match the start of a word in the donor’s first
name, last name or organization, or the start of their email address, ignoring case:
co finds Coworking and cole@school.edu but not Waco. Where digits
and letters touch, a word is also split there, so 25co searches as 25 co. A
search with no spaces also matches the start of the full name or organization with its
spaces taken out, so janesmith finds Jane Smith. Leave it out to list every donor.
Only donors at these levels (?level=): Annual, Mid, Major or
Principal, the values of the donor’s level field, in any case. Send several
comma-separated (level=major,principal) or repeat the parameter; a donor at any of
them is listed. Any other value returns 400 validation_failed. Level is worked out
from giving, so a signed-in user who may not see donors’ giving gets
403 permission_denied. Leave it out for every level.
Only donors with these giving statuses (?giving_status=): Recurring, New
or Lapsed, the values of the donor’s giving_status field, in any case. Send
several comma-separated (giving_status=recurring,new) or repeat the parameter; a donor
with any of them is listed. With level as well, a donor must match both. Any other
value returns 400 validation_failed. Giving status is worked out from giving, so a
signed-in user who may not see donors’ giving gets 403 permission_denied. Leave it
out for every donor, including those with no giving status.
The order to list donors in (?sort=): name or last_contacted. Leave it
out for the default order. Any other value returns 400 validation_failed.
Page size. Defaults to 25. Values outside 1–100 are clamped rather than rejected.
Opaque cursor. Pass the next_cursor from the previous page to page forward. Mutually exclusive with ending_before; if both are supplied, starting_after wins.
Opaque cursor. Pass the previous_cursor from the current page to page backward.
Optional extras to add to the response, comma-separated. total_count is the only supported value: it adds total_count, the number of records that match this request across all pages. The count is taken fresh at the moment of each request, so it can change while you page; ask for it on the first page. Without it, total_count is left out of the response. Asking or not never invalidates a cursor. Any other value returns 400 validation_failed.
Response
Discriminator constant. Always "list", mirroring Stripe’s list objects.
The request path this collection was served from (e.g. /api/v1/scholarships).
Opaque cursor for the next page (pass as starting_after). Null when there is none.
Opaque cursor for the previous page (pass as ending_before). Null when there is none.
The number of records that match the request across all pages, counted fresh on each
request. Present only when the request includes include=total_count; otherwise the
key is omitted.