Telyport Logo
API docs by Redocly

Telyport API (2.0.0)

Download OpenAPI specification:Download

Introduction

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.

About Telyport Last Mile

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.

Accepted Package Sizes

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.

Delivery Urgency Levels

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.

SEND or RECEIVE

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.

Pricing

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.

Contact

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

Getting Started

Register your business on Telyport

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

Enable Development Access for a user of your business

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

Generate API Keys

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

Integration

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

Environment Base Endpoint
Test https://test-api.telyport.com/v2
Live https://api.telyport.com/v2

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

Name Type Description Optional
status string Status will be success No
message string Message of the request Yes
data object Data of the request No
requestTime ISO8601 DateTime Request time of the request No

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.

Name Type Description Optional
errors key: value List of keys that has errors in them Yes
message string Detail of the error Yes

example output:

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

API Error Format

Name Type Description Optional
status string Status will be error No
message string Message of the request Yes
code string Code of the Error No
requestTime ISO8601 DateTime Request time of the request No
details object Details of the Error Yes

API Error Responses

The following table lists the error codes

error code reason status code details *description
E001 api_key_not_found 401 further explanation of the error Api key must be provided as X-API-KEY header parameter
E002 API_KEY_INVALID 401 further explanation of the error Make sure that you have got the right API key for the environment and version you are using.
E003 invalid_request 400 further explanation of the error Request payload or parameters must be invalid
E004 internal_server_error 500 further explanation of the error Something went wrong on our end. Please try again later.
E005 endpoint_only_for_testing 401 further explanation of the error This endpoint is only available in testing environment
E101 order_not_found 404 further explanation of the error Given order id does not exist
E102 order_already_cancelled 400 further explanation of the error Given order is already cancelled
E103 order_placed_in_unserviceable_region 400 further explanation of the error Please check serviceability of your coordinates.
E104 order_requested_at_unserviceable_time 400 further explanation of the error Sorry, we are not available at this time. Please try some other time.
E105 order_user_not_found 400 further explanation of the error Make sure the user_id provided belongs to a user of your business.
E106 this_order_does_not_belong_to_your_business 403 further explanation of the error Make sure the order_id provided belongs to a order of your business.
E107 order_pick_and_drop_not_in_same_region 400 further explanation of the error Pickup and drop coordinates must be in same region.
E108 order_details_given_is_invalid 400 further explanation of the error Make sure the order details provided are valid.
E109 ORDER_TRANSACTION_NOT_FOUND 404 further explanation of the error Given order transaction id does not exist
E110 order_can_not_be_cancelled_at_current_state 400 further explanation of the error Order is not in a state where it can be cancelled.
E111 order_not_cancelled_due_to_failed_refund_process 400 further explanation of the error Order is not cancelled due to failed refund process.
E112 order_pack_size_is_not_valid 400 further explanation of the error Check if the provided pack type in payload is valid.
E113 collection_amount_not_acceptable 400 further explanation of the error Collection amount should be between 150 and 10000
E114 invalid_promo_code 400 further explanation of the error Invalid promo code
E115 order_ship_type_distance_not_acceptable 400 further explanation of the error Package size is not acceptable for given ship type
E116 order_id_not_provided 400 further explanation of the error Order id must be provided in request query params
E117 order_enterprise_ship_type_invalid 400 further explanation of the error Ship type invalid for enterprise user
E118 order_invalid_ship_type 400 further explanation of the error Invalid ship type requested
E119 order_pack_size_is_not_serviceable 400 further explanation of the error Pack size is not serviceable for given ship type
E120 order_invalid_phone_number 400 further explanation of the error Invalid phone numbers in request body
E121 order_missing_coordinates 400 further explanation of the error Missing coordinates in request body
E122 fund_accounts_not_set 400 further explanation of the error Fund accounts not set for business. To receive cash collection. Please set fund accounts in business console.
E123 primary_fund_account_not_set 400 further explanation of the error Primary fund account not set for business. To receive cash collection. Please set primary fund account in business console.
E124 order_invalid_payment_method 400 further explanation of the error Invalid payment method requested. Please check the paymentMode to be one of ['postpaid', 'wallet']
E125 no_agents_available_to_handle_cash_collection 400 further explanation of the error No agents available to handle cash collection at the moment.
E126 order_otps_invalid 400 further explanation of the error Provided OTPs are invalid.
E141 no_postpaid_access 403 further explanation of the error You do not have access to postpaid orders. Please reach out to us at info@telyport.com email.
E142 postpaid_limit_exceeded 400 further explanation of the error You have crossed your postpaid limit for this account.
E151 in_sufficient_wallet_balance 400 further explanation of the error Insufficient wallet balance. Please add money to your wallet. For testing you can manage your test wallets under development section of your dashboard.
E152 invalid_wallet_type 400 further explanation of the error Wallet type must be either "business" or "user"
E201 user_not_found 404 further explanation of the error Given user id does not exist
E301 could_not_load_route_for_given_coordinates 400 further explanation of the error No route found for given coordinates.
E302 source_and_destination_are_of_different_regions 400 further explanation of the error Source and destination coordinates must be in same region.
E303 source_or_destination_out_of_serviceable_area 400 further explanation of the error Source or destination coordinates are out of serviceable area.
E304 no_serviceable_ship_type_found_for_requested_params 400 further explanation of the error No serviceable ship type found for requested params.
E305 invalid_serviceability_request 400 further explanation of the error Invalid serviceability request. Please check the request params.
E306 agents_unavailable_in_proximity 400 further explanation of the error No agents available in proximity to pickup location. Please try again later or contact support.

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

Orders

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

Status Description Next possible statuses
'NEW' Order is created 'STARTED', 'CANCELLED'
'STARTED' Order is started 'PICKUPCOMPLETED', 'CANCELLED', 'NEW'
'PICKUPCOMPLETED' Order pickup completed 'DROPCOMPLETED', 'WH_DROP', 'RETURNED'
'WH_DROP' Order is dropped at warehouse 'WH_PICK', 'RETURNED'
'WH_PICK' Order is picked from warehouse 'DROPCOMPLETED', 'RETURNED'

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.)

Get Order Data

Authorizations:
apiKey
query Parameters
orderID
required
string

orderID of the order

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "requestTime": "2019-08-24T14:15:22Z",
  • "status": "success"
}

Cancel Order

Authorizations:
apiKey
Request Body schema: application/json
action
string
Enum: "return" "discard"

Required for orders after pickup. Use "return" (with charges) or "discard" (without charges)

comments
string

Additional comments for return/discard actions

orderID
required
string
Default: "IN0000000000000"

The order unique identifier

reason
required
string
Default: "any reason"

The reason of the cancellation

Responses

Request samples

Content type
application/json
{
  • "action": "return",
  • "comments": "string",
  • "orderID": "IN0000000000000",
  • "reason": "any reason"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "requestTime": "2019-08-24T14:15:22Z",
  • "status": "success"
}

Create order

This API is designed to streamline and standardize the process of creating orders for both postpaid and wallet payment methods. It supports the creation of orders for both types

Authorizations:
apiKey
Request Body schema: application/json
object

The bonus payment for the agent

brand
string
Default: ""

The brand name associated with the order

businessOrderID
string
Default: ""

The business order id of the order

collectionsAmount
number

The collections amount of the order

object

The customer support contact details

object (disableOTPVerification)
required
object

The drop location of the order

instructions
string
Default: ""

The instructions of the order

isRainTime
boolean
Default: false

The rain time status of the order

isReadyToShip
boolean
Default: true

The package ready to ship status of the order

orderType
required
string
Enum: "SEND" "RECEIVE"

The order type

object

OTPs for the order (string or null)

required
object

The package of the order

paymentMode
required
string
Enum: "wallet" "postpaid"

The payment mode of the order

required
object

The pickup location of the order

required
object

The receiver of the order

requestID
string
Default: ""

The request id of the order matching the requestID sent for serviceability check

scheduledTimestamp
integer

The scheduled IST epoch timestamp of the order

required
object

The sender of the order

shipType
required
string
Enum: "NOW" "RUSH" "XPRESS" "SAMEDAY" "STANDARD" "SAMEDAY_ENTERPRISE" "STANDARD_ENTERPRISE" "RUSH_ENTERPRISE" "XPRESS_ENTERPRISE" "NOW_ENTERPRISE"

The type of the shipping

userID
string
Default: ""

The user unique identifier will be defaulted to business admin.

walletType
string
Enum: "business" "user"

The wallet type for payment mode of wallet

Responses

Request samples

Content type
application/json
{
  • "bonusPayment": {
    },
  • "brand": "",
  • "businessOrderID": "",
  • "collectionsAmount": 0,
  • "customerSupportContact": {
    },
  • "disableOTPVerification": {
    },
  • "dropAddress": {
    },
  • "instructions": "",
  • "isRainTime": false,
  • "isReadyToShip": true,
  • "orderType": "SEND",
  • "otps": {
    },
  • "pack": {
    },
  • "paymentMode": "wallet",
  • "pickAddress": {
    },
  • "receiver": {
    },
  • "requestID": "",
  • "scheduledTimestamp": 0,
  • "sender": {
    },
  • "shipType": "NOW",
  • "userID": "",
  • "walletType": "business"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "requestTime": "2019-08-24T14:15:22Z",
  • "status": "success"
}

Create a Postpaid Order

Your business must have postpaid access to create postpaid orders. To enable postpaid access, please contact us. (See Contact details.)

Authorizations:
apiKey
Request Body schema: application/json
businessOrderID
string
Default: ""

The business order id of the order

collectionsAmount
number

The collections amount of the order

object (disableOTPVerification)
required
object

The drop location of the order

instructions
string
Default: ""

The instructions of the order

orderType
required
string
Enum: "SEND" "RECEIVE"

The order type

required
object

The package of the order

required
object

The pickup location of the order

required
object

The receiver of the order

scheduledTimestamp
integer

The scheduled IST epoch timestamp of the order

required
object

The sender of the order

shipType
required
string
Enum: "NOW" "RUSH" "XPRESS" "SAMEDAY" "STANDARD" "SAMEDAY_ENTERPRISE" "STANDARD_ENTERPRISE" "RUSH_ENTERPRISE" "XPRESS_ENTERPRISE" "NOW_ENTERPRISE"

The type of the shipping

userID
string
Default: ""

The user unique identifier

Responses

Request samples

Content type
application/json
{
  • "businessOrderID": "",
  • "collectionsAmount": 0,
  • "disableOTPVerification": {
    },
  • "dropAddress": {
    },
  • "instructions": "",
  • "orderType": "SEND",
  • "pack": {
    },
  • "pickAddress": {
    },
  • "receiver": {
    },
  • "scheduledTimestamp": 0,
  • "sender": {
    },
  • "shipType": "NOW",
  • "userID": ""
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "requestTime": "2019-08-24T14:15:22Z",
  • "status": "success"
}

Create a Wallet Order

You cannot place wallet orders with insufficient balance.

Use this link to load your business/user wallets: https://console.telyport.com/a/wallet

Use this link for testing/development purposes: https://console.telyport.com/a/api-and-webhook/manage-test-env

Note: On selection of user wallet, the order will be placed on behalf of the provided userID and hence, Money will be deducted from the users wallet. In case userID is not provided, the order will be placed on behalf of default user who is the first admin user of the business.

Authorizations:
apiKey
Request Body schema: application/json
businessOrderID
string
Default: ""

The business order id of the order

collectionsAmount
number

The collections amount of the order

object (disableOTPVerification)
required
object

The drop location of the order

instructions
string
Default: ""

The instructions of the order

orderType
required
string
Enum: "SEND" "RECEIVE"

The order type

required
object

The package of the order

required
object

The pickup location of the order

required
object

The receiver of the order

scheduledTimestamp
integer

The scheduled IST epoch timestamp of the order

required
object

The sender of the order

shipType
required
string
Enum: "NOW" "RUSH" "XPRESS" "SAMEDAY" "STANDARD" "SAMEDAY_ENTERPRISE" "STANDARD_ENTERPRISE" "RUSH_ENTERPRISE" "XPRESS_ENTERPRISE" "NOW_ENTERPRISE"

The type of the shipping

userID
string
Default: ""

The user unique identifier will be defaulted to business admin.

walletType
required
string
Enum: "business" "user"

The payment mode of the order

Responses

Request samples

Content type
application/json
{
  • "businessOrderID": "",
  • "collectionsAmount": 0,
  • "disableOTPVerification": {
    },
  • "dropAddress": {
    },
  • "instructions": "",
  • "orderType": "SEND",
  • "pack": {
    },
  • "pickAddress": {
    },
  • "receiver": {
    },
  • "scheduledTimestamp": 0,
  • "sender": {
    },
  • "shipType": "NOW",
  • "userID": "",
  • "walletType": "business"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "requestTime": "2019-08-24T14:15:22Z",
  • "status": "success"
}

Discard Order

Authorizations:
apiKey
Request Body schema: application/json
comments
string
Default: ""

Additional comments/notes for the discard

orderID
required
string
Default: "IN0000000000000"

The order unique identifier

reason
string
Default: "Damaged package"

The discard reason

Responses

Request samples

Content type
application/json
{
  • "comments": "",
  • "orderID": "IN0000000000000",
  • "reason": "Damaged package"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "requestTime": "2019-08-24T14:15:22Z",
  • "status": "success"
}

Mark Order Ready to Ship

Authorizations:
apiKey
query Parameters
orderID
required
string

orderID of the order

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "details": "string",
  • "message": "string",
  • "requestTime": "2019-08-24T14:15:22Z",
  • "status": "error"
}

Check wallet order payment status

You can use this API to pool for payment status for wallet orders. You will receive orderID after wallet payment is successful. Possible order payment statuses are as follows:

  • PENDING - Order is pending for payment
  • SUCCESS - Order is paid
  • FAILED - Order payment failed
Authorizations:
apiKey
path Parameters
temporaryOrderID
required
string

Temporary Order ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "requestTime": "2019-08-24T14:15:22Z",
  • "status": "success"
}

Return Order

Authorizations:
apiKey
Request Body schema: application/json
comments
string
Default: ""

Additional comments/notes for the return

orderID
required
string
Default: "IN0000000000000"

The order unique identifier

reason
string
Default: "Customer refused"

The return reason

Responses

Request samples

Content type
application/json
{
  • "comments": "",
  • "orderID": "IN0000000000000",
  • "reason": "Customer refused"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "requestTime": "2019-08-24T14:15:22Z",
  • "status": "success"
}

Get Shipping Label

Authorizations:
apiKey
query Parameters
orderID
required
string

orderID of the order

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "details": "string",
  • "message": "string",
  • "requestTime": "2019-08-24T14:15:22Z",
  • "status": "error"
}

Get Order Timeline

Following events are available in the order timeline with additional properties

Event name Additional properties
ORDER_CREATED None
AGENT_ACCEPTED_ORDER agentDetails
PICK_DONE agentDetails, taskCompleteDetails
DROP_DONE agentDetails, taskCompleteDetails
RETURN_DONE agentDetails, taskCompleteDetails
WAREHOUSE_PICK_DONE warehouseDetails
WAREHOUSE_DROP_DONE warehouseDetails
RETURN_INITIATED returnDetails
ORDER_CANCELLED cancellationDetails
DROP_FAILED orderFailDetails
PICK_FAILED orderFailDetails
RESCHEDULED rescheduleDetails
REATTEMPT reattemptDetails

Note: You can find the schema for the additional properties in the success response schema below.

Authorizations:
apiKey
query Parameters
orderID
required
string

orderID of the order

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "requestTime": "2019-08-24T14:15:22Z",
  • "status": "success"
}

Update order details post-creation

Allows updating:

  • OTPs (pick, drop, rto) with validation based on order status
  • COD payment amount and status with automatic recalculation of commissions and taxes
  • Business order ID / reference ID
Authorizations:
apiKey
Request Body schema: application/json
businessOrderID
string

The business order ID / reference ID to update

object

COD payment details to update

isRainTime
boolean
Default: false

The rain time status of the order

orderID
required
string

The order id of the order to update

object

OTPs to update

Responses

Request samples

Content type
application/json
{
  • "businessOrderID": "string",
  • "codPayment": {
    },
  • "isRainTime": false,
  • "orderID": "string",
  • "otps": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "requestTime": "2019-08-24T14:15:22Z",
  • "status": "success"
}

Services

Service related operations

Last mile serviceability

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "requestTime": "2019-08-24T14:15:22Z",
  • "status": "success"
}

Pricing Estimate

Authorizations:
apiKey
Request Body schema: application/json
required
object
Default: {"lat":12.9181,"lng":77.6199}

Destination coordinates

required
object
Default: {"lat":12.9121,"lng":77.6139}

Origin coordinates

Responses

Request samples

Content type
application/json
{
  • "destination": {
    },
  • "origin": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "requestTime": "2019-08-24T14:15:22Z",
  • "status": "success"
}

Serviceability

This API will return the available ship types and their respective package sizes, along with the delivery time, charges, and a description of the service.

To use this API, you need to provide either the coordinates or the address of the pickup and drop-off locations. If you provide both, the API will prioritize the coordinates and ignore the address.

When specifying the package size, you have the option to provide the package weight, dimensions, or the Telyport package size. If you provide the Telyport package size, the API will consider it and ignore the weight and dimensions.

Authorizations:
apiKey
Request Body schema: application/json
fromAddress
string

From address

object

From coordinates

fromPincode
string

From pincode

object

Package dimensions, (allowed units values: "cm", "mm", "inch")

object

Package weight

requestID
string

Request ID to map serviceability requests with order creation requests

scheduleOrderAt
string

Schedule order at string

shipTypes
Array of strings

Ship types (allowed values: ['NOW', 'RUSH', 'XPRESS', 'SAMEDAY', 'STANDARD', 'SAMEDAY_ENTERPRISE', 'STANDARD_ENTERPRISE', 'RUSH_ENTERPRISE', 'XPRESS_ENTERPRISE', 'NOW_ENTERPRISE'])

toAddress
string

To address

object

To coordinates

toPincode
string

To pincode

tpPackageSizes
Array of strings

list of predefined telyport package sizes

Responses

Request samples

Content type
application/json
{
  • "fromAddress": "1229, HSR Layout, Bangalore, Karnataka,",
  • "fromCoordinates": {
    },
  • "fromPincode": "560102",
  • "packageDimensions": {
    },
  • "packageWeight": {
    },
  • "requestID": "string",
  • "scheduleOrderAt": "2023-08-04T12:00:00+05:30",
  • "shipTypes": [
    ],
  • "toAddress": "1229, HSR Layout, Bangalore, Karnataka,",
  • "toCoordinates": {
    },
  • "toPincode": "560102",
  • "tpPackageSizes": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "requestTime": "2019-08-24T14:15:22Z",
  • "status": "success"
}

Users

Users related operations

Get all users

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "requestTime": "2019-08-24T14:15:22Z",
  • "status": "success"
}

Webhooks

Introduction

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.

Supported Events

Note : More events will be added in the future.

Event Description
ORDER.CREATED Triggered when a new order is created.
ORDER.STATUS_UPDATED Triggered when the status of an order is updated.
AGENT.LOCATION_UPDATES Real-time streaming of agent location updates for active orders.

Webhook Request Format

Name Type Description Optional
event string Name of the event No
data object Data of the event will differ for every event No
timestamp ISO8601 DateTime Timestamp of the event No

Example request body:

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

Webhook Response

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

Webhook Retry

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.

Webhook Signature

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)

Webhook callback for order creation Webhook

This webhook is called when an order is created

Request Body schema: application/json
object
event
string
Value: "ORDER.CREATED"

Event type ORDER.CREATED

timestamp
integer

Epoch timestamp

webhookEventID
string

Webhook event ID

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "event": "ORDER.CREATED",
  • "timestamp": 0,
  • "webhookEventID": "string"
}

Webhook callback for order status update Webhook

This webhook is triggered whenever there is an update to the status of an order.

Webhook URL

The URL to which the webhook will be sent is configured in the business settings on the Business Dashboard.

Supported Status Updates

The webhook status update is triggered for the following status updates:

Status Description Possible Next Statuses
NEW The order has been created. STARTED, CANCELLED
STARTED The order has been assigned and accepted by an agent. PICKUPREACHED, CANCELLED
PICKUPREACHED The agent has reached the pickup location. PICKUPCOMPLETED, CANCELLED
PICKUPCOMPLETED The pickup of the order has been completed. WH_DROP, DROPREACHED, RETURN_INITIATED, DISCARDED
WH_DROP The order has been dropped at the warehouse. WH_PICK, RETURN_INITIATED, DISCARDED
WH_PICK The order has been picked up from the warehouse. DROPREACHED, RETURN_INITIATED, DISCARDED
DROPREACHED The agent has reached the drop-off location. DROPCOMPLETED, DISCARDED
DROPCOMPLETED The order has been successfully delivered to the final destination. -
RETURN_INITIATED The return process for the order has been initiated. RETURNED
RETURNED The order has been returned to the sender. -
CANCELLED The order has been cancelled. -
DISCARDED The order has been discarded (e.g., damaged, lost). -

Additional Properties

The webhook payload includes an additionalProperties object that provides context-specific information based on the order status. This helps you understand what happened and who was involved in each status update.

Agent Information Statuses

These statuses include information about the assigned agent:

STARTED, PICKUPREACHED, PICKUPCOMPLETED, DROPREACHED

When an order reaches any of these statuses, you'll receive the following agent details:

"additionalProperties": {
  "agentName": "John Doe",
  "agentPhone": "9876543210",
  "agentCode": "AG12345",
  "agentLocation": {
    "lat": 12.9716,
    "lng": 77.5946,
    "timestamp": 1739365639201,
    "bearing": 45.5
  }
}

Fields:

  • agentName (string): Full name of the assigned agent
  • agentPhone (string): Contact phone number of the agent
  • agentCode (string): Unique identifier code for the agent
  • agentLocation (object): Real-time location of the agent
    • lat (number): Latitude coordinate
    • lng (number): Longitude coordinate
    • timestamp (number): Unix timestamp (milliseconds) when location was recorded
    • bearing (number): Direction the agent is heading (0-360 degrees)

Delivery Completion Status

DROPCOMPLETED

When an order is successfully delivered, you'll receive agent details along with complete payment information:

"additionalProperties": {
  "agentName": "John Doe",
  "agentPhone": "9876543210",
  "agentCode": "AG12345",
  "agentLocation": {
    "lat": 12.9716,
    "lng": 77.5946,
    "timestamp": 1739365639201,
    "bearing": 45.5
  },
  "paymentInfo": {
    "deliveryCharge": 50.0,
    "gst": 9.0,
    "totalCharge": 59.0
  }
}

Additional Fields:

  • paymentInfo (object): Complete payment breakdown
    • deliveryCharge (number): Base delivery fee before taxes
    • gst (number): GST amount applied
    • totalCharge (number): Total delivery charges including all taxes

Return Statuses

RETURN_INITIATED

When a return is initiated, you'll receive the reason for the return:

"additionalProperties": {
  "reasonCode": "WRONG_ORDER",
  "reason": "Customer refused to accept the order since it was the wrong order."
}

Fields:

  • reasonCode (string): Code representing the return reason
  • reason (string): Detailed explanation of the return reason

Possible Return Reason Codes:

reasonCode reason
WRONG_ORDER Customer refused to accept the order since it was the wrong order.
UNREACHABLE Customer cannot be reached and address cannot be found.
REFUSED Customer doesn't want to accept the order.
REQUESTED_RETURN Customer requested return.
COD_REFUSED Customer doesn't want to pay cash on delivery.
DELAYED_DELIVERY Customer refused to accept due to delayed delivery.
AGENT_ISSUE Agent cannot complete it due to accident, vehicle issue, law enforcement, or other issues.

RETURNED

When an order is successfully returned, you'll receive agent details, payment information, return charges, and the return reason:

"additionalProperties": {
  "agentName": "John Doe",
  "agentPhone": "9876543210",
  "agentCode": "AG12345",
  "agentLocation": {
    "lat": 12.9716,
    "lng": 77.5946,
    "timestamp": 1739365639201,
    "bearing": 45.5
  },
  "paymentInfo": {
    "deliveryCharge": 50.0,
    "gst": 9.0,
    "totalCharge": 59.0,
    "returnCharge": 50.0
  },
  "returnReason": {
    "reasonCode": "WRONG_ORDER",
    "reason": "Customer refused to accept the order since it was the wrong order."
  }
}

Additional Fields:

  • paymentInfo (object): Complete payment breakdown including return charges
    • deliveryCharge (number): Base delivery fee before taxes
    • gst (number): GST amount applied
    • totalCharge (number): Total delivery charges including all taxes
    • returnCharge (number): Additional charges for the return
  • returnReason (object): Details about why the order was returned
    • reasonCode (string): Code representing the return reason
    • reason (string): Detailed explanation

Cancellation Status

CANCELLED

When an order is cancelled, you'll receive information about who cancelled it and why:

"additionalProperties": {
  "reason": "Customer requested cancellation",
  "comments": "Customer changed their mind",
  "cancelledByUserType": "user",
  "cancelledByUserID": "USR123456",
  "cancelledByUserName": "Jane Smith"
}

Fields:

  • reason (string): Primary reason for cancellation
  • comments (string): Additional comments or notes about the cancellation
  • cancelledByUserType (string): Type of user who cancelled the order
    • Telyport_admin: Cancelled by Telyport admin
    • user: Cancelled by the customer
    • System: Automatically cancelled by the system
  • cancelledByUserID (string, optional): Unique ID of the user who cancelled
  • cancelledByUserName (string, optional): Name of the user who cancelled

Discard Status

DISCARDED

When an order is discarded (e.g., package damaged, lost, or cannot be delivered), you'll receive information about why it was discarded:

"additionalProperties": {
  "reasonCode": "DAMAGED",
  "reason": "Package was damaged during transit and cannot be delivered"
}

Fields:

  • reasonCode (string): Code representing the discard reason
    • Common codes: DAMAGED, LOST, UNDELIVERABLE, EXPIRED, QUALITY_ISSUE
  • reason (string): Detailed explanation of why the order was discarded

Webhook Payload Examples

Example 1: Order Started

{
  "timestamp": 1739365639201,
  "event": "ORDER.STATUS_UPDATED",
  "data": {
    "orderID": "IN250212151234",
    "status": "STARTED",
    "updatedAt": 1739365639201,
    "additionalProperties": {
      "agentName": "John Doe",
      "agentPhone": "9876543210",
      "agentCode": "AG12345",
      "agentLocation": {
        "lat": 12.9716,
        "lng": 77.5946,
        "timestamp": 1739365639201,
        "bearing": 45.5
      }
    },
    "businessOrderID": "#547455"
  },
  "webhookEventID": "29RZXABCDtzk4Uxj"
}

Example 2: Order Delivered (Drop Completed)

{
  "timestamp": 1739368239201,
  "event": "ORDER.STATUS_UPDATED",
  "data": {
    "orderID": "IN250212151234",
    "status": "DROPCOMPLETED",
    "updatedAt": 1739368239201,
    "additionalProperties": {
      "agentName": "John Doe",
      "agentPhone": "9876543210",
      "agentCode": "AG12345",
      "agentLocation": {
        "lat": 12.9716,
        "lng": 77.5946,
        "timestamp": 1739368239201,
        "bearing": 45.5
      },
      "paymentInfo": {
        "deliveryCharge": 50.0,
        "gst": 9.0,
        "totalCharge": 59.0
      }
    },
    "businessOrderID": "#547455"
  },
  "webhookEventID": "30SZYBCDEuzl5Vyk"
}

Example 3: Order Returned

{
  "timestamp": 1739370839201,
  "event": "ORDER.STATUS_UPDATED",
  "data": {
    "orderID": "IN250212151234",
    "status": "RETURNED",
    "updatedAt": 1739370839201,
    "additionalProperties": {
      "agentName": "John Doe",
      "agentPhone": "9876543210",
      "agentCode": "AG12345",
      "agentLocation": {
        "lat": 12.9716,
        "lng": 77.5946,
        "timestamp": 1739370839201,
        "bearing": 45.5
      },
      "paymentInfo": {
        "deliveryCharge": 50.0,
        "gst": 9.0,
        "totalCharge": 59.0,
        "returnCharge": 50.0
      },
      "returnReason": {
        "reasonCode": "WRONG_ORDER",
        "reason": "Customer refused to accept the order since it was the wrong order."
      }
    },
    "businessOrderID": "#547455"
  },
  "webhookEventID": "31TZACDEFvam6Wzl"
}

Example 4: Order Cancelled

{
  "timestamp": 1739365700000,
  "event": "ORDER.STATUS_UPDATED",
  "data": {
    "orderID": "IN250212151234",
    "status": "CANCELLED",
    "updatedAt": 1739365700000,
    "additionalProperties": {
      "reason": "Customer requested cancellation",
      "comments": "Customer changed their mind",
      "cancelledByUserType": "user",
      "cancelledByUserID": "USR123456",
      "cancelledByUserName": "Jane Smith"
    },
    "businessOrderID": "#547455"
  },
  "webhookEventID": "32UABDEFGwbn7Xam"
}

Example 5: Order Discarded

{
  "timestamp": 1739371500000,
  "event": "ORDER.STATUS_UPDATED",
  "data": {
    "orderID": "IN250212151234",
    "status": "DISCARDED",
    "updatedAt": 1739371500000,
    "additionalProperties": {
      "reasonCode": "DAMAGED",
      "reason": "Package was damaged during transit and cannot be delivered"
    },
    "businessOrderID": "#547455"
  },
  "webhookEventID": "33VBCEFGHxco8Ybn"
}
Request Body schema: application/json
object
event
string
Value: "ORDER.STATUS_UPDATED"

Event name ORDER.STATUS_UPDATED

orderID
string

Order ID

status
string

Order status

timestamp
integer

Epoch timestamp

webhookEventID
string

Webhook event ID

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "event": "ORDER.STATUS_UPDATED",
  • "orderID": "string",
  • "status": "string",
  • "timestamp": 0,
  • "webhookEventID": "string"
}

Webhook callback for agent location updates Webhook

This webhook provides real-time streaming of agent location updates for all active orders assigned to agents. It allows you to track the live location of delivery agents handling your orders.

Webhook URL

The URL to which the webhook will be sent is configured in the business settings on the Business Dashboard.

When is this webhook triggered?

This webhook is triggered periodically (approximately every 5 seconds) for all orders that:

  • Have an agent assigned
  • Are in an active/in-transit status (not in completed states like DROPCOMPLETED, CANCELLED, RETURNED, or DISCARDED)

Active Order Statuses

The webhook streams location updates for orders in the following statuses:

Status Description
ASSIGNED Order has been assigned to an agent
REASSIGNED Order has been reassigned to a different agent
STARTED Agent has accepted and started working on the order
PICKUPREACHED Agent has reached the pickup location
PICKUPCOMPLETED Agent has completed the pickup
WH_ASSIGN Order assigned for warehouse operations
WH_PICK_STARTED Warehouse pickup has started
WH_PICK Order picked up from warehouse
DROPREACHED Agent has reached the drop-off location
RETURN_INITIATED Return process has been initiated

Note: Once an order reaches a terminal state (DROPCOMPLETED, CANCELLED, RETURNED, or DISCARDED), location updates will no longer be sent for that order.

Webhook Payload Structure

The webhook payload contains an array of agent location updates, with each entry representing one active order.

Payload Fields

Field Type Description
timestamp number Unix timestamp (milliseconds) when the webhook was triggered
event string Always AGENT.LOCATION_UPDATES
data object Container for the location update data
data.agents_location_updates array Array of agent location objects
data.updateCount number Total number of location updates in this payload
webhookEventID string Unique identifier for this webhook event

Agent Location Object

Each object in the agents_location_updates array contains:

Field Type Description
orderID string Unique identifier for the order
agentCode string Unique code identifying the agent
orderStatus string Current status of the order
location object Agent's current location data
location.lat number Latitude coordinate
location.lng number Longitude coordinate
location.timestamp number Unix timestamp (milliseconds) when location was recorded
location.bearing number Direction the agent is heading (0-360 degrees)

Webhook Payload Example

Single Order Update

{
  "timestamp": 1739365639201,
  "event": "AGENT.LOCATION_UPDATES",
  "data": {
    "agents_location_updates": [
      {
        "orderID": "IN250212151234",
        "agentCode": "AG12345",
        "orderStatus": "STARTED",
        "location": {
          "lat": 12.9716,
          "lng": 77.5946,
          "timestamp": 1739365639150,
          "bearing": 45.5
        }
      }
    ],
    "updateCount": 1
  },
  "webhookEventID": "29RZXABCDtzk4Uxj"
}

Multiple Orders Update

{
  "timestamp": 1739365639201,
  "event": "AGENT.LOCATION_UPDATES",
  "data": {
    "agents_location_updates": [
      {
        "orderID": "IN250212151234",
        "agentCode": "AG12345",
        "orderStatus": "PICKUPREACHED",
        "location": {
          "lat": 12.9716,
          "lng": 77.5946,
          "timestamp": 1739365639150,
          "bearing": 45.5
        }
      },
      {
        "orderID": "IN250212151235",
        "agentCode": "AG12346",
        "orderStatus": "DROPREACHED",
        "location": {
          "lat": 12.9820,
          "lng": 77.6050,
          "timestamp": 1739365639145,
          "bearing": 120.0
        }
      },
      {
        "orderID": "IN250212151236",
        "agentCode": "AG12345",
        "orderStatus": "STARTED",
        "location": {
          "lat": 12.9716,
          "lng": 77.5946,
          "timestamp": 1739365639150,
          "bearing": 45.5
        }
      }
    ],
    "updateCount": 3
  },
  "webhookEventID": "30SZYBCDEuzl5Vyk"
}

Use Cases

Real-time Order Tracking

Display live agent locations on a map for customers to track their deliveries in real-time.

Fleet Management

Monitor all active deliveries and agent positions for operational oversight and route optimization.

ETA Calculations

Calculate accurate estimated time of arrival based on agent's current location and movement.

Customer Notifications

Send proactive notifications to customers when agents are approaching pickup or delivery locations.

Important Notes

  1. Frequency: This webhook is triggered approximately every 5 seconds for all active orders
  2. Volume: If you have many active orders, you may receive frequent webhook calls with multiple location updates
  3. Filtering: Only orders with assigned agents in active statuses are included
  4. Same Agent, Multiple Orders: If an agent is handling multiple orders, each order will have a separate entry in the array with the same agent location
  5. Location Accuracy: Location data depends on the agent's device GPS accuracy and network connectivity
  6. Webhook Signature: Always verify the webhook signature using the X-Telyport-Signature header (see main webhook documentation)

Response

Return any 2xx status code to indicate successful receipt of the webhook. If a non-2xx status is returned, this webhook will not be retried.

Request Body schema: application/json
object
event
string
Value: "AGENT.LOCATION_UPDATES"

Event name AGENT.LOCATION_UPDATES

timestamp
integer

Epoch timestamp in milliseconds

webhookEventID
string

Webhook event ID

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "event": "AGENT.LOCATION_UPDATES",
  • "timestamp": 0,
  • "webhookEventID": "string"
}