# Roster Assignment

Manage crew roster assignments, including creating, retrieving, updating, and deleting duties. These endpoints enable partners to synchronize crew schedules and manage operational duties with the same semantics as the FL3XX web interface.

**Business Value**
- Automate crew schedule management and updates in real‑time.
- Keep crew schedules perfectly synchronized with external systems.
- Support crew self‑service and scheduler workflows via API.
- Reduce manual data entry and errors in crew roster management.

<br/>

**Use Cases**
- Create a new roster assignment (e.g., Off, Flight, Standby) for a crew member.
- Retrieve detailed information about a specific roster duty, including associated aircraft and airports.
- Update existing roster assignments to reflect changes in schedules or duty types.
- Search and filter roster assignments by crew member, type, or date range.

<br/>


## Get roster assignments

 - [POST /api/v2/rosters-search](https://developer.fl3xx.com/reference/v2/roster-assignment/rosterassignmentssearch.md): Returns a paginated list of roster assignments. Each item in the response is simplified; use GET /api/v2/rosters/{id} for full details.

## Create roster assignment

 - [POST /api/v2/rosters](https://developer.fl3xx.com/reference/v2/roster-assignment/rosterassignmentcreate.md): Creates a new roster assignment for a crew member. This is equivalent to adding a duty or day in the FL3XX roster interface.

Example Use Case: An automated scheduling system creates a "Standby" duty for a crew member, providing the start and end times, and ensuring all required references are correctly resolved.

Duration constraints:
- startDateTime must be strictly before endDateTime
- Maximum duration is 31 days for all roster types
- Maximum duration is 2 days for roster types with isDutyTimeVisible enabled

Field validation rules:
- Fields that the roster type does not support (e.g. sending dutyShiftType when isSubtypeVisible is false) are rejected with 400 — they are not silently ignored
- When a roster type has isDutyTimeVisible enabled, the following fields become mandatory if their corresponding flag is set: dutyAirportCode (isLocationVisible), departureAirportCode (isDepartureAirportEnabled), arrivalAirportCode (isArrivalAirportEnabled), serviceAirportCode (isForAirportEnabled), aircraft.tailNumber (isAircraftEnabled)
- When aircraft.crewPositionId is provided, aircraft.tailNumber is required. The crew position must be linked to the specified aircraft and must be assignable — use POST /api/v2/crew-position-search to discover valid positions

Check the roster type's configuration using GET /api/v2/roster-types/{id} before creating an assignment.

## Get roster assignment

 - [GET /api/v2/rosters/{id}](https://developer.fl3xx.com/reference/v2/roster-assignment/rosterassignmentbyidget.md): Retrieves the full details of a specific roster assignment.

Features:
- Returns complete assignment data including aircraft, airports, and logbook details
- Provides timing and status information
- Dynamic response structure based on the assignment's roster type

Example Use Case: A crew member's mobile app retrieves the full details of a "Flight" duty to display the assigned aircraft and the departure/arrival airports to the user.

Note: Sections such as aircraft, logbook, and ftl will be populated only if they are enabled for that specific duty type; otherwise, they will be null.

## Replace roster assignment

 - [PUT /api/v2/rosters/{id}](https://developer.fl3xx.com/reference/v2/roster-assignment/rosterassignmentbyidput.md): Replaces an existing roster assignment. All optional fields not provided in the request body are cleared on the assignment.

startDateTime and endDateTime should always be provided for a semantically correct PUT. If omitted, the existing values are preserved (due to how the API handles absent fields), but this behaviour should not be relied upon — always supply them.

Example Use Case: A scheduler performs a full replacement of a duty record, providing all relevant fields in the request to ensure a clean, authoritative update.

Validation rules (same as create):
- startDateTime must be strictly before endDateTime
- Fields the roster type does not support are rejected with 400
- Mandatory fields (when isDutyTimeVisible is set) must be present
- Duration constraints apply: max 31 days; max 2 days when isDutyTimeVisible
- FTL interdependency rules apply (see FTL schema)
- When aircraft.crewPositionId is provided, aircraft.tailNumber is required. The crew position must be linked to the specified aircraft and must be assignable

## Patch roster assignment

 - [PATCH /api/v2/rosters/{id}](https://developer.fl3xx.com/reference/v2/roster-assignment/rosterassignmentbyidpatch.md): Partially updates an existing roster assignment. Only the fields provided in the request body are updated; fields not included remain unchanged.

Example Use Case: A scheduler updates only the end time of an existing duty without affecting any other fields.

Validation rules:
- If provided, startDateTime must be strictly before endDateTime
- Fields the roster type does not support are rejected with 400 — they are not silently ignored
- Mandatory field checks (for isDutyTimeVisible) are not enforced on PATCH — only on PUT and create
- Duration constraints apply to the resulting start/end: max 31 days; max 2 days when isDutyTimeVisible
- FTL interdependency rules apply if ftl is provided (see FTL schema)
- When aircraft.crewPositionId is provided, aircraft.tailNumber is required. The crew position must be linked to the specified aircraft and must be assignable

## Delete a roster assignment

 - [DELETE /api/v2/rosters/{id}](https://developer.fl3xx.com/reference/v2/roster-assignment/rosterassignmentbyiddelete.md): Permanently removes the roster assignment.