Filtering
Filtering allows you to narrow down the results returned by the API based on specific attributes. The filter parameter can be used with any attribute to return a subset of results.
Basic Filters:
Simple:
/api/v2/signups?filter[note]=my noteCase Sensitive:
/api/v2/signups?filter[note][eql]=My notePrefix:
/api/v2/signups?filter[note][prefix]=mySuffix:
/api/v2/signups?filter[note][suffix]=myContains:
/api/v2/signups?filter[note][match]=ot
Numeric Filters:
Greater than:
/api/v2/signups?filter[donations_amount_in_cents][gt]=500Greater than or equal to:
/api/v2/signups?filter[donations_amount_in_cents][gte]=500Less than:
/api/v2/signups?filter[donations_amount_in_cents][lt]=1000Less than or equal to:
/api/v2/signups?filter[donations_amount_in_cents][lte]=1000
Null Checks:
Exists (is not null):
/api/v2/signups?filter[middle_name][not_eq]=nullDoes not exist (is null):
/api/v2/signups?filter[middle_name]=null
Nested Filtering: You can also filter sideloaded resources by nesting filter parameters.
- /api/v2/signups?include=memberships&filter[memberships][status]=active
Important Note: The filter does not remove unassociated Signups from the response. Signups without an active membership will still be included in the payload.
Examples
Filter by Note:
GET /api/v2/signups?filter[note]=meeting
Filter by Donations Greater Than a Certain Amount:
GET /api/v2/signups?filter[donations_amount_in_cents][gt]=1000
Filter by Active Memberships:
GET /api/v2/signups?include=memberships&filter[memberships][status]=active
Pagination
By default, index endpoints return 20 results per response. The response includes self, prev, and next links for pagination.
Customizing Page Size and Number:
Specify size:
/api/v2/signups?page[size]=10Specify page:
/api/v2/signups?page[number]=3
Sparse Fields
To optimize data transfer, you can use the fields parameter to specify only the attributes you need in the response.
Example:
GET /api/v2/signups?fields[signups]=first_name,last_name,email
Sorting
The sort parameter allows you to order the results.
Ascending Order:
GET /api/v2/signups?sort=first_name
Descending Order:
GET /api/v2/signups?sort=-first_name
Sideloading
Sideloading enables you to include related resources in the same response. This is done using the include parameter.
Example:
GET /api/v2/signups?include=recruiter,taggings
Sideposting
Sideposting allows you to create or update a resource alongside a connected resource within the same request.
Creating a Signup with a Recruiter and Tags:
{ "data": { "type": "signups", "attributes": { "first_name": "Kim", "last_name": "Possible", "email": "[email protected]" }, "relationships": { "recruiter": { "data": { "type": "signups", "temp-id": "unique-temp-id", "method": "create" } }, "signup_tags": { "data": [ { "type": "signup_tags", "temp-id": "new-signup-tag", "method": "create" }, { "type": "signup_tags", "temp-id": "another-new-signup-tag", "method": "create" }, { "type": "signup_tags", "id": "123", "method": "update" } ] } } }, "included": [ { "type": "signups", "temp-id": "unique-temp-id", "attributes": { "first_name": "Joy", "last_name": "Palmer", "email": "[email protected]" } }, { "type": "signup_tags", "temp-id": "new-signup-tag", "attributes": { "name": "create-from-api-call" } }, { "type": "signup_tags", "temp-id": "another-new-signup-tag", "attributes": { "name": "api-recruited" } } ] }