Shipment Collaborators

Users can share real-time shipment location and condition data with any user they chose, in or outside of their organization. This also includes sharing shipments with people who don’t already have a Tive account. Custom shipment user roles unlock granular control of your real-time shipment visibility data with users to enable secure, efficient collaboration so that shipments arrive on time and in full.

Adding Shipment Collaborators

The Add Shipment Collaborators endpoint should be used for adding collaborators to a shipment.

// PUT https://api.tive.com/public/v3/collaborators/shipments/{publicShipmentId}/add

{
    "collaborators": [
        {
            "email": "[email protected]",
            "roleName": "Editor"
        },
        {
            "email": "[email protected]",
            "roleName": "Contributor"
        },
        {
            "email": "[email protected]",
            "roleName": "Viewer"
        }
    ]
}

To add a collaborator, all that is needed is a valid email address and the role, or access level, you would like to assign someone. Tive will automatically detect when an existing collaborator email address is provided, however, if the roleName does not match between the existing record and the new request, the incoming request will take precedence and update the existing collaborator role.

For example, if the following request was subsequently made after the example above, the existing collaborator, Michael Scott, would have his role updated from Viewer to Contributor on a successful request. Additionally, Walter White would also be added as a new contributor collaborator to the shipment.

// PUT https://api.tive.com/public/v3/collaborators/shipments/{publicShipmentId}/add

{
    "collaborators": [
        {
            "email": "[email protected]",
            "roleName": "Contributor"
        },
        {
            "email": "[email protected]",
            "roleName": "Contributor"
        }
    ]
}

To enable alerts for shipment collaborators, set notifyAllCollaborators to true when creating or editing an alert preset via API. Alternatively, enable the Notify shipment collaborators checkbox when creating or editing an alert preset on the Tive platform.

Role Names

When choosing a roleName for a shipment collaborator, you can specify one of the following three options per user: Viewer, Contributor, or Editor.

By default, each of these three roles provide increasingly more insight and information into the shipment specified. However, these roles can be customized on a per organization basis. At this time, it is not possible to edit the role permissions via the public API, but admins have the ability to alter them via Shipment Access Controls in the Tive platform.

Removing Collaborators

To revoke shipment access to one or more collaborator with the Remove Shipment Collaborators endpoint, all that must be provided is a list of collaborator email addresses.

// PUT https://api.tive.com/v3/collaborators/shipments/{publicShipmentId}/remove

{
    "emailAddresses": [
        "[email protected]",
        "[email protected]"
    ]
}