Single Allocation Guide

When to Use

Offer temporary pop-up availability (e.g., “Open house on July 6 from 10–14”).
Block time for one-off events such as training sessions or holidays.
Apply overrides for either a resource or a service without touching the global schedule.

Concepts

Date-based windows: Define explicit startDate / endDate timestamps (ISO 8601 strings). They can span multiple days.
Target scope: Provide exactly one of ResourceId or ServiceId (not both). You must specify one or the other.
Description: Optional field to help internal teams understand why the override exists.

Endpoint Overview

Endpoint	Purpose
`POST /v3/singleAllocation`	Create a single allocation.
`POST /v3/singleAllocation/setSingleAllocations`	Replace all single allocations for the provided target.
`GET /v3/singleAllocation`	List allocations for a company; filter by `ServiceId`, `ResourceId`, `startDate`, or `endDate`.
`GET /v3/singleAllocation/:id`	Retrieve one allocation.
`PUT /v3/singleAllocation/:id`	Update the dates or description.
`DELETE /v3/singleAllocation/:id`	Remove an override.

Payload Examples

Resource-specific allocation:

{
  "ResourceId": "<uuid>",
  "startDate": "2025-07-06T10:00:00-04:00",
  "endDate": "2025-07-06T14:00:00-04:00",
  "description": "Open studio session"
}

Service-specific allocation (applies to all resources linked to the service):

{
  "ServiceId": "<uuid>",
  "startDate": "2025-07-06T10:00:00-04:00",
  "endDate": "2025-07-06T14:00:00-04:00",
  "description": "Holiday special hours"
}

Dates must be ISO-8601 compliant; the API stores them in UTC internally.
You must provide either ResourceId or ServiceId, but not both. If you specify ServiceId, the override applies to every eligible resource linked to that service.

Editing Strategies

Bulk Manage: setSingleAllocations is ideal for UI workflows like drag-and-drop calendars. Submit singleAllocations: [ ... ] to replace the existing set atomically.
Incremental Changes: Use the standard CRUD endpoints when scripts need to add or remove a single override.

Interaction with Availability

Single allocations override weekly allocations for the exact time window supplied:

Add availability: Create an allocation that represents extra working hours outside the usual schedule.
Remove availability: Pair single allocations with recurring blocks or delete conflicting weekly windows to prevent slot creation.

Every create/update/delete call invalidates availability caches so new slots reflect the change immediately.

Troubleshooting

Missing ResourceId/ServiceId: The API returns a validation error if you omit both. You must provide exactly one—either ResourceId or ServiceId, but not both.
Overlapping windows: Overlaps are allowed, but they may create duplicate-looking availability. Keep your overrides tidy to avoid confusion in admin tools.
Time zone confusion: Always pass localized timestamps (e.g., America/New_York). When in doubt, append the offset explicitly.

Single allocations give you precise control over exceptional days without rewriting your recurring schedule.