Orders

An order is a shift: one facility, one date and time window, and (once booked) one provider. Scopes: Read needs, orders and shift events for GET, Manage needs, orders and shift events for everything else.

Method	Path	Purpose
GET	/orders	List orders
POST	/orders	Create an order
GET	/orders/{id}	Get an order
PUT	/orders/{id}	Update an order
DELETE	/orders/{id}	Cancel an order

The order object

{
  "id": "b3e7…",
  "organizationId": "680e…",
  "orderNumber": "ORD-2026-01187",
  "facilityId": "0b7c…",
  "address": null,
  "providerId": "4c1d…",
  "availabilitySlotId": null,
  "shiftDate": "2026-11-03",
  "startTime": "07:00:00",
  "endTime": "19:00:00",
  "certifications": ["BLS", "ACLS"],
  "role": "RN",
  "specialty": "ICU",
  "shiftName": "Day",
  "notes": null,
  "referenceNumber": "PO-44812",
  "payRate": 62,
  "billRate": 88,
  "orderType": null,
  "travelContractId": null,
  "orderStatus": "booked",
  "guaranteed": false,
  "cancelReason": null,
  "canceledAt": null,
  "shiftStatus": "scheduled",
  "assignedAt": "2026-10-21T09:15:40.000Z",
  "acknowledgedAt": null,
  "createdBy": "6f3b…",
  "createdAt": "2026-10-21T09:15:40.000Z",
  "updatedAt": "2026-10-21T09:15:40.000Z"
}

Two status fields:

• orderStatus: the booking lifecycle. open (no provider) → booked (provider assigned) → confirmed (provider acknowledged or admin confirmed) → complete, or canceled at any point.
• shiftStatus: the time clock on the day, driven by shift events: scheduled, checked_in, on_break, checked_out, no_show.

role is the title (for example RN). payRate and billRate are visible to any key with the read scope.

List orders

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

Query	Meaning
status	open, booked, confirmed, complete, canceled
facilityId, providerId	One facility or provider
from, to	shiftDate range, inclusive
search, sortDirection	As on other lists
page, pageSize	Pagination (see Conventions)

For a nightly sync, pull a sliding window such as yesterday to 60 days ahead and compare updatedAt.

Create an order

curl -X POST https://app.atlahq.com/api/v1/orders \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "facilityId": "0b7c…",
    "providerId": "4c1d…",
    "shiftDate": "2026-11-03",
    "startTime": "07:00",
    "endTime": "19:00",
    "role": "RN",
    "specialty": "ICU",
    "referenceNumber": "PO-44812",
    "payRate": 62,
    "billRate": 88
  }'

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

Required: shiftDate, startTime, endTime. With providerId the order is created booked and the provider is notified; without it the order is open and can be filled later with PUT. Pass needId to link the order to a need (its filledCount updates). Both providerId and facilityId must belong to your organization (404 otherwise).

Booking is refused with 422 when the provider is disabled, missing a required document for the facility, not cleared there, or marked unavailable that day.

Update an order

Partial. Changing providerId rebooks the shift and notifies both providers; changing orderStatus sends the same notifications the web app does.

# Confirm
curl -X PUT https://app.atlahq.com/api/v1/orders/b3e7… \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "orderStatus": "confirmed" }'

# Reassign
curl -X PUT https://app.atlahq.com/api/v1/orders/b3e7… \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "providerId": "5d2e…" }'

# Mark complete after the shift
curl -X PUT https://app.atlahq.com/api/v1/orders/b3e7… \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "orderStatus": "complete" }'

Cancel an order

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

Soft: orderStatus becomes canceled, canceledAt is set, the provider is notified and any linked need's filledCount drops. To record a reason, use PUT with { "orderStatus": "canceled", "cancelReason": "…" } instead.