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.

Fleet

A depot — a first-class fleet base (hub, yard, cross-dock, parking site) where fleet units are stationed and dispatched from. Optionally linked to a co-located warehouse via the bare warehouseId.

List depots

Paginated list of depots. Filter by type or status.

Authorizations:
Bearer
query Parameters
type
string
Enum: "hub" "yard" "cross_dock" "parking_site"

Filter by type

status
string
Enum: "active" "inactive"

Filter by status

page
integer >= 1
Default: 1

Page number

itemsPerPage
integer [ 1 .. 100 ]
Default: 30

Items per page

Responses

Response samples

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

Register a depot

Register a depot

Authorizations:
Bearer
Request Body schema:
required

The new Depot resource

name
required
string <= 255 characters
code
required
string <= 64 characters
type
required
string
Enum: "hub" "yard" "cross_dock" "parking_site"
required
object (DepotAddressInput)
warehouseId
string or null <= 512 characters

Responses

Request samples

Content type
{
  • "name": "string",
  • "code": "string",
  • "type": "hub",
  • "address": {
    },
  • "warehouseId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "",
  • "name": "",
  • "code": "",
  • "type": "hub",
  • "status": "active",
  • "address": {
    },
  • "warehouseId": "string",
  • "createdAt": "",
  • "updatedAt": ""
}

Get a depot

Get a depot

Authorizations:
Bearer
path Parameters
id
required
string

Depot identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "",
  • "name": "",
  • "code": "",
  • "type": "hub",
  • "status": "active",
  • "address": {
    },
  • "warehouseId": "string",
  • "createdAt": "",
  • "updatedAt": ""
}

Deactivate a depot

Deactivate a depot

Authorizations:
Bearer
path Parameters
id
required
string

Depot identifier

Responses

Response samples

Content type
{
  • "type": "/errors/validation-error",
  • "title": "Validation Error",
  • "status": 400,
  • "detail": "The provided input is invalid",
  • "violations": [
    ],
  • "instance": "string"
}

Update a depot

Update a depot

Authorizations:
Bearer
path Parameters
id
required
string

Depot identifier

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

The updated Depot resource

name
string or null <= 255 characters
type
string or null
Enum: "hub" "yard" "cross_dock" "parking_site"
DepotAddressInput (object) or null
warehouseId
string or null <= 512 characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "type": "hub",
  • "address": {
    },
  • "warehouseId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "",
  • "name": "",
  • "code": "",
  • "type": "hub",
  • "status": "active",
  • "address": {
    },
  • "warehouseId": "string",
  • "createdAt": "",
  • "updatedAt": ""
}

Crews

Represents a team organization that manages drivers and vehicles.

Crews are responsible for executing routes and deliveries. They have members (drivers), vehicles, and can be assigned routes.

List all teams

Retrieve a paginated list of teams with optional filters.

Authorizations:
Bearer
query Parameters
status
string
Enum: "active" "disabled"
Example: status=active

Filter by team status

search
string
Example: search=Express

Search by name or code

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 30
Example: itemsPerPage=30

Number of items per page

Responses

Response samples

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

Create a team

Create a new team.

Authorizations:
Bearer
Request Body schema: application/json
required

Crew creation data

code
required
string [ 2 .. 50 ] characters
name
required
string [ 2 .. 255 ] characters
type
string
Default: "internal"
Enum: "internal" "external"
email
string or null <email>
phone
string or null <= 50 characters

Responses

Request samples

Content type
application/json
{
  • "code": "EXPRESS-01",
  • "name": "Express Logistics Inc.",
  • "type": "internal",
  • "email": "user@example.com",
  • "phone": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "EXPRESS-01",
  • "name": "Express Logistics Inc.",
  • "type": "internal",
  • "email": "dispatch@expresslogistics.com",
  • "phone": "+1-555-123-4567",
  • "status": "active",
  • "partnerId": "01912345-6789-7abc-def0-123456789def",
  • "partnerName": "string",
  • "homeDepotId": "01912345-6789-7abc-def0-123456789aaa",
  • "homeDepotName": "string",
  • "workspaceTeamId": "01912345-6789-7abc-def0-1234567890ab",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get a team by code

Retrieve a single team by its human-readable code.

Authorizations:
Bearer
path Parameters
code
required
string [ 2 .. 50 ] characters
Example: EXPRESS-01

Crew code

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "EXPRESS-01",
  • "name": "Express Logistics Inc.",
  • "type": "internal",
  • "email": "dispatch@expresslogistics.com",
  • "phone": "+1-555-123-4567",
  • "status": "active",
  • "partnerId": "01912345-6789-7abc-def0-123456789def",
  • "partnerName": "string",
  • "homeDepotId": "01912345-6789-7abc-def0-123456789aaa",
  • "homeDepotName": "string",
  • "workspaceTeamId": "01912345-6789-7abc-def0-1234567890ab",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get a team

Retrieve a single team by its UUID.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Crew UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "EXPRESS-01",
  • "name": "Express Logistics Inc.",
  • "type": "internal",
  • "email": "dispatch@expresslogistics.com",
  • "phone": "+1-555-123-4567",
  • "status": "active",
  • "partnerId": "01912345-6789-7abc-def0-123456789def",
  • "partnerName": "string",
  • "homeDepotId": "01912345-6789-7abc-def0-123456789aaa",
  • "homeDepotName": "string",
  • "workspaceTeamId": "01912345-6789-7abc-def0-1234567890ab",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Delete a team

Delete (disable) a team.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Crew UUID

Responses

Update a team

Update team details. Only provided fields will be updated.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Crew UUID

Request Body schema: application/json
optional

Crew update data (partial update supported)

name
string [ 2 .. 255 ] characters
email
string or null <email>
phone
string or null <= 50 characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "email": "user@example.com",
  • "phone": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "EXPRESS-01",
  • "name": "Express Logistics Inc.",
  • "type": "internal",
  • "email": "dispatch@expresslogistics.com",
  • "phone": "+1-555-123-4567",
  • "status": "active",
  • "partnerId": "01912345-6789-7abc-def0-123456789def",
  • "partnerName": "string",
  • "homeDepotId": "01912345-6789-7abc-def0-123456789aaa",
  • "homeDepotName": "string",
  • "workspaceTeamId": "01912345-6789-7abc-def0-1234567890ab",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Disable a team

Disable an active team.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Crew UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "EXPRESS-01",
  • "name": "Express Logistics Inc.",
  • "type": "internal",
  • "email": "dispatch@expresslogistics.com",
  • "phone": "+1-555-123-4567",
  • "status": "active",
  • "partnerId": "01912345-6789-7abc-def0-123456789def",
  • "partnerName": "string",
  • "homeDepotId": "01912345-6789-7abc-def0-123456789aaa",
  • "homeDepotName": "string",
  • "workspaceTeamId": "01912345-6789-7abc-def0-1234567890ab",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Enable a team

Enable a disabled team.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Crew UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "EXPRESS-01",
  • "name": "Express Logistics Inc.",
  • "type": "internal",
  • "email": "dispatch@expresslogistics.com",
  • "phone": "+1-555-123-4567",
  • "status": "active",
  • "partnerId": "01912345-6789-7abc-def0-123456789def",
  • "partnerName": "string",
  • "homeDepotId": "01912345-6789-7abc-def0-123456789aaa",
  • "homeDepotName": "string",
  • "workspaceTeamId": "01912345-6789-7abc-def0-1234567890ab",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Set a team's home depot

Set or clear a team's home depot. Pass a depotId to assign, or null to clear.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Crew UUID

Request Body schema: application/json
optional

Home depot assignment (null depotId clears it)

depotId
string or null <uuid>

Responses

Request samples

Content type
application/json
{
  • "depotId": "5c1dba4a-049c-4946-b492-7dd432cad67c"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "EXPRESS-01",
  • "name": "Express Logistics Inc.",
  • "type": "internal",
  • "email": "dispatch@expresslogistics.com",
  • "phone": "+1-555-123-4567",
  • "status": "active",
  • "partnerId": "01912345-6789-7abc-def0-123456789def",
  • "partnerName": "string",
  • "homeDepotId": "01912345-6789-7abc-def0-123456789aaa",
  • "homeDepotName": "string",
  • "workspaceTeamId": "01912345-6789-7abc-def0-1234567890ab",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Fleet Management

Represents a driver in the fleet.

List all drivers

Retrieve a list of all drivers in the fleet.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Register a new driver

Register a driver and associate with a team.

Authorizations:
Bearer
Request Body schema:
required

The new Driver resource

crewId
required
string = 26 characters
Default: ""
membershipId
string or null = 26 characters
PersonRepresentation (object) or null
ContactRepresentation (object) or null
hireDate
EmergencyContactRepresentation (object) or null

Responses

Request samples

Content type
{
  • "crewId": "",
  • "membershipId": "stringstringstringstringst",
  • "person": {
    },
  • "contact": {
    },
  • "hireDate": "string",
  • "emergencyContact": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "crewId": "string",
  • "teamName": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phone": "string",
  • "photoUrl": "string",
  • "avatarUrl": "string",
  • "status": "active",
  • "hireDate": "string",
  • "dateOfBirth": "string",
  • "emergencyContactName": "string",
  • "emergencyContactPhone": "string",
  • "emergencyContactRelationship": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a driver

Retrieve a single driver by ID.

Authorizations:
Bearer
path Parameters
id
required
string

Driver identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "crewId": "string",
  • "teamName": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phone": "string",
  • "photoUrl": "string",
  • "avatarUrl": "string",
  • "status": "active",
  • "hireDate": "string",
  • "dateOfBirth": "string",
  • "emergencyContactName": "string",
  • "emergencyContactPhone": "string",
  • "emergencyContactRelationship": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Update a driver

Update driver profile details. Only provided fields will be updated.

Authorizations:
Bearer
path Parameters
id
required
string

Driver identifier

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

The updated Driver resource

PersonRepresentation (object) or null
ContactRepresentation (object) or null
photoUrl
string or null <uri>
https://schema.org/url
hireDate
EmergencyContactRepresentation (object) or null

Responses

Request samples

Content type
application/merge-patch+json
{
  • "person": {
    },
  • "contact": {
    },
  • "photoUrl": "http://example.com",
  • "hireDate": "string",
  • "emergencyContact": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "crewId": "string",
  • "teamName": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phone": "string",
  • "photoUrl": "string",
  • "avatarUrl": "string",
  • "status": "active",
  • "hireDate": "string",
  • "dateOfBirth": "string",
  • "emergencyContactName": "string",
  • "emergencyContactPhone": "string",
  • "emergencyContactRelationship": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Activate a driver

Activate a driver that is currently in a non-active status.

Authorizations:
Bearer
path Parameters
id
required
string

Driver identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "crewId": "string",
  • "teamName": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phone": "string",
  • "photoUrl": "string",
  • "avatarUrl": "string",
  • "status": "active",
  • "hireDate": "string",
  • "dateOfBirth": "string",
  • "emergencyContactName": "string",
  • "emergencyContactPhone": "string",
  • "emergencyContactRelationship": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Deactivate a driver

Deactivate a driver with a reason.

Authorizations:
Bearer
path Parameters
id
required
string

Driver identifier

Request Body schema:
required

The new Driver resource

reason
required
string <= 1000 characters
Default: ""

Responses

Request samples

Content type
{
  • "reason": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "crewId": "string",
  • "teamName": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phone": "string",
  • "photoUrl": "string",
  • "avatarUrl": "string",
  • "status": "active",
  • "hireDate": "string",
  • "dateOfBirth": "string",
  • "emergencyContactName": "string",
  • "emergencyContactPhone": "string",
  • "emergencyContactRelationship": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Grant portal access

Grant a driver access to the customer portal via a membership.

Authorizations:
Bearer
path Parameters
id
required
string

Driver identifier

Request Body schema:
required

The new Driver resource

membershipId
required
string = 26 characters
Default: ""

Responses

Request samples

Content type
{
  • "membershipId": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "crewId": "string",
  • "teamName": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phone": "string",
  • "photoUrl": "string",
  • "avatarUrl": "string",
  • "status": "active",
  • "hireDate": "string",
  • "dateOfBirth": "string",
  • "emergencyContactName": "string",
  • "emergencyContactPhone": "string",
  • "emergencyContactRelationship": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Reinstate a driver

Reinstate a suspended driver back to active status.

Authorizations:
Bearer
path Parameters
id
required
string

Driver identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "crewId": "string",
  • "teamName": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phone": "string",
  • "photoUrl": "string",
  • "avatarUrl": "string",
  • "status": "active",
  • "hireDate": "string",
  • "dateOfBirth": "string",
  • "emergencyContactName": "string",
  • "emergencyContactPhone": "string",
  • "emergencyContactRelationship": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Revoke portal access

Revoke a driver's access to the customer portal.

Authorizations:
Bearer
path Parameters
id
required
string

Driver identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "crewId": "string",
  • "teamName": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phone": "string",
  • "photoUrl": "string",
  • "avatarUrl": "string",
  • "status": "active",
  • "hireDate": "string",
  • "dateOfBirth": "string",
  • "emergencyContactName": "string",
  • "emergencyContactPhone": "string",
  • "emergencyContactRelationship": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Suspend a driver

Suspend an active driver with a reason.

Authorizations:
Bearer
path Parameters
id
required
string

Driver identifier

Request Body schema:
required

The new Driver resource

reason
required
string <= 1000 characters
Default: ""

Responses

Request samples

Content type
{
  • "reason": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "crewId": "string",
  • "teamName": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phone": "string",
  • "photoUrl": "string",
  • "avatarUrl": "string",
  • "status": "active",
  • "hireDate": "string",
  • "dateOfBirth": "string",
  • "emergencyContactName": "string",
  • "emergencyContactPhone": "string",
  • "emergencyContactRelationship": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Fleet - Number Generation

Resource 'Fleet - Number Generation' operations.

Generate a team code

Generate a team code

Authorizations:
Bearer
Request Body schema:
required

The new CrewCode resource

number
string

The generated team code

type
string

Resource type

barcode
string or null

GS1-128 barcode (if applicable)

generatedAt
string

Generation timestamp (ISO 8601)

Responses

Request samples

Content type
{
  • "number": "CAR001",
  • "type": "dispatch.crew_code",
  • "barcode": "string",
  • "generatedAt": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "number": "CAR001",
  • "type": "dispatch.crew_code",
  • "barcode": "string",
  • "generatedAt": "string"
}

Preview the next team code

Preview the next team code

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "number": "CAR001",
  • "type": "dispatch.crew_code",
  • "barcode": "string",
  • "generatedAt": "string"
}