API docs by Redocly

4klyft API (1.0.0)

Download OpenAPI specification:

4klyft API Support: support@4klyft.com License: Proprietary

Logistics operations API for the 4klyft platform.

Overview

This API provides comprehensive endpoints for managing:

  • Routes & Execution: Create, manage, and execute delivery routes
  • Shipments & Loads: Track shipments from pickup to delivery
  • Fleet Management: Manage carriers, vehicles, and drivers
  • Proof of Delivery: Capture signatures, photos, and delivery confirmations
  • Settings: Configure system-wide and tenant-specific settings
  • Webhooks: Subscribe to real-time event notifications
  • Analytics: Access delivery performance metrics and reports

Authentication

All API endpoints (except /api/docs and /api/v1/iam/auth/*) require JWT Bearer token authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Rate Limiting

API requests are rate-limited to ensure fair usage. Standard limits are:

  • 1000 requests per minute for read operations
  • 100 requests per minute for write operations

Error Handling

The API uses RFC 7807 Problem Details for error responses.

Shipping Carriers

Represents a shipment moving through the logistics pipeline.

Shipments are assigned to routes for delivery and track the full lifecycle from creation to delivery.

Types:

  • ftl: Full Truckload — client contracts for exclusive vehicle use
  • ltl: Less Than Truckload — shared space with other shipments

List supported carrier providers

Returns the carrier provider registry that drives the carrier-creation picker.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "member": [
    ]
}

Check whether a provider has platform-shared credentials configured

Returns only whether a shared account is configured. The secret config is never returned.

Authorizations:
Bearer
path Parameters
type
required
string

CarrierPlatformCredential identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "type": "ups",
  • "configured": true
}

Configure a provider's platform-shared credentials

Validates the supplied credentials against the provider's credential-field schema and stores them encrypted. Write-only — the secret is never echoed back.

Authorizations:
Bearer
path Parameters
type
required
string

CarrierPlatformCredential identifier

Request Body schema:
required

The updated CarrierPlatformCredential resource

object

Provider credential config/secrets keyed by the provider's declared credential-field keys. Write-only — never returned.

Responses

Request samples

Content type
{
  • "credentials": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "type": "ups",
  • "configured": true
}

List external carriers

Retrieve a paginated list of external shipping providers.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Register an external carrier

Register an external carrier

Authorizations:
Bearer
Request Body schema:
required

The new Carrier resource

code
required
string [ 2 .. 64 ] characters
type
required
string
Default: "custom"
Enum: "ups" "dhl" "fedex" "usps" "sendcloud" "custom" "internal"
credentialScope
string or null
Value: "tenant"

Credential model — tenant (bring-your-own account) for external providers, or null for the internal/self carrier. The platform scope is excluded here on purpose (finding H4); platform carriers are provisioned out-of-band, never minted on demand through this tenant endpoint.

environment
string
Default: "sandbox"
Enum: "sandbox" "production"

Provider environment — "sandbox" (test upstream, the default) or "production" (live upstream). Opting into production is deliberate.

object

BYO provider keys/secrets/config — required only for tenant scope.

name
string or null <= 255 characters

Display name — required for the custom provider, inherited otherwise.

capabilities
Array of strings

Capabilities — custom provider only.

coverage
Array of strings

Coverage as ISO 3166-1 alpha-2 country codes — custom provider only.

Responses

Request samples

Content type
{
  • "code": "string",
  • "type": "ups",
  • "credentialScope": "tenant",
  • "environment": "sandbox",
  • "credentials": {
    },
  • "name": "string",
  • "capabilities": [
    ],
  • "coverage": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "UPS-PRIMARY",
  • "name": "UPS",
  • "type": "ups",
  • "isInternal": false,
  • "credentialScope": "platform",
  • "environment": "sandbox",
  • "status": "active",
  • "capabilities": [
    ],
  • "serviceLevels": [
    ],
  • "coverage": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get an external carrier

Get an external carrier

Authorizations:
Bearer
path Parameters
id
required
string

Carrier identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "UPS-PRIMARY",
  • "name": "UPS",
  • "type": "ups",
  • "isInternal": false,
  • "credentialScope": "platform",
  • "environment": "sandbox",
  • "status": "active",
  • "capabilities": [
    ],
  • "serviceLevels": [
    ],
  • "coverage": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Update an external carrier

Update an external carrier

Authorizations:
Bearer
path Parameters
id
required
string

Carrier identifier

Request Body schema: application/merge-patch+json
required

The updated Carrier resource

name
string [ 2 .. 255 ] characters
type
string
Default: "custom"
Enum: "ups" "dhl" "fedex" "usps" "custom" "internal"
capabilities
Array of strings
serviceLevels
Array of strings
coverage
Array of strings
environment
string or null
Enum: "sandbox" "production"

Provider environment — "sandbox" or "production". Omit to leave unchanged.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "type": "ups",
  • "capabilities": [
    ],
  • "serviceLevels": [
    ],
  • "coverage": [
    ],
  • "environment": "sandbox"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "UPS-PRIMARY",
  • "name": "UPS",
  • "type": "ups",
  • "isInternal": false,
  • "credentialScope": "platform",
  • "environment": "sandbox",
  • "status": "active",
  • "capabilities": [
    ],
  • "serviceLevels": [
    ],
  • "coverage": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Activate an external carrier

Activate an external carrier

Authorizations:
Bearer
path Parameters
id
required
string

Carrier identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "UPS-PRIMARY",
  • "name": "UPS",
  • "type": "ups",
  • "isInternal": false,
  • "credentialScope": "platform",
  • "environment": "sandbox",
  • "status": "active",
  • "capabilities": [
    ],
  • "serviceLevels": [
    ],
  • "coverage": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Deactivate an external carrier

Deactivate an external carrier

Authorizations:
Bearer
path Parameters
id
required
string

Carrier identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "UPS-PRIMARY",
  • "name": "UPS",
  • "type": "ups",
  • "isInternal": false,
  • "credentialScope": "platform",
  • "environment": "sandbox",
  • "status": "active",
  • "capabilities": [
    ],
  • "serviceLevels": [
    ],
  • "coverage": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Quote carrier rates for a shipment

Fetch live rate quotes for a shipment from a carrier (carrierId query parameter, required).

Authorizations:
Bearer
path Parameters
serviceLevel
required
string

CarrierRate identifier

query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Shipping Clients

A shipping client — a first-class customer that LINKS to an existing Partner (billing/contact entity) and layers shipping-specific defaults on top: preferred pickup/delivery addresses, billing terms, service level, and handling requirements.

Tenant-managed reference data. The linked partner is immutable once set.

List shipping clients

Retrieve a paginated list of shipping clients.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Register a shipping client for an existing partner

Register a shipping client for an existing partner

Authorizations:
Bearer
Request Body schema:
required

The new Client resource

partnerId
required
string <= 100 characters

The existing Partner this client wraps.

accountReference
string or null <= 128 characters
defaultServiceLevel
string or null
Enum: "standard" "express" "same_day" "next_day"
defaultHandlingRequirements
Array of strings
ShipmentAddressInput (object) or null
ShipmentContactInput (object) or null
ShipmentCoordinatesInput (object) or null
ShipmentAddressInput (object) or null
ShipmentContactInput (object) or null
ShipmentCoordinatesInput (object) or null
ClientBillingTermsInput (object) or null

Responses

Request samples

Content type
{
  • "partnerId": "string",
  • "accountReference": "string",
  • "defaultServiceLevel": "standard",
  • "defaultHandlingRequirements": [
    ],
  • "pickupAddress": {
    },
  • "pickupContact": {
    },
  • "pickupCoordinates": {
    },
  • "deliveryAddress": {
    },
  • "deliveryContact": {
    },
  • "deliveryCoordinates": {
    },
  • "billingTerms": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "status": "active",
  • "accountReference": "string",
  • "defaultServiceLevel": "standard",
  • "defaultHandlingRequirements": [
    ],
  • "defaultPickupAddress": {
    },
  • "defaultDeliveryAddress": {
    },
  • "billingTerms": {
    },
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a shipping client

Get a shipping client

Authorizations:
Bearer
path Parameters
id
required
string

Client identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "status": "active",
  • "accountReference": "string",
  • "defaultServiceLevel": "standard",
  • "defaultHandlingRequirements": [
    ],
  • "defaultPickupAddress": {
    },
  • "defaultDeliveryAddress": {
    },
  • "billingTerms": {
    },
  • "createdAt": "string",
  • "updatedAt": "string"
}

Update a shipping client profile

Update a shipping client profile

Authorizations:
Bearer
path Parameters
id
required
string

Client identifier

Request Body schema: application/merge-patch+json
required

The updated Client resource

accountReference
string or null <= 128 characters
defaultServiceLevel
string or null
Enum: "standard" "express" "same_day" "next_day"
defaultHandlingRequirements
Array of strings
ShipmentAddressInput (object) or null
ShipmentContactInput (object) or null
ShipmentCoordinatesInput (object) or null
ShipmentAddressInput (object) or null
ShipmentContactInput (object) or null
ShipmentCoordinatesInput (object) or null
ClientBillingTermsInput (object) or null

Responses

Request samples

Content type
application/merge-patch+json
{
  • "accountReference": "string",
  • "defaultServiceLevel": "standard",
  • "defaultHandlingRequirements": [
    ],
  • "pickupAddress": {
    },
  • "pickupContact": {
    },
  • "pickupCoordinates": {
    },
  • "deliveryAddress": {
    },
  • "deliveryContact": {
    },
  • "deliveryCoordinates": {
    },
  • "billingTerms": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "status": "active",
  • "accountReference": "string",
  • "defaultServiceLevel": "standard",
  • "defaultHandlingRequirements": [
    ],
  • "defaultPickupAddress": {
    },
  • "defaultDeliveryAddress": {
    },
  • "billingTerms": {
    },
  • "createdAt": "string",
  • "updatedAt": "string"
}

Activate a shipping client

Activate a shipping client

Authorizations:
Bearer
path Parameters
id
required
string

Client identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "status": "active",
  • "accountReference": "string",
  • "defaultServiceLevel": "standard",
  • "defaultHandlingRequirements": [
    ],
  • "defaultPickupAddress": {
    },
  • "defaultDeliveryAddress": {
    },
  • "billingTerms": {
    },
  • "createdAt": "string",
  • "updatedAt": "string"
}

Deactivate a shipping client

Deactivate a shipping client

Authorizations:
Bearer
path Parameters
id
required
string

Client identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "status": "active",
  • "accountReference": "string",
  • "defaultServiceLevel": "standard",
  • "defaultHandlingRequirements": [
    ],
  • "defaultPickupAddress": {
    },
  • "defaultDeliveryAddress": {
    },
  • "billingTerms": {
    },
  • "createdAt": "string",
  • "updatedAt": "string"
}