POST
Create a trip
Company space For: Stock keeper, Manager · Permission: trips.create, trip_stops.create, trip_legs.create, trip_rates.create, trip_vehicles.create Conditions
  • When nested stops, legs, rates or vehicles are sent, the caller also needs the matching trip_stops, trip_legs, trip_rates or trip_vehicles create permission.
  • name and is_private are required; stops is required with at least two entries; status and company_id are refused.
  • name must be unique: among the organization’s shared trips when is_private is false, or among the calling company’s private trips when it is true.
  • Each stop needs a distinct position, a point_type and a 27-character point_id. The point type must be registered (location_group, waypoint, vendor, vendor_pickup_point, customer, customer_address) and the point must exist.
  • Supplier, supplier pickup point, customer and customer address stops are only allowed on private trips; shared trips accept location groups and waypoints only.
  • Each leg must name two stops by position that exist in the request and the destination must come after the source; a source and destination pair can appear only once (409).
  • Vehicle asset_id must be a vehicle asset of the organization; load_weight and load_volume are refused. Rate amounts are in major units with at most the currency’s decimals and cannot be negative; amount_minor is refused.
  • The whole creation runs in one transaction: if any nested item is refused nothing is created.
What else happens
  • Creates the trip with status active, owned by the calling company and organization, with the caller as creator.
  • Creates the nested stops (with a copy of the point name and address), legs, leg rates, trip-level rates (owned by the calling company) and vehicles that were sent.
Part of Reusable trips and waypoints.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Response

TripResource

id
string
required

Identifier of the trip (27-character KSUID).

company_id
string
required

Identifier of the company the record belongs to.

is_private
boolean
required

True when only the owning company sees the trip; false when the trip is shared with every company of the organization. Set at creation and never changed.

name
string
required

Name of the trip, unique among shared trips of the organization or among the private trips of the owning company.

description
string | null
required

Free-text description of the trip; null when none.

status
string
required

active: the trip and its stops, legs, rates and vehicles can be modified. archived: they are frozen until the trip is set back to active.

creator_user_id
string | null
required

Identifier of the member who created the trip, set by the server.

created_at
string<date-time>
required

Date and time the record was created (ISO 8601, UTC).

updated_at
string<date-time>
required

Date and time the record was last changed (ISO 8601, UTC).

stops
TripStopResource · object[]

Stops of the trip, ordered by position.

legs
TripLegResource · object[]

Legs of the trip, ordered by the position of their source stop. Each leg carries only the rates of the calling company.

rates
TripRateResource · object[]

Trip-level rates (not attached to a leg) owned by the calling company; rates of other companies are never returned.

vehicles
TripVehicleResource · object[]

Vehicle assets attached to the trip.