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=primary_address,work_address,registered_address&filter[addresses][state]=MT
Important Note: The filter does not remove unassociated Signups from the response. Signups that do not have addresses matching the criteria of the filter 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 Address State:
GET /api/v2/signups?include=primary_address&filter[addresses][state]=CA
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=primary_address,work_address
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" } } ] }