Filtering with query parameters

Using URL query parameters to filter API responses is a common practice in web development, particularly when working with RESTful APIs. Query parameters allow clients to specify certain criteria for the data they are requesting, effectively filtering the response from the server based on these parameters. Here's a basic overview of how this works:

Understanding URL Query Parameters

  1. Structure of a URL with Query Parameters:
    • A typical URL with query parameters looks like this: https://example.com/api/items?param1=value1&param2=value2
    • Here, ?param1=value1&param2=value2 represents the query parameters.
    • param1 and param2 are the keys, and value1 and value2 are their respective values.
  2. Multiple Parameters:
    • Multiple query parameters are separated by the & symbol.

How They Are Used in APIs

  1. Filtering Data:
    • APIs can use these parameters to filter results. For instance, in a user API, you might use https://example.com/api/users?age=25 to get users who are 25 years old.
  2. Sorting and Pagination:
    • They can also be used for sorting (e.g., sort=age_asc) and pagination (e.g., page=2&limit=10).

Wingspan query parameters

Here's the table with the Wingspan recognized query parameters and their corresponding definitions:

Note: The '=' operator typically denotes equality, '!=' denotes inequality, and 'contains' checks if the field includes a specified substring.

Query ParameterDefinition
schema.filter('memberId', '=')Filters for records where memberId exactly matches a given value.
schema.filter('memberId', '!=')Filters for records where memberId does not match a given value.
schema.filter('clientId', '=')Filters for records where clientId exactly matches a given value.
schema.filter('clientId', '!=')Filters for records where clientId does not match a given value.
schema.filter('name', '=')Filters for records where name exactly matches a given value.
schema.filter('labels.createdBy', '=')Filters for records where labels.createdBy matches a given value.
schema.filter('labels.company', '=')Filters for records where labels.company matches a given value.
schema.filter('labels.company', 'in')Filters for records where labels.company is in a set of values.
schema.filter('labels.bulkBatchId', '=')Filters for records where labels.bulkBatchId matches a given value.
schema.filter('labels.bulkBatchId', 'in')Filters for records where labels.bulkBatchId is in a set of values.
schema.filter('name', 'contains')Filters for records where name contains a specified substring.
schema.filter('company', '=')Filters for records where company exactly matches a given value.
schema.filter('company', 'contains')Filters for records where company contains a specified substring.
schema.filter('emailTo', '=')Filters for records where emailTo exactly matches a given value.
schema.filter('emailTo', 'contains')Filters for records where emailTo contains a specified substring.
schema.filter('status', '=')Filters for records where status exactly matches a given value.
schema.filter('status', 'in')Filters for records where status is in a set of values.
schema.filter('member.user.email', 'in')Filters for records where member.user.email is in a set of values.
schema.filter('member.user.email', '=')Filters for records where member.user.email exactly matches a given value.
schema.filter('form1099Balances.2022.events.submittedForCollaboratorReviewAt', '=')Filters by exact match of the submission date for collaborator review.
schema.filter('form1099Balances.2022.events.submittedForCollaboratorReviewAt', 'in')Filters by a set of specified submission dates for collaborator review.
schema.filter('form1099Balances.2022.events.submittedForCollaboratorReviewAt', 'between')Filters for submission dates for collaborator review within a specific range.
schema.filter('form1099Balances.2022.events.submittedForCollaboratorReviewAt', '>')Filters for submission dates for collaborator review after a specified date.
schema.filter('form1099Balances.2022.events.submittedForCollaboratorReviewAt', '<')Filters for submission dates for collaborator review before a specified date.
schema.filter('form1099Balances.2022.events.submittedForCollaboratorReviewAt', '>=')Filters for submission dates for collaborator review on or after a specified date.
schema.filter('form1099Balances.2022.events.submittedForCollaboratorReviewAt', '<=')Filters for submission dates for collaborator review on or before a specified date.
schema.filter('form1099Balances.2022.events.submittedForCollaboratorReviewAt', '!=')Filters out a specific submission date for collaborator review.
schema.filter('form1099Balances.2022.deliveryMethod', '=')Filters by exact match of the delivery method for Form 1099.
schema.filter('form1099Balances.2022.deliveryMethod', 'in')Filters by a set of specified delivery methods for Form 1099.
schema.filter('formW9Data.name', '=')Filters for records where the 'name' in 'formW9Data' is equal to a specified value.
schema.filter('formW9Data.name', '!=')Filters for records where the 'name' in 'formW9Data' is not equal to a specified value.
schema.filter('formW9Data.name', 'contains')Filters for records where the 'name' in 'formW9Data' contains a specified substring.
schema.filter('formW9Data.businessName', '=')Filters for records where the 'businessName' in 'formW9Data' is equal to a specified value.
schema.filter('formW9Data.businessName', '!=')Filters for records where the 'businessName' in 'formW9Data' is not equal to a specified value.
schema.filter('formW9Data.businessName', 'contains')Filters for records where the 'businessName' in 'formW9Data' contains a specified substring.
schema.filter('formW9Data.addressLine1', '=')Filters for records where 'addressLine1' in 'formW9Data' is equal to a specified value.
schema.filter('formW9Data.addressLine1', '!=')Filters for records where 'addressLine1' in 'formW9Data' is not equal to a specified value.
schema.filter('formW9Data.addressLine1', 'contains')Filters for records where 'addressLine1' in 'formW9Data' contains a specified substring.
schema.filter('formW9Data.addressLine2', '=')Filters for records where 'addressLine2' in 'formW9Data' is equal to a specified value.
schema.filter('formW9Data.name', '=')Filters for records where the 'name' in 'formW9Data' is equal to a specified value.
schema.filter('formW9Data.name', '!=')Filters for records where the 'name' in 'formW9Data' is not equal to a specified value.
schema.filter('formW9Data.name', 'contains')Filters for records where the 'name' in 'formW9Data' contains a specified substring.
schema.filter('formW9Data.businessName', '=')Filters for records where the 'businessName' in 'formW9Data' is equal to a specified value.
schema.filter('formW9Data.businessName', '!=')Filters for records where the 'businessName' in 'formW9Data' is not equal to a specified value.
schema.filter('formW9Data.businessName', 'contains')Filters for records where the 'businessName' in 'formW9Data' contains a specified substring.
schema.filter('formW9Data.addressLine1', '=')Filters for records where 'addressLine1' in 'formW9Data' is equal to a specified value.
schema.filter('formW9Data.addressLine1', '!=')Filters for records where 'addressLine1' in 'formW9Data' is not equal to a specified value.
schema.filter('formW9Data.addressLine1', 'contains')Filters for records where 'addressLine1' in 'formW9Data' contains a specified substring.
schema.filter('formW9Data.addressLine2', '=')Filters for records where 'addressLine2' in 'formW9Data' is equal to a specified value.
schema.filter('formW9Data.addressLine2', '!=')Filters data where addressLine2 is not equal to a specified value
schema.filter('formW9Data.addressLine2', 'contains')Filters data where addressLine2 contains a specified substring
schema.filter('formW9Data.city', '=')Filters data where city is equal to a specified value
schema.filter('formW9Data.city', '!=')Filters data where city is not equal to a specified value
schema.filter('formW9Data.city', 'contains')Filters data where city contains a specified substring
schema.filter('formW9Data.state', '=')Filters data where state is equal to a specified value
schema.filter('formW9Data.state', '!=')Filters data where state is not equal to a specified value
schema.filter('formW9Data.state', 'contains')Filters data where state contains a specified substring
schema.filter('formW9Data.postalCode', '=')Filters data where postalCode is equal to a specified value
schema.filter('formW9Data.postalCode', '!=')Filters data where postalCode is not equal to a specified value
schema.filter('formW9Data.postalCode', 'contains')Filters by postal code, checking if it contains a specified value.
schema.filter('formW9Data.country', '=')Filters by country, checking for an exact match.
schema.filter('formW9Data.country', '!=')Filters by country, excluding those that match the specified value.
schema.filter('formW9Data.country', 'contains')Filters by country, checking if it contains a specified value.
schema.filter('formW9Data.ssn', '=')Filters by social security number (SSN), checking for an exact match.
schema.filter('formW9Data.ssn', '!=')Filters by SSN, excluding those that match the specified value.
schema.filter('formW9Data.ssn', 'contains')Filters by SSN, checking if it contains a specified value.
schema.filter('formW9Data.ein', '=')Filters by employer identification number (EIN), checking for an exact match.
schema.filter('formW9Data.ein', '!=')Filters by EIN, excluding those that match the specified value.
schema.filter('formW9Data.ein', 'contains')Filters records where EIN contains specified value
schema.filter('formW9Data.companyStructure', '=')Filters records where company structure is equal to specified value
schema.filter('formW9Data.companyStructure', '!=')Filters records where company structure is not equal to specified value
schema.filter('formW9Data.companyStructure', 'contains')Filters records where company structure contains specified value
schema.filter('taxStatus', '=')Filters records where tax status is equal to specified value
schema.filter('taxStatus', '!=')Filters records where tax status is not equal to specified value
schema.filter('clientData.externalId', '=')Filters records where client's external ID is equal to specified value
schema.filter('memberData.externalId', '=')Filters records where member's external ID is equal to specified value