Build for state, not just requests.

The API uses OAuth2 client credentials. Sandbox tokens come fromoauth-sandbox.routespring.comand API calls go tosandbox.routespring.com/api/v1. Production hosts are confirmed during onboarding.

Each schedule submission represents the full picture for its date window. RouteSpring compares that snapshot with prior persisted legs and bookings to derive new stays, changes, cancellations, swaps, and deadhead flights.

• Reposting an identical roster is a no-op.
• Changing a deadhead identity key can produce a cancellation plus a new action item.
• Duty dates and local departure timestamps must agree or the leg can be dropped during grouping.

POST /crew/schedules acknowledges ingestion before reconciliation and supplier work finish. Continue polling the processing-status endpoint while poll_recommended is true. Stop when the API returns false.

A false value can accompany COMPLETED or FAILED, or a BOOKINGstate held only by items that need human action. Read action items and individual booking states before deciding that every travel requirement succeeded.

Treat schedule, action, booking, cursor, trip-session, and flight-option identifiers as opaque. Flight options expire in roughly 20 minutes, so search fresh and pass the selected ID back verbatim.

For booking failures, prefer the dedicated retry endpoints. They expose queue and job status so operators can distinguish a retried request from a duplicate booking attempt.