> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uplift.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Filtering Athletes

> Learn how to use custom query parameters to filter API results based on specific attributes, and understand the expected behavior of the output.

### Using Custom Query Parameters

The API allows you to include additional query parameters to filter results based on specific attributes, such as `team`, `sport`, `coach`, or any other custom attributes defined in your organization’s data schema. These parameters enable you to narrow down the results to match your specific requirements.

> **Note**: If your organization did not standardize the naming conventions or data, mismatches may occur when filtering athletes. For example, `team` could be listed as `Team`, `team`, or other variations, and `xyz` could be represented inconsistently (e.g., `XYZ`, `xyz`, or `Xyz`). These discrepancies may lead to incorrect or missing results. Ensure consistent naming conventions for both attribute names and their values to improve filtering accuracy.

### Examples of Usage

Here are some examples to demonstrate how to use custom attributes effectively:

1. **Filter by a Single Attribute**\
   If you want to retrieve athletes who play a specific sport, use the `sport` parameter:
   ```bash theme={null}
   curl -X GET 'https://api.uplift.ai/v1/athletes?limit=100&sport=MLB' \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json'
   ```

2. **Filter by Multiple Attributes**\
   You can combine multiple attributes to refine your search further:
   ```bash theme={null}
   curl -X GET 'https://api.uplift.ai/v1/athletes?limit=100&sport=MLB&team=XYZ' \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json'
   ```

3. **Sorting Results**\
   Use the `sorted_by` parameter to organize the results by a specific field, such as `first_name`, `last_name`, or `date_of_birth`:
   ```bash theme={null}
   curl -X GET 'https://api.uplift.ai/v1/athletes?limit=100&sorted_by=last_name' \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json'
   ```

### Important Considerations

To ensure the best experience when using custom query parameters, keep the following in mind:

1. **Data Availability**:\
   Custom attributes must exist and be populated in your organization’s data schema. If an attribute is not defined or empty for some records, those records will be excluded from the filtered results.

2. **Case Sensitivity**:\
   Depending on the implementation, some attributes may be case-sensitive. For example, searching for `team=XYZ` may not return the same results as `team=xyz` or `team=Xyz`. Ensure you verify your data structure and consistently use the correct casing, such as uppercase, lowercase, or camel case, based on your data schema.

3. **Handling Unexpected Inputs**:\
   If an attribute value does not match any records, the response will return an empty array. Ensure attribute names and values are spelled correctly to avoid unexpected results.

4. **Combining Parameters**:\
   The API processes query parameters using logical AND. All conditions must match for a record to be included in the results.
   For example:
   ```
   ?sport=MLB&team=XYZ&sorted_by=last_name
   ```
   Only returns athletes who match all specified criteria.

5. **Debugging**:\
   To validate your queries, use smaller limit values (e.g., `limit=10`) and inspect the response payload to ensure the filtering criteria are applied correctly.