{ "openapi": "3.1.0", "info": { "title": "Atla public API", "version": "1.0.0", "summary": "Read and write an organization's providers, facilities, needs, orders and shift events with an API key.", "description": "## Authentication\n\nCreate a key in Atla under Settings > API keys and send it as a bearer token:\n\n```\nAuthorization: Bearer atla_live_...\n```\n\nA key acts as the organization that created it, limited to the scopes it was given. Every route below names the scope it needs.\nKeys expire on the date chosen at creation and can be revoked at any time; a revoked or expired key answers `401`.\n\n## Scopes\n\n- `providers:read`: Read providers. List providers and their facility assignments and specialties.\n- `providers:write`: Manage providers. Create, update and deactivate providers; assign facilities and specialties. Includes Read providers.\n- `facilities:read`: Read facilities. List facilities, their assigned providers and contacts.\n- `facilities:write`: Manage facilities. Create, update and delete facilities and facility contacts. Includes Read facilities.\n- `scheduling:read`: Read needs, orders and shift events. List and read staffing needs, orders (shifts) and time-clock events.\n- `scheduling:write`: Manage needs, orders and shift events. Create and update needs and orders, assign providers, record shift events. Includes the read scope.\n\nA write scope includes its read scope.\n\n## Limits and conventions\n\n- 600 requests per minute per key. `X-RateLimit-Remaining` is returned on every response; a `429` carries `Retry-After`.\n- Ids are UUIDs. Dates are `YYYY-MM-DD`; times are facility wall-clock `HH:MM:SS`; timestamps are ISO 8601 in UTC.\n- List routes return a flat array, or `{ data, total }` when `page` is given.\n- Errors are `{ \"statusCode\": 400, \"statusMessage\": \"...\" }`.\n- Routes in this document only change additively. Anything not listed here is not part of the public contract." }, "servers": [ { "url": "https://app.atlahq.com/api/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Account", "description": "About the key itself" }, { "name": "Providers", "description": "Clinicians and other staff the organization schedules" }, { "name": "Facilities", "description": "Places where shifts happen" }, { "name": "Needs", "description": "Open staffing requests, filled by assigning providers" }, { "name": "Orders", "description": "Shifts. An order is one provider, one facility, one date and time window" }, { "name": "Shift events", "description": "Check-in, break and check-out events on an order" } ], "paths": { "/profile": { "get": { "tags": [ "Account" ], "summary": "Who am I", "description": "The integration user behind the key: organization and effective entitlements. Reachable with any key. Useful to verify a key works.", "operationId": "getProfile", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/providers": { "get": { "tags": [ "Providers" ], "summary": "List providers", "description": "Scope `providers:read`. Every provider in the organization the key is allowed to see (provider label rules apply).", "operationId": "listProviders", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Providers" ], "summary": "Create a provider", "description": "Scope `providers:write`. Creates the sign-in account and the provider record.", "operationId": "createProvider", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCreate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "userId": { "type": "string", "format": "uuid" }, "providerId": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/providers/{id}": { "put": { "tags": [ "Providers" ], "summary": "Update a provider", "description": "Scope `providers:write`. Only keys present in the body are written; an explicit `null` clears a field. `isActive: false` disables the provider.", "operationId": "updateProvider", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderUpdate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Providers" ], "summary": "Deactivate a provider", "description": "Scope `providers:write`. Soft delete: sets `isActive` false and `status` terminated. The sign-in account is kept.", "operationId": "deactivateProvider", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/providers/{id}/facilities": { "get": { "tags": [ "Providers" ], "summary": "List a provider's facility assignments", "description": "Scope `providers:read`.", "operationId": "listProviderFacilities", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderFacility" } } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Providers" ], "summary": "Assign facilities to a provider", "description": "Scope `providers:write`.", "operationId": "assignProviderFacilities", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "facilityIds" ], "properties": { "facilityIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Providers" ], "summary": "Set clearance on a facility assignment", "description": "Scope `providers:write`. Marks the provider cleared (or not) to work at the facility.", "operationId": "setProviderFacilityClearance", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "facilityId", "cleared" ], "properties": { "facilityId": { "type": "string", "format": "uuid" }, "cleared": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Providers" ], "summary": "Remove facility assignments", "description": "Scope `providers:write`.", "operationId": "removeProviderFacilities", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "facilityIds" ], "properties": { "facilityIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/providers/{id}/specialties": { "get": { "tags": [ "Providers" ], "summary": "List a provider's specialties", "description": "Scope `providers:read`.", "operationId": "listProviderSpecialties", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderSpecialty" } } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Providers" ], "summary": "Replace a provider's specialties", "description": "Scope `providers:write`.", "operationId": "setProviderSpecialties", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "specialtyIds" ], "properties": { "specialtyIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/facilities": { "get": { "tags": [ "Facilities" ], "summary": "List facilities", "description": "Scope `facilities:read`. Active facilities of the organization.", "operationId": "listFacilities", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Facility" } } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Facilities" ], "summary": "Create a facility", "description": "Scope `facilities:write`.", "operationId": "createFacility", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityCreate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessWithId" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/facilities/{id}": { "get": { "tags": [ "Facilities" ], "summary": "Get a facility", "description": "Scope `facilities:read`.", "operationId": "getFacility", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Facility" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Facilities" ], "summary": "Update a facility", "description": "Scope `facilities:write`. Partial update.", "operationId": "updateFacility", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityCreate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Facilities" ], "summary": "Delete a facility", "description": "Scope `facilities:write`. Refused with `409` while orders or document requirements still reference it.", "operationId": "deleteFacility", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Still referenced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/facilities/{id}/providers": { "get": { "tags": [ "Facilities" ], "summary": "List providers assigned to a facility", "description": "Scope `facilities:read`.", "operationId": "listFacilityProviders", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FacilityProvider" } } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/facilities/{id}/contacts": { "get": { "tags": [ "Facilities" ], "summary": "List facility contacts", "description": "Scope `facilities:read`.", "operationId": "listFacilityContacts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FacilityContact" } } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Facilities" ], "summary": "Add a facility contact", "description": "Scope `facilities:write`. Needs at least a name or an email.", "operationId": "createFacilityContact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityContactInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessWithId" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/facility-contacts/{id}": { "put": { "tags": [ "Facilities" ], "summary": "Update a facility contact", "description": "Scope `facilities:write`. Partial update.", "operationId": "updateFacilityContact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityContactInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Facilities" ], "summary": "Delete a facility contact", "description": "Scope `facilities:write`.", "operationId": "deleteFacilityContact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/needs": { "get": { "tags": [ "Needs" ], "summary": "List needs", "description": "Scope `scheduling:read`.", "operationId": "listNeeds", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "partially_filled", "filled", "canceled" ] } }, { "name": "facilityId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "title", "in": "query", "schema": { "type": "string" }, "description": "Exact title, for example RN" }, { "name": "specialty", "in": "query", "schema": { "type": "string" }, "description": "Exact specialty, for example ICU" }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date", "example": "2026-11-03" }, "description": "shiftDate on or after" }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date", "example": "2026-11-03" }, "description": "shiftDate on or before" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "shift_date", "title", "status", "created_at" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number. When present the response is `{ data, total }`; when absent, a flat array." }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 25 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Need" } }, { "type": "object", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Need" } }, "total": { "type": "integer" } } } ] } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Needs" ], "summary": "Create a need", "description": "Scope `scheduling:write`.", "operationId": "createNeed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeedCreate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessWithId" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/needs/{id}": { "get": { "tags": [ "Needs" ], "summary": "Get a need", "description": "Scope `scheduling:read`.", "operationId": "getNeed", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Need" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Needs" ], "summary": "Update a need", "description": "Scope `scheduling:write`. Partial update.", "operationId": "updateNeed", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeedUpdate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Needs" ], "summary": "Cancel a need", "description": "Scope `scheduling:write`. Soft cancel: status becomes `canceled`.", "operationId": "cancelNeed", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/needs/{id}/assign": { "post": { "tags": [ "Needs" ], "summary": "Assign a provider to a need", "description": "Scope `scheduling:write`. Creates a linked order that inherits the need's facility, date, times and specialty. The need's `filledCount` and `status` update automatically.", "operationId": "assignNeed", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "providerId" ], "properties": { "providerId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "orderId": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Provider cannot take the shift (disabled, not compliant, not cleared, unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders": { "get": { "tags": [ "Orders" ], "summary": "List orders", "description": "Scope `scheduling:read`.", "operationId": "listOrders", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "booked", "confirmed", "complete", "canceled" ] } }, { "name": "facilityId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "providerId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date", "example": "2026-11-03" }, "description": "shiftDate on or after" }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date", "example": "2026-11-03" }, "description": "shiftDate on or before" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number. When present the response is `{ data, total }`; when absent, a flat array." }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 25 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, { "type": "object", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "total": { "type": "integer" } } } ] } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Orders" ], "summary": "Create an order", "description": "Scope `scheduling:write`. With `providerId` the order is created booked and the provider is notified; without it the order is open.", "operationId": "createOrder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessWithId" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Provider or facility not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Provider cannot take the shift (disabled, not compliant, not cleared, unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}": { "get": { "tags": [ "Orders" ], "summary": "Get an order", "description": "Scope `scheduling:read`.", "operationId": "getOrder", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Orders" ], "summary": "Update an order", "description": "Scope `scheduling:write`. Partial update. Changing `orderStatus` or `providerId` triggers the same notifications the web app sends.", "operationId": "updateOrder", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderUpdate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Provider cannot take the shift", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Orders" ], "summary": "Cancel an order", "description": "Scope `scheduling:write`. Soft cancel: `orderStatus` becomes `canceled`.", "operationId": "cancelOrder", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shift-events": { "get": { "tags": [ "Shift events" ], "summary": "List shift events for an order", "description": "Scope `scheduling:read`. Oldest first. `localTimestamp` is the facility wall-clock rendering of `timestamp`.", "operationId": "listShiftEvents", "parameters": [ { "name": "orderId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ShiftEvent" } } } } }, "400": { "description": "orderId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Shift events" ], "summary": "Record a shift event", "description": "Scope `scheduling:write`. Prefer `localTimestamp` (facility wall-clock) over `timestamp`; when both are absent the server uses now. The order's `shiftStatus` follows the latest event.", "operationId": "createShiftEvent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShiftEventCreate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessWithId" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shift-events/{id}": { "put": { "tags": [ "Shift events" ], "summary": "Update a shift event", "description": "Scope `scheduling:write`. Time and/or notes.", "operationId": "updateShiftEvent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "localTimestamp": { "$ref": "#/components/schemas/LocalTimestamp" }, "timestamp": { "type": "string", "format": "date-time" }, "notes": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Shift events" ], "summary": "Delete a shift event", "description": "Scope `scheduling:write`. The order's `shiftStatus` is recalculated.", "operationId": "deleteShiftEvent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing, invalid, expired or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not hold the scope this route needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 600 requests in a minute for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key from Settings > API keys, for example `atla_live_...`." } }, "schemas": { "Error": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 403 }, "statusMessage": { "type": "string", "example": "This API key does not have the \"Manage providers\" scope" } } }, "Success": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } } }, "SuccessWithId": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "id": { "type": "string", "format": "uuid" } } }, "LocalTimestamp": { "type": "string", "example": "2026-11-03T07:00:00", "description": "Facility wall-clock, `YYYY-MM-DDTHH:MM[:SS]`, no offset" }, "Profile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "displayName": { "type": "string" }, "role": { "type": "string", "example": "admin" }, "entitlements": { "type": "array", "items": { "type": "string" }, "description": "Feature tokens the key holds, derived from its scopes" }, "organizationId": { "type": "string", "format": "uuid" }, "organizationName": { "type": "string" } } }, "Provider": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid", "nullable": true }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "displayName": { "type": "string" }, "title": { "type": "string", "nullable": true }, "specialty": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "employeeId": { "type": "string", "nullable": true }, "hireDate": { "type": "string", "format": "date", "example": "2026-11-03", "nullable": true }, "hourlyRate": { "type": "number", "nullable": true }, "status": { "type": "string", "example": "active", "description": "incomplete, active, inactive, on_leave, terminated, or an applicant status" }, "phone": { "type": "string", "nullable": true }, "workPhone": { "type": "string", "nullable": true }, "emergencyContactName": { "type": "string", "nullable": true }, "emergencyContactPhone": { "type": "string", "nullable": true }, "rating": { "type": "number", "nullable": true }, "departmentId": { "type": "string", "format": "uuid", "nullable": true }, "departmentName": { "type": "string", "nullable": true }, "managerId": { "type": "string", "format": "uuid", "nullable": true }, "managerName": { "type": "string", "nullable": true }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "ProviderCreate": { "type": "object", "required": [ "email", "password", "firstName", "lastName" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8 }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "title": { "type": "string" }, "specialty": { "type": "string" }, "department": { "type": "string" }, "employeeId": { "type": "string" }, "hireDate": { "type": "string", "format": "date", "example": "2026-11-03" }, "hourlyRate": { "type": "number" } } }, "ProviderUpdate": { "type": "object", "description": "Only keys present are written. Send `null` to clear a field.", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "title": { "type": "string", "nullable": true }, "specialty": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "employeeId": { "type": "string", "nullable": true }, "hireDate": { "type": "string", "format": "date", "example": "2026-11-03", "nullable": true }, "hourlyRate": { "type": "number", "nullable": true }, "status": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "workPhone": { "type": "string", "nullable": true }, "emergencyContactName": { "type": "string", "nullable": true }, "emergencyContactPhone": { "type": "string", "nullable": true }, "isActive": { "type": "boolean" }, "departmentId": { "type": "string", "format": "uuid", "nullable": true }, "managerId": { "type": "string", "format": "uuid", "nullable": true } } }, "ProviderFacility": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "cleared": { "type": "boolean" } } }, "ProviderSpecialty": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "abbreviation": { "type": "string", "nullable": true } } }, "Facility": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zip": { "type": "string", "nullable": true }, "timezone": { "type": "string", "example": "America/Phoenix", "nullable": true }, "defaultStartTime": { "type": "string", "example": "07:00:00", "description": "HH:MM or HH:MM:SS, facility wall-clock", "nullable": true }, "defaultEndTime": { "type": "string", "example": "07:00:00", "description": "HH:MM or HH:MM:SS, facility wall-clock", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive", "maintenance", "pending" ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "FacilityCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "website": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "description": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "timezone": { "type": "string", "example": "America/Phoenix" }, "defaultStartTime": { "type": "string", "example": "07:00:00", "description": "HH:MM or HH:MM:SS, facility wall-clock" }, "defaultEndTime": { "type": "string", "example": "07:00:00", "description": "HH:MM or HH:MM:SS, facility wall-clock" }, "status": { "type": "string", "enum": [ "active", "inactive", "maintenance", "pending" ] } } }, "FacilityProvider": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid", "nullable": true }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "displayName": { "type": "string" }, "title": { "type": "string", "nullable": true }, "titleId": { "type": "string", "format": "uuid", "nullable": true }, "specialty": { "type": "string", "nullable": true }, "specialties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "department": { "type": "string", "nullable": true }, "status": { "type": "string" } } }, "FacilityContact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "facilityId": { "type": "string", "format": "uuid" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "mobile": { "type": "string", "nullable": true }, "isPrimary": { "type": "boolean" }, "notes": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "FacilityContactInput": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "title": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "mobile": { "type": "string" }, "isPrimary": { "type": "boolean" }, "notes": { "type": "string" } } }, "Need": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "facilityId": { "type": "string", "format": "uuid", "nullable": true }, "title": { "type": "string" }, "specialty": { "type": "string", "nullable": true }, "shiftDate": { "type": "string", "format": "date", "example": "2026-11-03" }, "startTime": { "type": "string", "example": "07:00:00", "description": "HH:MM or HH:MM:SS, facility wall-clock" }, "endTime": { "type": "string", "example": "07:00:00", "description": "HH:MM or HH:MM:SS, facility wall-clock" }, "certifications": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string", "nullable": true }, "quantity": { "type": "integer" }, "filledCount": { "type": "integer" }, "status": { "type": "string", "enum": [ "open", "partially_filled", "filled", "canceled" ] }, "createdBy": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "facility": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "nullable": true } }, "nullable": true } } }, "NeedCreate": { "type": "object", "required": [ "facilityId", "title", "shiftDate", "startTime", "endTime" ], "properties": { "facilityId": { "type": "string", "format": "uuid" }, "title": { "type": "string", "example": "RN" }, "specialty": { "type": "string", "example": "ICU" }, "shiftDate": { "type": "string", "format": "date", "example": "2026-11-03" }, "startTime": { "type": "string", "example": "07:00:00", "description": "HH:MM or HH:MM:SS, facility wall-clock" }, "endTime": { "type": "string", "example": "07:00:00", "description": "HH:MM or HH:MM:SS, facility wall-clock" }, "certifications": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "default": 1 } } }, "NeedUpdate": { "type": "object", "properties": { "facilityId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "specialty": { "type": "string", "nullable": true }, "shiftDate": { "type": "string", "format": "date", "example": "2026-11-03" }, "startTime": { "type": "string", "example": "07:00:00", "description": "HH:MM or HH:MM:SS, facility wall-clock" }, "endTime": { "type": "string", "example": "07:00:00", "description": "HH:MM or HH:MM:SS, facility wall-clock" }, "certifications": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string", "nullable": true }, "quantity": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "open", "partially_filled", "filled", "canceled" ] } } }, "Order": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "orderNumber": { "type": "string", "nullable": true }, "facilityId": { "type": "string", "format": "uuid", "nullable": true }, "address": { "type": "string", "nullable": true }, "providerId": { "type": "string", "format": "uuid", "nullable": true }, "availabilitySlotId": { "type": "string", "format": "uuid", "nullable": true }, "shiftDate": { "type": "string", "format": "date", "example": "2026-11-03" }, "startTime": { "type": "string", "example": "07:00:00", "description": "HH:MM or HH:MM:SS, facility wall-clock" }, "endTime": { "type": "string", "example": "07:00:00", "description": "HH:MM or HH:MM:SS, facility wall-clock" }, "certifications": { "type": "array", "items": { "type": "string" }, "nullable": true }, "role": { "type": "string", "description": "Title, for example RN", "nullable": true }, "specialty": { "type": "string", "nullable": true }, "shiftName": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "referenceNumber": { "type": "string", "nullable": true }, "payRate": { "type": "number", "nullable": true }, "billRate": { "type": "number", "nullable": true }, "orderType": { "type": "string", "nullable": true }, "travelContractId": { "type": "string", "format": "uuid", "nullable": true }, "orderStatus": { "type": "string", "enum": [ "open", "booked", "confirmed", "complete", "canceled" ] }, "guaranteed": { "type": "boolean" }, "cancelReason": { "type": "string", "nullable": true }, "canceledAt": { "type": "string", "format": "date-time", "nullable": true }, "shiftStatus": { "type": "string", "enum": [ "scheduled", "checked_in", "on_break", "checked_out", "no_show" ], "nullable": true }, "assignedAt": { "type": "string", "format": "date-time", "nullable": true }, "acknowledgedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdBy": { "type": "string", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "OrderCreate": { "type": "object", "required": [ "shiftDate", "startTime", "endTime" ], "properties": { "facilityId": { "type": "string", "format": "uuid" }, "providerId": { "type": "string", "format": "uuid" }, "needId": { "type": "string", "format": "uuid" }, "availabilitySlotId": { "type": "string", "format": "uuid" }, "shiftDate": { "type": "string", "format": "date", "example": "2026-11-03" }, "startTime": { "type": "string", "example": "07:00:00", "description": "HH:MM or HH:MM:SS, facility wall-clock" }, "endTime": { "type": "string", "example": "07:00:00", "description": "HH:MM or HH:MM:SS, facility wall-clock" }, "role": { "type": "string", "example": "RN" }, "specialty": { "type": "string", "example": "ICU" }, "shiftName": { "type": "string" }, "certifications": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "referenceNumber": { "type": "string" }, "payRate": { "type": "number" }, "billRate": { "type": "number" }, "orderType": { "type": "string" }, "guaranteed": { "type": "boolean" }, "orderStatus": { "type": "string", "enum": [ "open", "booked", "confirmed" ] }, "branchId": { "type": "string", "format": "uuid" }, "costCenterId": { "type": "string", "format": "uuid" }, "unitId": { "type": "string", "format": "uuid" } } }, "OrderUpdate": { "type": "object", "description": "Partial update. Same fields as OrderCreate, all optional.", "properties": { "facilityId": { "type": "string", "format": "uuid", "nullable": true }, "providerId": { "type": "string", "format": "uuid", "nullable": true }, "shiftDate": { "type": "string", "format": "date", "example": "2026-11-03" }, "startTime": { "type": "string", "example": "07:00:00", "description": "HH:MM or HH:MM:SS, facility wall-clock" }, "endTime": { "type": "string", "example": "07:00:00", "description": "HH:MM or HH:MM:SS, facility wall-clock" }, "role": { "type": "string" }, "specialty": { "type": "string", "nullable": true }, "shiftName": { "type": "string", "nullable": true }, "certifications": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string", "nullable": true }, "referenceNumber": { "type": "string", "nullable": true }, "payRate": { "type": "number", "nullable": true }, "billRate": { "type": "number", "nullable": true }, "orderType": { "type": "string", "nullable": true }, "guaranteed": { "type": "boolean" }, "orderStatus": { "type": "string", "enum": [ "open", "booked", "confirmed", "complete", "canceled" ] }, "cancelReason": { "type": "string", "nullable": true }, "branchId": { "type": "string", "format": "uuid", "nullable": true }, "costCenterId": { "type": "string", "format": "uuid", "nullable": true }, "unitId": { "type": "string", "format": "uuid", "nullable": true } } }, "ShiftEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "format": "uuid" }, "eventType": { "type": "string", "enum": [ "check_in", "break_start", "break_end", "check_out", "no_show" ] }, "timestamp": { "type": "string", "format": "date-time" }, "localTimestamp": { "$ref": "#/components/schemas/LocalTimestamp" }, "actorId": { "type": "string", "format": "uuid", "nullable": true }, "notes": { "type": "string", "nullable": true }, "latitude": { "type": "number", "nullable": true }, "longitude": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "actor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "displayName": { "type": "string" } }, "nullable": true } } }, "ShiftEventCreate": { "type": "object", "required": [ "orderId", "eventType" ], "properties": { "orderId": { "type": "string", "format": "uuid" }, "eventType": { "type": "string", "enum": [ "check_in", "break_start", "break_end", "check_out", "no_show" ] }, "localTimestamp": { "$ref": "#/components/schemas/LocalTimestamp" }, "timestamp": { "type": "string", "format": "date-time" }, "notes": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" } } } } } }