Implementation Session: Reading Benefits Data

Objectives

• Understand the Benefits endpoints and what data each returns

• Handle batch requests for /plans-enrollments and /plans-dependents

• Handle errors correctly, including per-item errors inside batch responses

Relevant Resources

• Benefits Product Overview

• Benefits Data Model

• Batch Requests

• Field Support

Notes

The typical read flow for Benefits data

Before this: call /directory to get the full list of individual_ids for your workforce. You can use those individual_ids to map enrollments to individuals.

Start with /plans — it returns the full list of plan_ids for your workforce and supports pagination. /plans-enrollments will show employees enrolled and their associated plan_ids to give you an enrollment_id and /plans-dependents will give dependent_ids.

Batch endpoints — always send all IDs in one request

Get Enrollments and Get Dependents are POST requests so they can accept a list of enrollment_ids or dependent_ids in a single POST request body and return a response array with one result per ID. Do not loop and make one request per ID — this will exhaust your rate limit quickly (20 req/min per endpoint across your entire application). Pass all IDs in a single call.

A 200 from a batch endpoint does not mean every record succeeded

Batch endpoints return 200 at the HTTP level even if individual records failed. Each item in the responses array has its own code field. Always check each item's code individually — a 404 or 500 inside the array means that specific record failed, even though the overall request was accepted.

Use the API Reference response schema — not the examples — to see all fields and enum values

The example responses in the API Reference show sample data, not the full set of possible values. For fields that return enums, refer to the response schema in the API Reference to see all valid options.

Use the Field Support matrix to determine which providers meet your requirements

Before finalizing which providers to support, check the Field Support matrix to confirm that the fields your application depends on are available for each provider. Currently, the Benefits endpoints are only live for ADP Workforce Now.