---
title: "Create a Shipment"
method: POST
path: "/public/v3/Shipments"
tags: ["Shipments"]
---

# Create a Shipment

`POST /public/v3/Shipments`

Create a shipment within the specified account.

## Headers

- `x-tive-account-id` integer, required

## Request body

- ShipmentCreateRequest
  - `skipDeviceLocationCheck` boolean — Determines whether a shipment should start even if the tracker location does not match the shipment start location. Defaults to `false`.
  - `closeActiveShipments` boolean — Close other active shipments related to the trackers being added to this shipment. When closing an existing shipment the new shipment will start at the current time. Defaults to `false`.
  - `devices` string[], nullable — A list of device IDs associated with the shipment. Note, to <emp>start</emp> a shipment you must specify at least one device.
  - `trackerStartDelay` 'ZeroMinutes' | 'ThirtyMinutes' | 'OneHour' | 'OneAndHalfHours' | 'TwoHours' | 'FourHours' — The period of time the tracker should wait before measuring or transmitting data after the start button is pressed. This is ONLY for Solo Pro Devices.
  - `shipmentId` string, required — The unique identifier of your shipment.
  - `customFields` ShipmentCustomFieldRequest[], nullable — Custom informational field that apply to your organization. Shipments allow for up to nine custom fields.
    - `key` string, nullable — The name of the custom field.
    - `value` string, nullable — The value of the custom field.
  - `shipmentLegs` ShipmentLegRequest[], required — For Shipments that make more than one stop, multiple Legs can be created for each stop that the shipment will make. Addresses are required for To/From for each leg, either by sending To/FromLocationId **or** To/FromCoordinates and To/FromAddress.
    - `mode` string, required — The mode of transportation. Values can be `Road`, `Ocean`, `Air`, or `Rail`.
    - `driverType` string, nullable — Driver type for road legs. Values can be `Solo`, `Team`.
    - `carrierId` string, nullable — ID of the carrier responsible for transport of the leg.
    - `fromLocationId` integer, nullable — ID of a saved location to use as the leg origin. When provided, FromCoordinates and FromAddress must not be set. Either this ID or both FromCoordinates and FromAddress are required.
    - `fromCoordinates` CoordinateRequest — Coordinates of the location.
      - `latitude` number, double, required
      - `longitude` number, double, required
    - `fromAddress` AddressRequest — The full address of the location.
      - `street` string, required
      - `sublocality` string, nullable
      - `locality` string, required
      - `state` string, required
      - `country` string, required
      - `postalCode` string, required
    - `toLocationId` integer, nullable — ID of a saved location to use as the leg destination. When provided, ToCoordinates and ToAddress must not be set. Either this ID or both ToCoordinates and ToAddress are required.
    - `toCoordinates` CoordinateRequest — Coordinates of the location.
      - `latitude` number, double, required
      - `longitude` number, double, required
    - `toAddress` AddressRequest — The full address of the location.
      - `street` string, required
      - `sublocality` string, nullable
      - `locality` string, required
      - `state` string, required
      - `country` string, required
      - `postalCode` string, required
    - `container` string, nullable — The container ID used when the shipment leg mode is <emp>Ocean</emp>.
    - `airWaybill` string, nullable — The air waybill used when the shipment leg mode is <emp>Air</emp>.
    - `shipFromDate` string, nullable — The start date and time of the leg. <b>Required</b> for the first leg of the shipment.
    - `etaDate` string, nullable — The estimated time of delivery for a given leg. This field should be set to enable ETA alerts and notifications via alert presets for a given leg.
    - `legLabel` string, nullable — The custom name of a shipment leg.
    - `alertPresetIds` integer[], nullable — A list of alert preset IDs that should trigger their respective alerts on a given shipment leg.
  - `endOfTripConfiguration` EndOfTripConfigurationRequest
    - `sendToCollaborators` boolean — Should collaborators receive end of trip report.
    - `users` string[], nullable — List of userIds for users that should receive the end of trip report.
  - `commodities` integer[], nullable — List of commodity ids to attach to the shipment.
  - `mbolNumber` string, nullable — The Master Bill of Lading Number associated to this shipment.
  - `mbolCarrierScac` string, nullable — The SCAC code of the carrier for the Master Bill of Lading Number associated to this shipment.
  - `startNow` boolean — Specify whether the shipment should start immediately on successful creation. Defaults to `false` when not specified.
  - `collaborators` ShipmentCollaboratorRequest[], nullable — Optional list of collaborators to add to the shipment upon creation.
    - `email` string, required — Email address of the user collaborator.
    - `roleName` string, required — Name of the shipment role you would like to assign to a user. Values can be `Viewer`, `Contributor`, or `Editor`.

## Response `201`

The created shipment publicShipmentId

- integer

## Other responses

- `400` — Unable to create the shipment. See response message for details.
- `401` — Unauthorized

---

[API](https://skmtc.net/tive/apis/tive-public-api.md) · [All operations](https://skmtc.net/tive/apis/tive-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tive/tive-public-api/versions/9a8d869e3cdc/schema)