Needs

A need is an open staffing request: a facility needs n people with a title (and optionally a specialty) on a date and time window. Filling a need creates one order per provider. Scopes: Read needs, orders and shift events for GET, Manage needs, orders and shift events for everything else.

Method	Path	Purpose
GET	/needs	List needs
POST	/needs	Create a need
GET	/needs/{id}	Get a need
PUT	/needs/{id}	Update a need
DELETE	/needs/{id}	Cancel a need
POST	/needs/{id}/assign	Assign a provider, creating the linked order

The need object

{
  "id": "9a21…",
  "organizationId": "680e…",
  "facilityId": "0b7c…",
  "title": "RN",
  "specialty": "ICU",
  "shiftDate": "2026-11-03",
  "startTime": "07:00:00",
  "endTime": "19:00:00",
  "certifications": ["BLS", "ACLS"],
  "notes": "Night differential applies",
  "quantity": 2,
  "filledCount": 1,
  "status": "partially_filled",
  "createdBy": "6f3b…",
  "createdAt": "2026-10-20T15:02:11.000Z",
  "updatedAt": "2026-10-21T09:15:40.000Z",
  "facility": { "id": "0b7c…", "name": "Cedar Ridge Medical Center", "type": "Hospital" }
}

status is maintained by Atla from the linked orders: open (none filled), partially_filled, filled (filledCount >= quantity), or canceled. Cancelling a linked order lowers filledCount again.

List needs

curl -H "Authorization: Bearer $KEY" \
  "https://app.atlahq.com/api/v1/needs?status=open&from=2026-11-01&to=2026-11-30&page=1&pageSize=100"

Query	Meaning
status	open, partially_filled, filled, canceled
facilityId	One facility
title, specialty	Exact match, for example RN, ICU
from, to	shiftDate range, inclusive
search	Title, specialty, notes, facility name
sort	shift_date, title, status, created_at
sortDirection	asc or desc
page, pageSize	Pagination (see Conventions)

Create a need

curl -X POST https://app.atlahq.com/api/v1/needs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "facilityId": "0b7c…",
    "title": "RN",
    "specialty": "ICU",
    "shiftDate": "2026-11-03",
    "startTime": "07:00",
    "endTime": "19:00",
    "quantity": 2,
    "certifications": ["BLS", "ACLS"],
    "notes": "Night differential applies"
  }'

{ "success": true, "id": "9a21…" }

Required: facilityId, title, shiftDate, startTime, endTime. quantity defaults to 1. Titles and specialties are matched by name against the organization's lists in Atla.

Update and cancel

curl -X PUT https://app.atlahq.com/api/v1/needs/9a21… \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "quantity": 3, "notes": "Third slot added" }'

curl -X DELETE https://app.atlahq.com/api/v1/needs/9a21… -H "Authorization: Bearer $KEY"

Delete is a soft cancel (status: canceled). Orders already created from the need are not cancelled automatically; cancel them through Orders if required.

Assign a provider

curl -X POST https://app.atlahq.com/api/v1/needs/9a21…/assign \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "providerId": "4c1d…" }'

{ "success": true, "orderId": "b3e7…" }

Creates an order that inherits the need's facility, date, times, title, specialty and certifications, books the provider on it and notifies them, exactly as the Atla web app does. Refused with 422 when the provider is disabled, missing a required document for the facility, not cleared there, or marked unavailable that day. filledCount and status on the need update automatically.