> For the complete documentation index, see [llms.txt](https://flapjax.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flapjax.gitbook.io/docs/rest-api/reference/people-events/filter-people.md).

# Filter People

## Filter people

> Filters people based on relationship attribute conditions. Returns a paginated list of people whose attributes match the provided filters.\
> \
> Attribute filters are passed as \*\*top-level keys\*\* in the request body. Any key that isn't a reserved pagination field (\`cursor\_configuration\`, \`sort\_direction\`) is treated as an attribute filter. At least one attribute filter must be provided or the request returns a 400 error.\
> \
> For example, to find all people where the \`company\` attribute equals \`"Acme Inc"\`, send \`{"company": "Acme Inc"}\` in the request body. You can combine multiple filters in a single request.<br>

```json
{"openapi":"3.0.3","info":{"title":"Listener API","version":"1.0.0"},"tags":[{"name":"filter-people"}],"servers":[{"url":"https://{domain}/v1","variables":{"domain":{"default":"your-domain","description":"Your deployment domain"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token with the required scope for the endpoint. Pass via the `Authorization: Bearer <token>` header.\n"}},"schemas":{"FilterRequest":{"type":"object","description":"Filter request body. Attribute filters are top-level keys — any key that isn't `cursor_configuration` or `sort_direction` is treated as a filter. At least one attribute filter must be provided.\n","properties":{"cursor_configuration":{"$ref":"#/components/schemas/CursorConfiguration"},"sort_direction":{"type":"string","description":"Sort order for results.","enum":["asc","desc"]}},"additionalProperties":{"description":"Attribute filter. The key is the attribute key and the value is the filter condition.\n"}},"CursorConfiguration":{"type":"object","description":"Cursor-based pagination configuration.","properties":{"size":{"type":"integer","description":"Number of results per page.","default":50},"after_id":{"type":"string","description":"ID from a previous response. When provided, results start after this ID.\n"}}},"PaginatedResponse":{"type":"object","description":"Response envelope containing a paginated list.","properties":{"status":{"type":"string","enum":["Success"]},"data":{"type":"object","properties":{"items":{"type":"array","description":"The page of results.","items":{"type":"object"}}}}}},"ErrorResponse":{"type":"object","description":"Standard error response envelope.","properties":{"error":{"type":"string","description":"Machine-readable error type. Use this for programmatic error handling.\n","enum":["operation_failed","failed_binding_json","invalid_json","invalid_parameter","not_found","duplicate_entry","rate_limit_exceeded"]},"errorstack":{"type":"object","nullable":true,"description":"Detailed error stack (only present for server errors)."}}}}},"paths":{"/people/filter":{"post":{"summary":"Filter people","operationId":"filterPeople","tags":["filter-people"],"description":"Filters people based on relationship attribute conditions. Returns a paginated list of people whose attributes match the provided filters.\n\nAttribute filters are passed as **top-level keys** in the request body. Any key that isn't a reserved pagination field (`cursor_configuration`, `sort_direction`) is treated as an attribute filter. At least one attribute filter must be provided or the request returns a 400 error.\n\nFor example, to find all people where the `company` attribute equals `\"Acme Inc\"`, send `{\"company\": \"Acme Inc\"}` in the request body. You can combine multiple filters in a single request.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterRequest"}}}},"responses":{"200":{"description":"Filtered list of people.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"400":{"description":"No filters provided or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```