Integration Requirements

REST API

Carriyo relies on APIs to integrate with the carrier system. Please note that we do not support batch or file-based integrations through FTP, EDI, or similar methods.

For seamless integration, we recommend utilising our REST API based on the Carriyo Plug & Play specification. This specification ensures smooth integration, but if you are unable to implement it, we can create a custom integration using your own API. In such cases, it is crucial to provide us with a clear specification in the form of an OAS (Open API Specification), along with clear examples to facilitate the integration process.

To simplify the setup for our clients, Carriyo implements a reusable connector for each carrier. This means that the connector can be utilised by any of our clients who wish to use the carrier service. To simplify the setup for our client, we kindly request the carrier to provide us with common API credentials that we can use across all of our clients.

Carriyo supports various authentication methods based on the carrier's requirements. The most commonly used methods include Basic Authentication, OAuth 2.0, or header-based API key authentication.

In the interest of security, we do not support clear text usernames and passwords in the request body.

Webhook Support

Carriyo is a platform that provides real-time visibility to its clients, and it relies on carriers to support real-time status updates through webhooks. When Carriyo receives status updates from the carrier, it processes them immediately.

To streamline the onboarding process for new clients using your service, we prefer a one-time webhook setup on your end. This setup should recognise shipments originating from Carriyo and automatically send real-time status updates to Carriyo for all such shipments.

The Carriyo Plug & Play specification provides details about the structure of the webhook payload. However, if you are unable to support the Carriyo Plug & Play specification and we have mutually agreed to develop a custom integration using your API, we can utilise your existing webhook structure. In this case, it is important that the payload contains the following information.

1. Tracking Number: carrier's unique tracking number to identify the shipment
2. Status Code: current status of the shipment
3. Status Change Date: date & time the status was changed
4. Current Location: current location of the shipment, including geo coordinates
5. Any additional details such as driver name, driver phone, recipient name, proof of delivery etc.