Search

API Getting Started Guide

Introduction

The Turvo Public API enables you to integrate and leverage Turvo's advanced logistics and supply chain management capabilities. Using the Public API, you can unlock real-time data access, streamline processes, and empower your applications with industry-leading logistics technology.

Turvo's Public API allows you to integrate with Turvo through RESTful methods that have predictable, resource-oriented URLs, and use HTTP response codes to indicate API errors.

To get started using the Turvo Public API, refer to our API Quick Start Guide. The API Quick Start Guide contains details that will help you build your first client quickly and use the API. 

Note: The Postman Collections for the Getting Started guide are attached at the end of this article. 

Prerequisites

Before you make the first API call, you must complete the steps in this section. After you complete the prerequisites, you can authenticate your API and make the first API call. The following steps guide you through the process of creating a customer, a carrier, and a shipment using the Turvo App. 

Note: The steps outlined below are using the Turvo UI and not the Public API to complete the following. 

Authenticating and making your first API call

Now that you’re done creating the customer, carrier, and shipment in the UI using the Turvo app, you can now proceed with authenticating your API requests.

To get started authenticating and making your first API call, refer to our API Quick Start Guide.

In the following section, we you will use Postman Collections to make your first few API calls. 

Using Postman to make your first API calls

In this tutorial, we will take the following approach to make your first few API calls. The user flow is illustrated below:

  1. Get an existing shipment
  2. Get an existing customer
  3. Update the status of an existing shipment
  4. Create a new customer
  5. Update the existing customer
  6. Create a new shipment

Get an existing shipment

In the previous section, “Authenticating and making your first API call”, you completed the authentication process and obtained your existing shipment.

Get an existing customer

The Get an Existing customer API is a GET call and it fetches all customer details. To get an existing customer, use the following API endpoint in the sandbox environment:

  • https://my-sandbox-publicapi.turvo.com/v1/customers/{customerId}

A customerId you can use is 746371. You can use the sandbox environment until you are ready to use the production environment. You can access this endpoint in both Sandbox and Production environments in our documentation here.

Update the status of a shipment

The Update the status of a shipment API is a PUT call, and it updates the status of an existing shipment. To update the status of an existing shipment, use the following API endpoint in the sandbox environment:

  • https://my-sandbox-publicapi.turvo.com/v1/shipments/status/{shipmentId}

You must specify the path and query parameters in the above URL endpoint.

Path Parameter

  • shipmentId: Turvo ID of the shipment for which the status needs to be updated. It is an integer and a ‘Required’ parameter.

Query Parameter

  • fullResponse: Flag on whether or not Turvo should return full response to your request. It is a boolean value.

You can access this endpoint in both Sandbox and Production environments in our documentation here.

Create a new customer

The Create a new customer API is a POST call, and it creates a new customer in Turvo. To create a new customer, use the following API endpoint in the sandbox environment:

  • https://my-sandbox.publicapi.turvo.com/v1/customers

You must specify the query parameters in the above URL endpoint.

Query Parameter

  • fullResponse: Flag on whether or not Turvo should return full response to your request. It is a boolean value.

You can access this endpoint in both Sandbox and Production environments in our documentation here.

Update an existing customer

The Update an existing customer API is a PUT call, and it updates an existing customer in Turvo. To update an existing customer, use the following API endpoint in the sandbox environment:

  • https://my-sandbox.publicapi.turvo.com/v1/customers/{customerId}

You must specify the path and query parameters in the above URL endpoint.

Path Parameter

  • customerId: The ID of the customer using which you can update the existing customer. It is an integer and a ‘Required’ parameter.

Note: You can use the same customerId which you’ve obtained in the Response body while creating a new customer API endpoint.

Query Parameter

  • fullResponse: Flag on whether or not Turvo should return full response to your request. It is a boolean value.

Request Body

In the Request body, we’ve specified only the object that needed to be updated in the existing customer, instead of specifying the entire customer object.

{
    "externalIds": [
        {
            "type": {
                "key": "erp_id",
                "value": "ERP ID"
            },
            "value": "12345",
            "_operation": 0
        }
    ]
}

You can access this endpoint in both Sandbox and Production environments in our documentation here.

Last step: Create a new shipment

The create a new shipment API is a POST call, and it creates a new shipment in Turvo. To create a new shipment, use the following API endpoint in the sandbox environment:

  • https://my-sandbox.publicapi.turvo.com/v1/shipments

You must specify the query parameters in the above URL endpoint.

Note: To successfully create your new shipment, you must specify the shipment location pick up and drop points. In essence, use the Location APIs (Location Pickup POST and Location Drop POST) provided to you in the Postman collections folder.

Query Parameter

  • fullResponse: A flag on if Turvo should return full response to your request. It is a boolean value.

You can access this endpoint in both Sandbox and Production environments in our documentation here.

Was this article helpful?

0 out of 0 found this helpful