More efficient way to retrieve service schedule plan times

[aberamseyer]

Related Product
Which product is this feature related to?
Services

Is your feature request related to a problem? Please describe.
Finally getting around to creating this issue as directed a few months ago here.

Primary problem: retrieving every date of service for every person in any service schedule requires thousands of API requests.

We want understand "who is regularly serving". We have a sync process that runs for many data points, and the service schedule portion is by far the slowest. Today, this requires an API request per person, which can easily be in the thousands and make our sync take hours.

Today, our approach is:

1. Page through services/v2/teams?include=people in its entirety, every time, and collect all the person_ids from it.
2. Page through services/v2/people/<person_id>/schedules?include=plan_times&filter=after&after=<last_sync_time> for every person_id from the v2/teams response

Describe the solution you'd like
We would love to have an endpoint to retrieve all the service schedules for all people, particularly ordered by last update date (descending) so we can page through the API until we reach the date since our last synchronization. Maybe services/v2/schedules?include=plan_times? We're open to suggestions.

Our current implementation uses the following data points from services/v2/people/<person_id>/schedules

1. schedule.attributes.service_type_name
2. schedule.attributes.status
3. schedule.relationships.team.data.id
4. schedule.relationships.plan_times[*].attributes.starts_at

All from https://developer.planning.center/docs/#/apps/services/2018-11-01/vertices/schedule

Additional context

We also want to track team assignments, so we'll continue to use services/v2/teams?include=people for that regardless.

We always track the last time our api batches run, so ordering by an updated_at, descending is sufficient for us to know what has changed. We stop paging through the API when we reach updated_at values before the time of our last sync.

We're not currently in a position to set up a webhooks consumer for services changes, but that may work in the future. However, I don't think the currently available subscriptions include the data we're looking for.

Overall, we're just looking to reduce our API footprint to make things faster because we know we're causing a lot of load.

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

[github-actions]

Potentially Related Issues

I found some existing issues that may be related to this one. Please check if any of them address your question before waiting for a response:

🟣 #1428 — Internal Server Error 500 - reading large number of people. (Closed)

Summary: User experienced 500 Internal Server Error when fetching large numbers of people (30,000+) from the People API at around the 5,200 person mark. The issue was resolved as a temporary incident during a specific 15-minute window.

Key discussion points:

• User was paginating through 30,000+ people records in batches of 50-100 with delays between requests
• Error occurred around offset 5,200, but was traced to a specific incident window (7:05-7:20am Pacific on that day)
• CSV export was suggested as an alternative viable option for large datasets
• Retry logic with delays was implemented to handle 429 and 500 errors gracefully

Resolution: The 500 errors were caused by a temporary incident during a specific 15-minute window. After that incident was resolved, the import completed successfully. Planning Center confirmed CSV export is a viable alternative for large datasets (30,000+ records).

🟣 #1400 — Rate limit guidance for large-scale donation migration 100k+ records (Closed)

Summary: User needed to migrate 100k+ historical donation records but was limited to single donation POST requests, causing bottlenecks even with caching. This directly parallels the new issue's concern about inefficient person-by-person API requests.

Key discussion points:

• No bulk import endpoint exists for donations; each record requires individual API call
• Community member successfully migrated 30k records using 50 calls per 5 seconds with person ID caching
• Best practices include: caching everything locally, using background workers, implementing smart rate limit handling with Retry-After headers, and keeping batch sizes small
• Even with optimizations, 100k record migrations take several days

Resolution: Planning Center confirmed no bulk donation creation is available and no immediate plans to add it. The recommended approach is to implement proper rate limiting (respecting Retry-After headers), aggressive local caching of person IDs, and acceptance that large-scale migrations take days. This is relevant to the new issue as it confirms Planning Center's general stance on bulk operations.

🟣 #1368 — Bulk API songs import question (Closed)

Summary: User developing a lyrics management app asked about bulk song creation via API, facing the same pattern of needing to loop through individual POST requests for multiple items.

Key discussion points:

• No bulk creation endpoint exists for songs; must loop through individual POST requests
• Suggested using concurrency (2-3 simultaneous requests) while respecting rate limits
• Rate limiting documentation was referenced as key consideration

Resolution: Planning Center confirmed no plans to add bulk song creation functionality. Individual looped requests are acceptable as long as rate limits are respected. This establishes a pattern that Planning Center generally doesn't support bulk creation endpoints across their API.

🟣 #1351 — Guest Service Registration (Closed)

Summary: User couldn't find Guest service schedules in API responses and was using an inefficient approach of polling all teams and then querying each person individually - very similar to the new issue's current implementation.

Key discussion points:

• User was iterating through all teams via services/v2/teams and then calling services/v2/people/{person_id}/schedules for every person - identical to new issue's approach
• Both /plan_people and /schedules edges only return future results unless before/past filters are used
• Webhooks (services.v2.events.plan.updated) were suggested as alternative to polling every team and person
• Webhook approach eliminates need to request every team and every person when only a few have changed

Resolution: The guest scheduling issue was resolved (uncheck a box or send email). More importantly for the new issue, Planning Center suggested using webhooks to subscribe to plan changes instead of polling all teams and people. This is the exact optimization strategy that could help the new issue reduce their thousands of API requests.

🟣 #1262 — Include Blockout Dates and PlanPerson Data in People API Endpoint (Closed)

Summary: User requested the ability to include blockout_dates and plan_people data directly in the /services/v2/people endpoint to avoid making separate requests per person, citing rate limit concerns with large teams - nearly identical to the new issue's request.

Key discussion points:

• Currently requires separate API requests per person to get blockout dates and plan person data
• Inefficient process leads to rate limit issues, especially for large organizations
• Requested include=blockout_dates,plan_people parameter support on people endpoint
• Use case involved automated team scheduling and planning workflows with large teams

Resolution: Planning Center acknowledged the value and added the request to their internal tracking system for future consideration, but provided no timeline or commitment. This is highly relevant as it shows Planning Center is aware of similar efficiency concerns but hasn't yet implemented solutions.

---

This comment was generated automatically. If none of these match your issue, no action is needed — a team member will review your issue soon.

[modille]

@aberamseyer Sorry for the delay here!

It sounds like you're essentially making N schedule requests, where N is the number of People. Besides being a large number of network requests, like you said, I suspect that might result in a lot of empty responses, which could contribute to the overall slowness of your sync process.

With the existing APIs, the way I would approach that would be to instead list all service types, then for each service type get the plans since your last sync time, then for each of those plans get its PlanPeople. Then you're 1) making M+N requests, where M is the number of service types and N is the number of plans with times in your sync window (likely way less than the number of people), and 2) avoiding API requests that will be empty responses.

On top of that, a great way to reduce response latency for all of your API requests is to use JSON:API sparse fieldsets (essentially just telling us about those 4 particular fields you need -- service type name, plan person status, team ID, plan time starts_at).

Here's an example:

1. List service types, including just ID and name fields: GET /services/v2/service_types?fields[ServiceType]=name
2. For each service type, get plans with plan times since last sync time, including just plan time starts_at GET /services/v2/service_types/<id>/plans?include=plan_times&filter=after&after=<last_sync_time>&fields[Plan]=dates&fields[PlanTime]=starts_at
3. For each plan, get PlanPeople, including just status and team ID GET /services/v2/service_types/<id>/plans/<id>/team_members?include=team&fields[PlanPerson]=status,team

Or breaking those query params out:

• GET /services/v2/service_types
  • fields[ServiceType]=name
• GET /services/v2/service_types/<id>/plans
  • include=plan_times
  • filter=after
  • after=<last_sync_time>
  • fields[Plan]=dates
  • fields[PlanTime]=starts_at
• GET /services/v2/service_types/<id>/plans/<id>/team_members
  • include=team
  • fields[PlanPerson]=status,team

Can you try that out and see if it would meet your needs and speed up your sync process?

I'll close this issue for now, but if you have any additional needs that the current API doesn't meet or if you try out the new approach and run into any issues then feel free to comment back here and I'll be glad to reopen and take another look!