How Courier Integration Works

Understand how external couriers connect to and operate within Deliverty Hub.

What Are External Couriers?

External couriers are third-party delivery providers that organizations can activate within Deliverty Hub. Rather than relying solely on their own delivery agents, organizations can connect to external courier services to expand their delivery capacity and coverage area.

When an organization activates an external courier, Deliverty Hub handles the communication between the organization's task management workflow and the courier's delivery infrastructure, whether through a direct API integration or a deployed plugin.

Courier Statuses

Every registered courier in the system has a status that determines whether it can accept delivery tasks.

Status Description Can Accept Tasks?
ACTIVE The courier is fully operational and available for task assignment. Yes
PENDING The courier has been registered but is waiting for approval from the Deliverty team. No
BLOCKED The courier has been blocked and cannot accept any new tasks. No
IN_REVIEW The courier is currently under review (e.g., after a configuration change or incident). No
Status Transitions

A newly registered courier starts in PENDING status. Once verified by the Deliverty team, it moves to ACTIVE. A courier can be moved to IN_REVIEW or BLOCKED at any time by an administrator.

API Authentication Types

When integrating via API (Option A), you configure how Deliverty Hub authenticates with your service. There are four supported authentication types and three delivery locations for your credentials.

Auth Types

Auth Type Description
API_KEY A static API key provided by your service. Deliverty sends it with each request.
OAUTH OAuth-based authentication using client credentials or token exchange.
BASIC HTTP Basic authentication with a username and password pair.
BEARER A bearer token sent in the Authorization header.

Credential Delivery Location

You specify where in each HTTP request the credentials should be placed:

Location Description
HEADER Credentials are sent as an HTTP header (e.g., Authorization: Bearer <token>).
QUERY Credentials are appended as a query parameter (e.g., ?api_key=abc123).
BODY Credentials are included in the request body payload.

Per-Organization Credentials

Deliverty Hub is a multi-tenant platform. Each organization that activates your courier service provides its own set of API credentials. This means:

  • Organization A might use API key abc-123 for your service.
  • Organization B might use API key xyz-789 for the same service.
  • Credentials are stored securely and scoped to each organization.
  • When Deliverty Hub dispatches a task, it uses the credentials of the organization that owns that task.
Why Per-Organization?

This design allows you (as a courier provider) to offer different service tiers, billing accounts, or rate limits to different organizations, all while using a single integration with Deliverty Hub.

Availability Schedules

External couriers can define availability schedules that specify which days and hours they operate. The schedule supports day-of-week granularity (Monday through Sunday), allowing couriers to indicate:

  • Which days of the week they accept deliveries.
  • Operating hours for each day (start time and end time).
  • Different hours for different days (e.g., shorter hours on weekends).

When an organization attempts to assign a task to an external courier, Deliverty Hub checks the courier's availability schedule. If the courier is outside their operating hours, the system can flag this to the organization or prevent the assignment.

Task Routing

When an organization selects an external courier for a delivery task, Deliverty Hub routes the task through the following flow:

1

Organization Selects Courier

An admin or the system assigns a task to an external courier that the organization has activated.

2

Credentials Retrieved

Deliverty Hub retrieves the organization's specific API credentials for that courier.

3

Dispatch via API or Plugin

The system calls the courier's API endpoint (Option A) or invokes the courier's plugin createTask() method (Option B) to dispatch the delivery.

4

Status Updates Flow Back

The courier sends status updates (via webhooks or polling), and Deliverty Hub updates the task status for the organization and their customers.

↑↓ Navigate ↵ Open Esc Close