People: expose list membership change history (per-person adds/removes over time)

[michaelhvisser]

Related Product

People

Is your feature request related to a problem? Please describe.

The People API can tell me who is on a list right now, but not how that list
changed over time. /people/v2/lists/{id}/list_results is a point-in-time
snapshot, and total_people + refreshed_at is a single current number.

That makes three very common church questions impossible to answer from the API:

• How has this list grown or shrunk over the last 6 / 12 months?
• Who joined this list since last week, and who dropped off?
• Someone just landed on this list — who do I hand them to for follow-up?

Lists are where churches encode the things they actually care about: first-time
guests, lapsed attenders, inactive givers, people ready for the next step. The
membership of those lists changing is the ministry signal, and today that
signal isn't retrievable.

Describe the solution you'd like

A read-only endpoint under People that exposes per-person list membership
changes. Something like:

GET /people/v2/lists/{list_id}/membership_changes

and/or an org-wide GET /people/v2/list_membership_changes

Each record would carry:

• person_id
• list_id
• action — entered or left
• occurred_at (or the date of the refresh the change belongs to)

With standard JSON:API conventions: pagination, order, and where[] filtering
on list and date range, plus include=person. Readable with the existing People
scope.

Historical backfill would make this dramatically more useful than
subscribe-from-today — a church connecting an integration on day one should be
able to chart the last year, not start accumulating from scratch.

Secondary ask, if per-person change records aren't something that can be
exposed: a per-list count history — date plus result count for each refresh.
That would at least make trend reporting possible, though it can't support a
join/leave feed or any follow-up trigger.

Describe alternatives you've considered

1. Polling list_results and diffing client-side. This is what I'd have to
   do, and it works, but it means every integrator independently rebuilds the
   same snapshot store. For orgs with hundreds of lists it's an expensive way to
   spend the rate limit, it only produces history from the day the church
   connects, and it misses anything that happens between polls. ListResult
   created_at also appears to reset when a list refreshes, so it can't stand in
   for a join date.

2. The existing people.v2.events.list_result.created /
   .destroyed webhooks. These are the closest existing thing and they're
   useful, but they don't cover the need: there's no way to subscribe per list,
   so an integration receives every membership change for every list in the org
   and filters on its own end — which during nightly refresh windows is a very
   large burst for big accounts. There's also no backfill and no reconciliation
   path, so any delivery failure or lapsed subscription leaves a permanent hole
   in the record with no way to detect or repair it. And they do nothing for
   reporting on the past.

3. Snapshotting total_people on a schedule. Gives a count trend and nothing
   else — five people in and five out looks identical to no change, so it can't
   drive a feed or a trigger.

Additional context

I build Parable, an analytics and workflow platform for churches running
Planning Center. "Show me this list over time" is the single most requested
thing I hear, and it's the one I currently have to say no to.

The same data would also serve follow-up automation for teams whose workflow
lives outside Planning Center — when someone lands on the "visited twice, no
next step" list, route them to a person. Read-only change history is enough for
all of it; no writes needed.

Happy to test against a preview or give feedback on a proposed shape.

I have..

• Reviewed the documentation found at https://developer.planning.center/docs
• Searched for previous issues asking for this feature request
• Removed all private information from this issue (credentials, tokens, emails, phone numbers, etc.)
• Reviewed my issue for completeness