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. Poll the processing-status endpoint until it returns COMPLETED,PARTIAL, or FAILED.

Do not stop on the first apparent completion if flight tasks remain. The aggregate status can move back to BOOKING while a supplier call is still non-terminal.

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.