Related Product: People
Is your feature request related to a problem? Please describe.
Working programmatically with the People list engine is blocked at two levels that we discovered together during the same investigation:
Level 1 — No write access to lists or rules at all.
POST /people/v2/lists returns 403 Forbidden. The resource schema on list rules and conditions explicitly sets can_create: false, can_update: false, can_destroy: false. There is no API path to create a list or add/modify a rule programmatically.
Level 2 — No schema discovery endpoint for condition types.
Even if write access existed, there is no way to know what values are valid. Endpoints like GET /people/v2/lists/condition_definitions and /condition_types return 404. The condition type registry — what definition_class values exist, what comparison operators each supports, what the settings object structure looks like — is entirely opaque to the API.
Together, these mean the list engine is effectively a black box: you can read lists that already exist, but you cannot build, validate, or introspect the schema for new ones. This was filed previously as #1446 (condition discovery, added to the board) and #1435 (list CRUD, closed without plans). We're raising it again because the same investigation produced new concrete evidence about both issues simultaneously, and because the two gaps reinforce each other.
Describe the solution you'd like.
Two requests, in priority order:
Primary ask (narrower, more achievable): Add a read-only schema discovery endpoint for list condition types:
GET /people/v2/lists/condition_options
Response should enumerate all valid definition_class values (e.g. PersonFieldCondition, WorkflowCardCondition, BackgroundCheckCondition), the comparison operators each supports (e.g. is, is_not, is_greater_than, etc.), and the structure of any settings fields required. This endpoint requires no write access — it is purely documentation exposed as data.
This is directly analogous to the precedent set by the membership_types endpoint (#1424, resolved): a configuration schema that existed internally was made public after a feature request. The list condition schema already exists in the UI — the People app's list builder uses it client-side. Making it accessible as a stable API endpoint solves the discovery problem permanently without requiring any change to the write access model.
Secondary ask (larger scope): Expose CRUD on lists and rules:
POST /people/v2/lists — create a listPOST /people/v2/lists/{id}/rules — add a rule with conditionsPATCH /people/v2/lists/{id}/rules/{id} — update a ruleDELETE /people/v2/lists/{id}/rules/{id} — remove a rule
This would allow programmatic use of the People filtering engine without replicating it externally — the most powerful version of the feature, and the subject of #1435.
Describe alternatives you've considered.
The current workaround for condition discovery is to reverse-engineer the schema by reading conditions off every existing list in the organization, then inferring what's possible from what's already been used. After running this across all 75 Winepress lists (215 conditions total), we identified 31 unique condition types.
This approach has serious gaps:
- It only surfaces condition types already used in our organization — types we've never built a list for are invisible (e.g. Background Check conditions do not appear in any of our 75 lists, so we have no data on their
definition_class, valid comparisons, or settings shape)
- It reveals nothing about valid values for
settings fields — only the exact settings used in our existing conditions, which may not be exhaustive
- It is completely blind to new condition types added in future PCO updates — we would only discover them by noticing a new UI option and manually building a test list
- It cannot be done at all by developers who are starting from scratch with an empty PCO instance
There is no workaround for the write access issue. Lists and rules cannot be created via the API by any means.
Additional context
This was discovered while building a tool to programmatically audit and validate list filter logic across a growing PCO instance (Winepress Church, ~930 people, 75 lists). The immediate motivation was attempting to enumerate all valid condition types by creating a test list — which failed on the first call (POST /lists → 403).
The condition discovery gap (primary ask) also has a forward-looking AI relevance: any AI-assisted list creation workflow — including PCO's own UI AI features — would benefit from being able to read the available condition schema programmatically. Knowing what's structurally possible is a prerequisite to suggesting or validating filter logic.
Related prior issues on this repo:
The membership_types resolution (#1424) is a useful precedent: a private configuration endpoint was made public after a similar request. The list condition schema would be a natural candidate for the same treatment.
Completion checklist:
Related Product: People
Is your feature request related to a problem? Please describe.
Working programmatically with the People list engine is blocked at two levels that we discovered together during the same investigation:
Level 1 — No write access to lists or rules at all.
POST /people/v2/listsreturns403 Forbidden. The resource schema on list rules and conditions explicitly setscan_create: false, can_update: false, can_destroy: false. There is no API path to create a list or add/modify a rule programmatically.Level 2 — No schema discovery endpoint for condition types.
Even if write access existed, there is no way to know what values are valid. Endpoints like
GET /people/v2/lists/condition_definitionsand/condition_typesreturn404. The condition type registry — whatdefinition_classvalues exist, whatcomparisonoperators each supports, what thesettingsobject structure looks like — is entirely opaque to the API.Together, these mean the list engine is effectively a black box: you can read lists that already exist, but you cannot build, validate, or introspect the schema for new ones. This was filed previously as #1446 (condition discovery, added to the board) and #1435 (list CRUD, closed without plans). We're raising it again because the same investigation produced new concrete evidence about both issues simultaneously, and because the two gaps reinforce each other.
Describe the solution you'd like.
Two requests, in priority order:
Primary ask (narrower, more achievable): Add a read-only schema discovery endpoint for list condition types:
Response should enumerate all valid
definition_classvalues (e.g.PersonFieldCondition,WorkflowCardCondition,BackgroundCheckCondition), thecomparisonoperators each supports (e.g.is,is_not,is_greater_than, etc.), and the structure of anysettingsfields required. This endpoint requires no write access — it is purely documentation exposed as data.This is directly analogous to the precedent set by the
membership_typesendpoint (#1424, resolved): a configuration schema that existed internally was made public after a feature request. The list condition schema already exists in the UI — the People app's list builder uses it client-side. Making it accessible as a stable API endpoint solves the discovery problem permanently without requiring any change to the write access model.Secondary ask (larger scope): Expose CRUD on lists and rules:
POST /people/v2/lists— create a listPOST /people/v2/lists/{id}/rules— add a rule with conditionsPATCH /people/v2/lists/{id}/rules/{id}— update a ruleDELETE /people/v2/lists/{id}/rules/{id}— remove a ruleThis would allow programmatic use of the People filtering engine without replicating it externally — the most powerful version of the feature, and the subject of #1435.
Describe alternatives you've considered.
The current workaround for condition discovery is to reverse-engineer the schema by reading conditions off every existing list in the organization, then inferring what's possible from what's already been used. After running this across all 75 Winepress lists (215 conditions total), we identified 31 unique condition types.
This approach has serious gaps:
definition_class, valid comparisons, orsettingsshape)settingsfields — only the exact settings used in our existing conditions, which may not be exhaustiveThere is no workaround for the write access issue. Lists and rules cannot be created via the API by any means.
Additional context
This was discovered while building a tool to programmatically audit and validate list filter logic across a growing PCO instance (Winepress Church, ~930 people, 75 lists). The immediate motivation was attempting to enumerate all valid condition types by creating a test list — which failed on the first call (
POST /lists→403).The condition discovery gap (primary ask) also has a forward-looking AI relevance: any AI-assisted list creation workflow — including PCO's own UI AI features — would benefit from being able to read the available condition schema programmatically. Knowing what's structurally possible is a prerequisite to suggesting or validating filter logic.
Related prior issues on this repo:
The
membership_typesresolution (#1424) is a useful precedent: a private configuration endpoint was made public after a similar request. The list condition schema would be a natural candidate for the same treatment.Completion checklist: