NOTE This is documentation for version 2 of Telyport apis. If you are looking for version 1, Please visit here. Please use version 2 for any new development.

We are an in-city delivery as a service platform that connects couriers with customers and businesses to empower time sensitive delivery. We apply technology to create a reliable, efficient, scalable and cost-effective hyperlocal delivery infrastructure for locals and businesses.

Telyport gives you the ability to select package size, which allows you to pay for what you use and also, this lets us pool certain orders to reduce overall shipment cost.

• X-Small: A Package that fits in a cereal box and weighs less than 0.5 kg. Approximate measurement 17 × 17 × 10 cm.

• Small: A Package that fits in a shoebox and weighs less than 3 kg. Approximate measurement 34 × 32 × 10 cm.

• Medium: A Package that fits in a handbag and weighs less than 7 kg. Approximate measurement 34 × 32 × 20 cm.

• Large: A Package that fits in a Laundry bag and weighs less than 15 kg. Approximate measurement 42 × 36 × 37 cm.

• X-Large: A Package that fits in a compact suitcase and weighs less than 25 kg. Approximate measurement 54 × 38 × 38 cm.

• XX-Large: A Package that fits in a large suitcase and weighs less than 50 kg. Approximate measurement 67 × 45 × 37 cm.

• Quarter-truck-load: A Package that fits in a quarter truck and weighs less than 200 kg. Approximate measurement 125 × 110 × 95 cm.

• Half-truck-load: A Package that fits in a half truck and weighs less than 350 kg. Approximate measurement 145 × 125 × 110 cm.

• Full-truck-load: A Package that fits in a full truck and weighs less than 750 kg. Approximate measurement 245 × 145 × 120 cm.

Telyport gives you the ability to select delivery urgency level, which allows you to pay for what you use and also, this lets us pool certain orders to reduce overall shipment cost.

• Now: A Package that needs to be picked and dropped at priority.

• Rush: A Package that needs to be picked and dropped within 2 hours of booking.

• Xpress: A Package that needs to be picked and dropped within 4 hours of booking.

• Sameday: A Package that needs to be picked and dropped on the same day of booking.

• standard: A Package that is not urgent and can be delivered within 24 hours.

Whether you are an individual or a business, choose a type of delivery that fits your needs. By using Telyport you can either send or receive a package.

Our pricing model is dynamic which means that the price of a delivery is determined by the size of the package, the urgency of the delivery, weather conditions in the region, and the distance between the pickup and dropoff locations.

Business Charges

Telyport can handle your payments with your customers by charging a handling fee of 3% on your business charges.

If you have any queries on using Telyport APIs, please drop an email at info@telyport.com, and we will get back to you.

To start using Telyport APIs, you need to register your business on Telyport. You can register your business by visiting https://console.telyport.com/register

To Manage API keys and Webhooks. You need to have development access to your business account. You can add a developer access to a user by visiting https://console.telyport.com/a/user-management

To use Telyport APIs, you need to generate API keys. You can generate API keys by visiting https://console.telyport.com/a/api-and-webhook

API Keys

Use Test key for development and testing the integration in staging environment. Once you are ready to go live, use Live key for production environment.

API Base Endpoints

API Requests

All requests to Business API must be made via HTTPS. POST, PUT, and, PATCH requests should send all parameters in the body of the request in JSON format and UTF-8 encoding; GET requests should send parameters in the query string.

All requests must include an HTTP header X-Api-Key with the value of your API key.

X-Api-Key is a mandatory header for all requests. You have to pass in the API key generated from API and webhooks section of the console. If you do not include this header, you will receive a 401 Unauthorized response.

API Success Responses Format

All the success response will have a JSON body with the following structure:

{
 "status": "success",
 "message": "Message",
 "data": {},
"requestTime": "2020-05-20T12:00:00.000Z"
}

API Request Validation Errors

Status code of such errors will be 400.

example output:

{
 "errors": {
 "pickupLocation": "'Pickup' is required property",
 "dropoffLocation": "'Dropoff' is required property"
 },
 "message": "Input payload validation failed"
}

API Error Format

API Error Responses

The following table lists the error codes

*description: This is just a brief of the error. This will not be returned in the response.

About orders

• Following order APIs can be used to place hyperlocal orders only.
• Orders can be placed on behalf of any user by providing userID in the request body. If userID is not provided, the order will be placed on behalf of default user who is the first admin user of the business.
• Package sizes is required to be accurate because it will help us to assign an agent who is capable of carrying the package.
• Maximum liability for an order will be INR 1500
• Maximum package size for an order will be 15kg

Order status flow

Note: Enterprise businesses can't use regular ship_types. Append _ENTERPRISE to the ship types instead. You can only use the enterprise ships that are set to your business. If you want to use other enterprise ship_types, please contact us. Contact details.)

Service related operations

Users related operations

Webhooks allow you to receive real-time updates from Telyport. You can subscribe to the events you want to receive and Telyport will send a POST request to your webhook URL whenever an event occurs. You get updates for all the orders irrespective of the channel through which they were placed.

You can manage webhooks from the API and Webhooks section of the console.

Note : More events will be added in the future.

Example request body:

{
    "event": "ORDER.CREATED",
    "data": {
        "orderID": "IN123456789",
        "temporaryOrderID": "IN123456789",
        "businessOrderID": "1234",
        "status": "NEW",
    }
}

Return any 200 status to indicate that the data was received successfully.

Telyport will retry sending the webhook request if it fails to receive a 200 status code. The retry interval will increase exponentially until it reaches 35 minutes. After that, It will be marked as failed and you will have to manually retry it from the console. If none of the events are successful for 3 days, the webhook will be deactivated. You will have to manually activate it from the console.

Telyport will sign the webhook request body with your webhook secret. You can verify the signature by using the X-Telyport-Signature header.

Signature is generated using HMAC-SHA256 algorithm with hex digest. We use the request body as the message and the webhook secret as the key. Here's an example of how to verify the signature in Node.js and Python.

Node.js

const crypto = require('crypto');

const verifySignature = (body, signature, secret) => {
    const hmac = crypto.createHmac('sha256', secret);
    const digest = Buffer.from(hmac.update(body).digest('hex'), 'utf8');
    const checksum = Buffer.from(signature, 'utf8');
    return crypto.timingSafeEqual(digest, checksum);
};

Python

import hmac
import hashlib

def verify_signature(body, signature, secret):
    digest = hmac.new(secret.encode('utf-8'), body.encode('utf-8'), hashlib.sha256).hexdigest()
    return hmac.compare_digest(digest, signature)