Trinet logo
API docs by Redocly

Go Carrier Services API (1.0.0)

Download OpenAPI specification:

Go Carrier Services API offers a comprehensive solution for integrating with multiple carriers under a single API.

Introduction

With support for multiple carriers, our API ensures you have all the necessary information at your fingertips. Whether you are a small business or a large enterprise, our API will help you streamline your shipping process by providing you with real-time tracking information, shipping rates, and more. Supported carriers include:
- FedEx
- Purolator
- UPS
- Loomis Express
- Canada Post
- GLS
- USPS
- DHL

Authentication

Authentication to the Go Tracking API is required to ensure secure access to our services. Use the following headers for authentication:

  • x-client-id: Your unique client identifier provided upon registration.
  • x-client-secret: A confidential client secret for secure access. Ensure to keep this secret safe and do not share it publicly.

Webhooks

Webhooks are used to notify your application when a shipment is updated. The following schema is used to define the webhook payload:

  {
    "id": "string",

    "trackingNumber": "string",

    "trackerId": "string",

    "status": "string",

    "description": "string",

    "date": "ISO Date String",

    "location": { 

      "city": "string",

      "state": "string",

      "country": "string",

      "zip": "string"

    }
  }

Credentials

Manage credentials for carriers.

Create a new credential

Provide custom credentials to be used for carrier authentication

Request Body schema: application/json
required
Any of
carrierCode
required
string

Carrier Code

code
required
string

A unique name for this credential. Use the same credential as it is on GO, this will be used to define what account to use when connecting with the carrier services.

config
object

JSON configuration for the credential.

required
object

The connection details in a JSON format.

Responses

Request samples

Content type
application/json
Example
{
  • "carrierCode": "string",
  • "code": "string",
  • "config": { },
  • "credentials": {
    }
}

Response samples

Content type
application/json
{
  • "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "code": "CONN123",
  • "clientId": "string",
  • "carrierCode": "string"
}

Find all credentials

Retrieve all credentials

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Find a credential by ID

Retrieve a credential by ID

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "code": "CONN123",
  • "clientId": "string",
  • "carrierCode": "string"
}

Delete a credential

Delete a credential by ID

path Parameters
id
required
string

Responses

Get the credential schema by carrier code

Retrieve the schema for a specific carrier

path Parameters
carrierCode
required
string

Responses

Carriers

Manage carriers available through the API.

Get all carriers

Get a list of available carriers and their codes

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Carriers Services

Manage carriers services available through the API.

Create a new carrier service

Request Body schema: application/json
required
object (CreateCarrierServiceDto)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "code": "EXPRESS",
  • "name": "Express Delivery",
  • "carrierCode": "DHL",
  • "description": "Provides expedited shipping for packages under 50 lbs.",
  • "config": "{\"deliveryWindow\": \"24 hours\", \"tracking\": true}"
}

Get all carrier services

query Parameters
carrierCode
string

The carrier code

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a carrier service by ID

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "code": "EXPRESS",
  • "name": "Express Delivery",
  • "carrierCode": "DHL",
  • "description": "Provides expedited shipping for packages under 50 lbs.",
  • "config": "{\"deliveryWindow\": \"24 hours\", \"tracking\": true}"
}

Update a carrier service

path Parameters
id
required
string
Request Body schema: application/json
required
object (UpdateCarrierServiceDto)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "code": "EXPRESS",
  • "name": "Express Delivery",
  • "carrierCode": "DHL",
  • "description": "Provides expedited shipping for packages under 50 lbs.",
  • "config": "{\"deliveryWindow\": \"24 hours\", \"tracking\": true}"
}

Delete a carrier service

path Parameters
id
required
string

Responses

Carriers Handling Units

Manage carriers handling units available through the API.

Create a new carrier handling unit

Request Body schema: application/json
required
object (CreateCarrierHandlingUnitDto)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "code": "PALLETS",
  • "mapping": {
    },
  • "carrierCode": "FEDEX",
  • "description": "Handling unit for managing large pallets",
  • "config": "{\"maxWeight\": \"1000 kg\", \"dimensions\": \"120x100x90 cm\"}"
}

Get all carrier handling units

query Parameters
full
required
boolean
carrierCode
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a carrier handling unit by ID

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "code": "PALLETS",
  • "mapping": {
    },
  • "carrierCode": "FEDEX",
  • "description": "Handling unit for managing large pallets",
  • "config": "{\"maxWeight\": \"1000 kg\", \"dimensions\": \"120x100x90 cm\"}"
}

Update a carrier handling unit

path Parameters
id
required
string
Request Body schema: application/json
required
object (UpdateCarrierHandlingUnitDto)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "code": "PALLETS",
  • "mapping": {
    },
  • "carrierCode": "FEDEX",
  • "description": "Handling unit for managing large pallets",
  • "config": "{\"maxWeight\": \"1000 kg\", \"dimensions\": \"120x100x90 cm\"}"
}

Delete a carrier handling unit

path Parameters
id
required
string

Responses

Carriers Accessorials

Manage carriers accessorials available through the API.

Create a new carrier accessorial

Request Body schema: application/json
required
object (CreateCarrierAccessorialDto)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "code": "LIFTGATE",
  • "mapping": {
    },
  • "carrierCode": "UPS",
  • "description": "Additional service for liftgate required at delivery.",
  • "config": "{\"serviceArea\": \"Urban\", \"additionalCost\": true}"
}

Get all carrier accessorials

query Parameters
full
required
boolean
carrierCode
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a carrier accessorial by ID

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "code": "LIFTGATE",
  • "mapping": {
    },
  • "carrierCode": "UPS",
  • "description": "Additional service for liftgate required at delivery.",
  • "config": "{\"serviceArea\": \"Urban\", \"additionalCost\": true}"
}

Update a carrier accessorial

path Parameters
id
required
string
Request Body schema: application/json
required
object (UpdateCarrierAccessorialDto)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "code": "LIFTGATE",
  • "mapping": {
    },
  • "carrierCode": "UPS",
  • "description": "Additional service for liftgate required at delivery.",
  • "config": "{\"serviceArea\": \"Urban\", \"additionalCost\": true}"
}

Delete a carrier accessorial

path Parameters
id
required
string

Responses

Shipments

Manage your shipments with ease

Book shipment

Book shipment synchronously or asynchronously

Request Body schema: application/json
required

Booked Shipment data or Job ID

required
Array of objects (BookingDto)

Array of shipment requests

async
boolean
Default: false

Flag to book shipment asynchronously. NOTICE: A maximum of 5 shipments can be booked synchronously.

Responses

Request samples

Content type
application/json
{
  • "data": [
    ],
  • "async": false
}

Response samples

Content type
application/json
Example
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "data": {
    },
  • "carrierCode": "UPS",
  • "shipmentExternalId": "string",
  • "shipmentReference": "string",
  • "trackingNumber": "string",
  • "docs": [
    ],
  • "packageTrackingNumbers": [
    ],
  • "jobId": "string"
}

Get booking job by ID

Use this to confirm the status of a booking job and retrieve the booking details

path Parameters
groupId
required
string

Booking job group ID

Responses

Get booking documents

Get booking documents by file name

path Parameters
fileName
required
string

Document file name

Responses

Retry booking job

Retry a failed booking job

path Parameters
groupId
required
string

Booking job group ID

recordId
required
string
jobId
required
any

Booking job ID

Responses

Cancel a shipment

For testing, use the endpoint test/shipments/cancel and TEST_GTRN00000000 as shipmentId to get an error response

Request Body schema: application/json
required

Carrier, shipment and credentials information

carrierCode
required
string

Carrier code

shipmentId
required
string

Identification number of the shipment provided by the carrier. Some carriers use the tracking number as the shipment ID, while others use a different ID. Use external shipment ID

credentialsCode
required
string

Unique code for the credentials to be used in the connection. Use DEFAULT for Trinet default credentials. Here use the same credentials used to create the shipment

shouldRetry
boolean
Default: true

Should retry failed requests. Defaults to true

Responses

Request samples

Content type
application/json
{
  • "carrierCode": "FEDEX",
  • "shipmentId": "123456789",
  • "credentialsCode": "FEDEX_CREDENTIALS",
  • "shouldRetry": true
}

Response samples

Content type
application/json
{
  • "message": "TEST ERROR"
}

Trackers

Manage tracking records.

Create a new tracker

Provide the tracking information to start monitoring a shipment for updates. This operation initiates a shipment tracker and update notification process. Multiple instances of the same tracking number and carrier code will be ignored.

Request Body schema: application/json
required

Tracking Information, including notification webhooks

trackingNumber
required
string

The tracking number provided by the carrier

carrierCode
required
string

The carrier code for the carrier connection. Obtain valid carrier codes from the GET /carriers endpoint.

required
Array of objects (WebhookDto)

Array of webhook objects to notify when the tracking is updated. NOTICE: this value cannot be overridden by the using this method, use the PUT /trackings/:trackerId endpoint instead. Supported methods: POST.

eta
string

Shipment expected delivery date

Responses

Request samples

Content type
application/json
{
  • "trackingNumber": "string",
  • "carrierCode": "string",
  • "notificationWebhooks": [
    ],
  • "eta": "2021-09-30T00:00:00.000Z"
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "id": "a1b2c3d4-1234-5678-9abc-1234567890ab",
  • "trackingNumber": "string",
  • "clientId": "string",
  • "carrierCode": "string",
  • "history": [
    ],
  • "latestStatus": {
    },
  • "notificationWebhooks": [
    ],
  • "isActive": true,
  • "forceNextFulfillment": true,
  • "eta": "2019-08-24T14:15:22Z"
}

Get all trackers

Get list of all shipments being tracked

path Parameters
code
required
string

Carrier Connection Code

query Parameters
pageSize
number <= 50
Default: 10

Number of entries per page

page
number >= 1
Default: 1
trackingNumbers
Array of strings

Tracking Numbers

carrierCodes
Array of strings

Carrier Codes

withTrackingStatus
required
boolean
Default: true

If true return tracker with tracking status. Default is true.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Get available tracking statuses

Get all possible tracking statuses

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get a tracker by id

Get tracking details of a specific shipment being tracked

path Parameters
id
required
string

Tracker uuid received upon creation

code
required
any

Carrier Connection Code

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "id": "a1b2c3d4-1234-5678-9abc-1234567890ab",
  • "trackingNumber": "string",
  • "clientId": "string",
  • "carrierCode": "string",
  • "history": [
    ],
  • "latestStatus": {
    },
  • "notificationWebhooks": [
    ],
  • "isActive": true,
  • "forceNextFulfillment": true,
  • "eta": "2019-08-24T14:15:22Z"
}

Update a tracker configuration by id

Update the configuration of a shipment tracker. Use this to create new notification webhooks

path Parameters
id
required
string

Tracker uuid received upon creation

Request Body schema: application/json
required
trackingNumber
string

The tracking number provided by the carrier

Array of objects (WebhookDto)

Array of webhook objects to notify when the tracking is updated. NOTICE: this value cannot be overridden by the using this method, use the PUT /trackings/:trackerId endpoint instead. Supported methods: POST.

isActive
boolean

Whether the tracker is active or not

Responses

Request samples

Content type
application/json
{
  • "trackingNumber": "string",
  • "notificationWebhooks": [
    ],
  • "isActive": true
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "id": "a1b2c3d4-1234-5678-9abc-1234567890ab",
  • "trackingNumber": "string",
  • "clientId": "string",
  • "carrierCode": "string",
  • "history": [
    ],
  • "latestStatus": {
    },
  • "notificationWebhooks": [
    ],
  • "isActive": true,
  • "forceNextFulfillment": true,
  • "eta": "2019-08-24T14:15:22Z"
}

Remove a shipment tracker by ID

Stop the shipment tracker. By removing the tracker, the shipment tracking records will no longer be update, nor will new notifications will be sent

path Parameters
id
required
string

Tracker uuid received upon creation

Responses

Tracking fulfillment

Manually add track record to a tracked shipment' tracking history. This operations will trigger notification webhooks

path Parameters
id
required
string

Tracker uuid received upon creation

Request Body schema: application/json
required
description
required
string

Description of the tracking status

date
required
string

ISO Date string of the tracking status update

object

Location of the tracking status update

status
required
string
Enum: "AWAITING_PAYMENT" "AWAITING_PICKUP" "SCHEDULED_FOR_PICKUP" "BOOKED" "CANCELLED" "CLEARED" "COULD_NOT_LOAD_TRACKING_INFORMATION" "DELAYED" "DELIVERED" "DELIVERY_ATTEMPTED" "DROPPED_OFF" "HOLD" "IN_TRANSIT" "INFO" "MISSING_INFORMATION" "OUT_FOR_DELIVERY" "PAID" "PICKED_UP" "PROCESSED" "PROCESSING" "REFUSED" "RETURN" "RETURNED_TO_SENDER" "SCHEDULED_FOR_DELIVERY" "TRACKER_CREATED" "UNABLE_TO_PICKUP" "UNDELIVERABLE" "UNKNOWN"

Status of the shipment

Responses

Request samples

Content type
application/json
{
  • "description": "Package delivered at front door",
  • "date": "2023-11-20T00:00:00.000Z",
  • "location": {
    },
  • "status": "AWAITING_PAYMENT"
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "id": "a1b2c3d4-1234-5678-9abc-1234567890ab",
  • "status": "DELIVERED",
  • "description": "Package delivered at front door",
  • "date": "2023-11-20T00:00:00.000Z",
  • "location": "Quebec, Canada"
}

Refresh all trackers

This operation will trigger a refresh of provided trackers. This will update the tracking status of the shipment and trigger notification webhooks

Request Body schema: application/json
required
ids
Array of strings

Tracker Ids

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Rates

Get rates for small parcel and LTL shipments.

Get rates for small parcel and LTL shipments

Request Body schema: application/json
required
required
Array of objects (RequestedCarriersDto)

Requested carriers and credentials

required
object

Shipment details

Responses

Request samples

Content type
application/json
{
  • "requestedCarriers": [
    ],
  • "shipment": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

Notifications

Manage notifications for your shipments.

Create a new notifier

Add a new notifier configuration to the system. This includes the channel to send the notification to and the template to use.

Request Body schema: application/json
required

Notifier configuration details

code
required
string

Unique code for the notification template

template
required
string

Content of the notification template, which can include variables to be replaced at runtime. Use placeholders to customize the message. Supported format: Mustache.

channel
required
string
Enum: "email" "slack" "pusher"

The channel to send the notification to

body
object

Default values for the placeholders in the template. Must be a valid JSON object

config
object

Default configuration for the channel. Must be a valid JSON object. (See the NotificationDto for more details)

Responses

Request samples

Content type
application/json
{
  • "code": "WELCOME_EMAIL",
  • "template": "Hello, {{user}}! Welcome to our platform.",
  • "channel": "email",
  • "body": { },
  • "config": { }
}

Response samples

Content type
application/json
{}

Find all notifiers

Retrieve a list of all notifiers.

Responses

Find one notifier

Retrieve details of a specific notifier by ID.

path Parameters
id
required
string

The ID of the notifier to retrieve

Responses

Update a notifier

Update the configuration of an existing notifier.

path Parameters
id
required
string

The ID of the notifier to update

Request Body schema: application/json
required

Updated notifier configuration details

code
string

Unique code for the notification template

template
string

Content of the notification template, which can include variables to be replaced at runtime. Use placeholders to customize the message. Supported format: Mustache.

channel
string
Enum: "email" "slack" "pusher"

The channel to send the notification to

body
object

Default values for the placeholders in the template. Must be a valid JSON object

config
object

Default configuration for the channel. Must be a valid JSON object. (See the NotificationDto for more details)

Responses

Request samples

Content type
application/json
{
  • "code": "WELCOME_EMAIL",
  • "template": "Hello, {{user}}! Welcome to our platform.",
  • "channel": "email",
  • "body": { },
  • "config": { }
}

Delete a notifier

Remove a notifier from the system.

path Parameters
id
required
string

The ID of the notifier to delete

Responses

Send a notification

Trigger a notification using a specific notifier.

path Parameters
id
required
string

The ID of the notifier to notify

Request Body schema: application/json
required

Payload to send with the notification

Any of
body
required
object

Use this property to pass the notification body attributes that will be used to render the notification template. Can override default body

required
object

The configuration for the Slack notification. Supported formats: block kit (please See Slack Block Kit for more details)

Responses

Request samples

Content type
application/json
Example
{
  • "body": {
    },
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string"
}