Create a Shipment

To create a shipment via the Tive public API, you will need to provide the following required fields in your request payload.

shipmentId: a unique identifier for your shipment.
devices: an array of device ids to attach to a shipment. In order to start a shipment, a device must be attached.
fromAddress: the origin address of your shipment leg. Must be specified for each shipment leg.
fromCoordinates: the origin coordinates of your shipment leg. Must be specified for each shipment leg.
toAddress: the destination address of the shipment leg. Must be specified for each shipment leg.
toCoordinates: the destination coordinates of the shipment leg. Must be specified for each shipment leg.
mode: the mode of transportation. Valid modes are: Road, Air, Ocean, or Rail. Mode must be specified for each shipment leg.
shipFromDate: the start date of the first leg of the shipment.

Note, a device is not required to create a shipment, however, you must specify a device to start one. Additionally, while these may be the only required fields, additional information may be specified. To view the full shipment data model, please refer to the Create a Shipment endpoint.

{
    "shipmentId": "My New Shipment",
    "devices": [],
    "shipmentLegs": [
        {
            "mode": "Road",
            "fromAddress": {
                "street": "56 Roland St Suite 100A",
                "sublocality": null,
                "locality": "Boston",
                "state": "Massachusetts",
                "country": "United States",
                "postalCode": "02129"
            },
            "fromCoordinates": {
                "latitude": 42.38122791176727,
                "longitude": -71.08002729815101
            },
            "toAddress": {
                "street": "598 Assembly Row",
                "sublocality": null,
                "locality": "Somerville",
                "state": "Massachusetts",
                "country": "United States",
                "postalCode": "02145"
            },
            "toCoordinates": {
                "latitude": 42.39488110478032,
                "longitude": -71.07966965170591
            },
            "shipFromDate": "2022-01-27T18:00:00.000Z"
        }
    ]
}

Shipment Legs

For shipments that make more than one stop, legs can be created for each segment of the trip. To create a leg simply add an object within the shipmentLegs array. Each leg must specify the mode, fromAddress, fromCoordinates, toAddress, and toCoordinates.

"shipmentLegs": [
    {
        "mode": "Road",
        "fromAddress": {
            "street": "56 Roland St Suite 100A",
            "sublocality": null,
            "locality": "Boston",
            "state": "Massachusetts",
            "country": "United States",
            "zipCode": "02129"
        },
        "fromCoordinates": {
            "latitude": 42.38122791176727,
            "longitude": -71.08002729815101
        },
        "toAddress": {
            "street": "598 Assembly Row",
            "sublocality": null,
            "locality": "Somerville",
            "state": "Massachusetts",
            "country": "United States",
            "zipCode": "02145"
        },
        "toCoordinates": {
            "latitude": 42.39488110478032,
            "longitude": -71.07966965170591
        },
        "shipFromDate": "2022-01-27T18:00:00.000Z"
    },
    {
        "mode": "Road",
        "fromAddress": {
            "street": "598 Assembly Row",
            "sublocality": null,
            "locality": "Somerville",
            "state": "Massachusetts",
            "country": "United States",
            "zipCode": "02145"
        },
        "fromCoordinates": {
            "latitude": 42.39488110478032,
            "longitude": -71.07966965170591
        },
        "toAddress": {
            "street": "1 City Hall Square",
            "sublocality": null,
            "locality": "Boston",
            "state": "Massachusetts",
            "country": "United States",
            "zipCode": "02203"
        },
        "toCoordinates": {
            "latitude": 42.360343077859746,
            "longitude": -71.05759073862578
        }
    }
]

Shipment Status

Upcoming

Shipments will be considered upcoming if they start in the future. To do this, just set the shipFromDate property on the shipment's first leg accordingly.

Active

Shipments can be created without associating a device, however, once you’re ready to ship, you’ll be required to link at least one device to the shipment. This is important depending on how you prefer to start your shipments:

Start Immediately

If at least one device has been associated to your shipment, setting the query parameter startNow to true as part of your shipment creation request will immediately start your shipment. Otherwise, your shipment will be considered upcoming.

Start a Shipment Endpoint

Alternatively, once you create your shipment, you can subsequently call the Start a Shipment endpoint by specifying the shipment's publicShipmentId assuming the shipment has at least one device associated.

The following optional parameters may be specified as part of the Start a Shipment endpoint:

deviceIds: Allows you to add devices to the shipment. Note, if the shipment does not already have a device associated to it you must provide a valid deviceId or deviceName for a successful request.
skipDeviceLocationCheck: Determines whether a shipment should start even if the tracker location does not match the shipment start location. Defaults to false.
closeActiveShipments: If you are trying to start a shipment and a device is already on an active shipment, this boolean parameter will dictate whether the active shipments will be closed or not. Defaults to false.

curl --request PATCH \
     --url https://api.tive.com/public/v3/shipments/{publicShipmentId}/start \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR_JWT_TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
     "deviceIds": [
          "G12345",
          "G54321"
     ],
     "skipDeviceLocationCheck": false,
     "closeActiveShipments": false
}
'

Completed

The simplest way to complete a shipment is with the Automatic Shipment Completion Delay setting associated with an account. When a Tive device gets to the last stop on the last leg of a shipment, the shipment will automatically close after the specified time delay.

Auto completion can be changed via API with the Update Account Auto Complete Delay or by navigating the the account details page on the Tive platform. On the Tive platform, delay can be in minutes, hours, days, or weeks and can not be less than 60 minutes or more than 2 weeks. By default an account auto completion delay is set to 1 day. Via the API, this value must be specified in minutes as outlined by the field autocompleteShipmentDelayMinutes in the endpoint linked above.

Alternatively, the Complete a Shipment endpoint can be used to close your shipment as needed by specifying the shipment's publicShipmentId.

Custom Fields

While not required, shipments are able to take up to five custom fields. Common uses for custom fields include adding a Bill of Lading (BOL) or Purchase Order (PO) number for a shipment.

To add a custom field when creating a shipment, specify the name of the field with key, and the value with value. To add another custom field, just add another object ({}) with the new label and value.

{
    "shipmentName": "My New Shipment",
    "devices": [],
    "customFields": [
        {
            "key": "Purchase Order",
            "value": "PO 1234"
        },
        {
            "key": "Bill of Lading",
            "value": "BOL 4321"
        }
    ],
    "shipmentLegs": [
        {
            "mode": "Road",
            "fromAddress": {
                "street": "56 Roland St Suite 100A",
                "sublocality": null,
                "locality": "Boston",
                "state": "Massachusetts",
                "country": "United States",
                "zipCode": "02129"
            },
            "fromCoordinates": {
                "latitude": 42.38122791176727,
                "longitude": -71.08002729815101
            },
            "toAddress": {
                "street": "598 Assembly Row",
                "sublocality": null,
                "locality": "Somerville",
                "state": "Massachusetts",
                "country": "United States",
                "zipCode": "02145"
            },
            "toCoordinates": {
                "latitude": 42.39488110478032,
                "longitude": -71.07966965170591
            },
            "shipFromDate": "2022-01-27T18:00:00.000Z"
        }
    ]
}