Getting API Shift Select Atrium Health Working in Practice
I spent about three weeks getting the ShiftSelect API integration working with Atrium Health's cancer care scheduling pipeline. It wasn't straightforward. The documentation exists but it assumes you already know a fair amount about their auth flow and payload structure. Here is what actually happened and how I got it to function without burning a week on retry loops. The core idea behind the API Shift Select Atrium Health integration is automating nurse-to-patient matching in oncology units. Instead of a scheduling coordinator manually pulling from a spreadsheet and cross-referencing certifications, the API checks ShiftSelect in real time, verifies active credentials, and pushes the assignment into Atrium's internal system. For cancer care specifically this matters because oncology nurses need current BLS, chemo certification, and sometimes specific competency stamps that expire on different cycles. Manual tracking misses things. The API catches them before a schedule publishes. The foundation is their OAuth 2.0 flow. You start by registering your application in the ShiftSelect partner portal. You get a client ID and secret. From there you request an access token with a POST to their token endpoint. The token expires every hour. Do not cache it for longer than 55 minutes or you will start seeing 401 errors at 3 AM when your cron job runs and nobody is awake to fix it.
The payload structure is the first place people trip up. ShiftSelect expects a very specific JSON format for employee queries. If you send extra fields or nest things where they do not expect nesting, the endpoint silently drops those fields instead of throwing an error. I learned this the hard way when I included an "employee_type" field that the endpoint ignored, then spent two hours wondering why all my results came back empty. The workaround was stripping the request down to only the documented required fields and adding one optional field at a time until I confirmed what they actually accept. Here is the authentication sequence that works: POST to https://api.shiftselect.com/oauth/token with grant_type=client_credentials. Include your client_id and client_secret in the body. Set the Content-Type header to application/x-www-form-urlencoded. Parse the response for the access_token value. Store it with an expiry timestamp.
For the cancer care integration specifically, the critical endpoint is /api/v1/scheduling/employees. This is where you pull the credential data. The response includes certification_expiry dates, license status, and shift availability. What the docs do not make clear is that chemo certification shows up under a different field code than basic nursing credentials. I had to inspect the raw response and noticed the field was nested inside a certifications object with a type identifier. Without that detail you would just see an empty array and assume nobody was certified. The real integration challenge comes with the Atrium Health side. Once you have the employee data from ShiftSelect, you need to push qualified candidates into Atrium's scheduling system for the oncology unit. This typically goes through Atrium's own API or sometimes a middleware layer depending on which hospital campus you are dealing with. Charlotte behaves differently from Concord. I found that the API endpoints for credential verification differ slightly between campuses. One campus returns a full object with all certifications while the other returns a truncated summary that omits expiration dates. You need to handle both response shapes or your automation will silently publish schedules with expired credentials. The automation logic I ended up writing checks three things before an assignment goes out: does the nurse have an active chemo certification, is their BLS current, and do they have unscheduled hours available that week. All three come from the same /api/v1/scheduling/employees call. If any check fails, the API routes that nurse out of the pool for oncology assignments. The whole verification takes about 200 milliseconds per nurse. A typical oncology unit with 30 assigned nurses takes under 7 seconds to run the full check.
Get the Full Details
There is a known edge case with travel nurses and per diem staff. Their credentials appear in ShiftSelect but the certification dates sometimes reflect their agency records rather than Atrium's internal validation. I ran into this when a nurse showed a valid chemo certification with a 2027 expiry date but Atrium's system had flagged her as expired two weeks prior. The mismatch happened because the travel agency had submitted an outdated credential packet. The workaround was to run a secondary check against Atrium's own credential API endpoint after the ShiftSelect query. If the two dates disagree by more than 30 days, flag the assignment for manual review rather than auto-approving or auto-rejecting. This added about 400 milliseconds per edge-case nurse but prevented two credential violations in the first month of go-live. Rate limiting is another thing the documentation buries. ShiftSelect allows 100 requests per minute on the standard tier. If you are pushing a full week of oncology schedules with 60 nurses, you can stay under that limit. But if you run a validation sweep every 5 minutes during a staffing crisis like I did, you will hit the ceiling by 11 AM. When you hit the limit the API returns a 429 with a Retry-After header. The correct response is to back off and retry with exponential delay. I wrote a simple wrapper that catches 429s, reads the Retry-After value, sleeps for 1.5 times that duration, and retries up to three times. Any more than that and you just queue the request for the next cycle. The biggest pitfall I encountered was around timezone handling. ShiftSelect stores timestamps in UTC. Atrium Health stores them in Eastern Time with no explicit timezone marker. When I first wired the integration, assignments published with shifted timeframes. A nurse scheduled for a 7 PM shift in Charlotte was showing up as scheduled for 2 AM because the UTC conversion happened twice. The fix was to explicitly parse the ShiftSelect response with .utc() and convert to Eastern only at the point of insertion into Atrium's system, never before.
Another counter-intuitive thing: the API does not validate nurse-patient ratios in real time. It only stores and returns the data you ask for. So even though the ShiftSelect system tracks how many patients each nurse has, the API endpoint for employee lookups does not include a current patient count field. You have to query a separate endpoint for workload data and merge the results yourself. I combined the two queries with a simple join on employee ID and used the merged result for the assignment logic. This added one extra API call per nurse but gave me the complete picture the scheduling system actually needed. If you are building this from scratch, the best approach is to start with a read-only connection. Pull employee data first. Confirm the payload shapes match what you expect. Then add the write path for pushing assignments. Skipping the read-only phase will cost you more time than you save. I watched two colleagues try to go straight to the assignment endpoint and spend four days debugging authentication issues that were actually caused by passing test employee IDs that do not exist in the production environment. The integration also requires a webhook listener if you want real-time updates. ShiftSelect supports webhooks for schedule changes and credential updates. Setting this up means exposing a public endpoint that accepts POST requests and validates the signature header. Without signature validation anyone who figures out your webhook URL can push fake schedule changes into your system. I saw this happen to a clinic down the road. Someone scraped the endpoint from their GitHub repo and ran a loop that injected invalid assignments. The webhook signature check solves this entirely. The header includes an HMAC-SHA256 signature that you verify against a shared secret before processing any payload.
One more thing about the Atrium side that the public documentation glosses over: oncology scheduling often requires backfill automation when a nurse calls out sick. The API supports automatic shift reassignment through a specific endpoint that queries available nurses by proximity and certification match. I configured this to trigger within 15 minutes of a callout being logged. The system identifies eligible replacements from ShiftSelect, checks their current patient load, and proposes the top two matches to a scheduler for approval. The approval step is still manual because the algorithm sometimes picks a nurse who is qualified but already at capacity on a different unit. Auto-assigning without human oversight creates more problems than it solves in oncology settings. The total build time for a functional integration varies. A well-scoped read-only credential checker took me about 8 hours including testing. The full write path with webhooks and backfill automation pushed it to roughly 3 days. If your team has existing OAuth experience and a staging environment ready, you can cut that in half. If you are waiting on IT to provision API access and get firewall rules updated, plan on a week or two of delays before you make your first successful call. The most honest assessment of this approach: it works well for the volume of data Atrium's oncology units handle but it is not a replacement for having a scheduler on the floor during peak turnover periods. The API handles the routine checks and the routine assignments. When three nurses call out on the same Tuesday morning during flu season, the automation gets confused and surfaces mediocre matches because its pool of qualified nurses shrinks faster than the algorithm can adapt. In those situations the manual override is faster than fighting the system. The API is strongest as a filter and a data pipeline, not as a decision maker.
