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.

Geocoding

Represents a geocoding result.

Geocoding converts addresses to coordinates (forward geocoding) or coordinates to addresses (reverse geocoding).

Autocomplete a partial address

Returns structured address suggestions for the supplied query, biased toward an optional ISO country code.

Authorizations:
Bearer
query Parameters
q
required
string >= 2 characters
Example: q=Keizersgracht 123 Amsterdam

Partial address query (street, postal code, or city)

country
string = 2 characters
Example: country=NL

ISO 3166-1 alpha-2 country code to bias the results

limit
integer [ 1 .. 10 ]
Example: limit=5

Maximum suggestions to return (1–10, default 5)

page
integer
Default: 1

The collection page number

Responses

Response samples

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

Geocode an address

Convert an address string to geographic coordinates (forward geocoding).

Authorizations:
Bearer
Request Body schema: application/json
required

Address to geocode

address
required
string

Full address to geocode

Responses

Request samples

Content type
application/json
{
  • "address": "Keizersgracht 123, 1015 CJ Amsterdam, Netherlands"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "address": "Keizersgracht 123, 1015 CJ Amsterdam, Netherlands",
  • "coordinates": {
    },
  • "confidence": 0.95
}

Reverse geocode coordinates

Convert geographic coordinates to an address (reverse geocoding).

Authorizations:
Bearer
Request Body schema: application/json
required

Coordinates to reverse geocode

latitude
required
number <float> [ -90 .. 90 ]

Latitude coordinate

longitude
required
number <float> [ -180 .. 180 ]

Longitude coordinate

Responses

Request samples

Content type
application/json
{
  • "latitude": 52.3676,
  • "longitude": 4.9041
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "address": "Keizersgracht 123, 1015 CJ Amsterdam, Netherlands",
  • "coordinates": {
    },
  • "confidence": 0.95
}

Validate a structured address before saving

Forward-geocodes the supplied address and returns either valid:true with a normalised coordinate-bearing match, or valid:false with alternative suggestions.

Authorizations:
Bearer
Request Body schema:
required

The new AddressValidation resource

street
string or null <= 255 characters
streetLine2
string or null <= 255 characters
city
string or null <= 100 characters
province
string or null <= 100 characters
postalCode
string or null <= 20 characters
countryCode
string or null = 2 characters

Responses

Request samples

Content type
{
  • "street": "string",
  • "streetLine2": "string",
  • "city": "string",
  • "province": "string",
  • "postalCode": "string",
  • "countryCode": "st"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "valid": false,
  • "confidence": 0,
  • "normalized": {
    },
  • "suggestions": [
    ]
}

Countries

A country the platform is available in.

Public reference data that powers the unauthenticated signup country selector. Backed by active country zones in the Addressing module — the set is controlled by activating/deactivating country zones.

The resource deliberately declares no #[ApiProperty(identifier: true)] so API Platform does not synthesise an item-level Get operation alongside the collection — countries are a flat reference list, not an addressable entity.

List available countries

Public, unauthenticated list of the countries the platform is available in (active country zones). Used by the signup country selector. Each item exposes the ISO 3166-1 alpha-2 code and the country name.

Authorizations:
Bearer

Responses

Response samples

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

Locations

Represents a physical location in the system.

Locations are used to define delivery addresses, pickup points, warehouses, and other physical points of interest.

List all locations

Retrieve a paginated list of locations with optional filters.

Authorizations:
Bearer
query Parameters
type
string
Enum: "warehouse" "customer" "pickup_point" "hub" "other"
Example: type=warehouse

Filter by location type

search
string
Example: search=Amsterdam

Search by name or address

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 location

Create a new location. Coordinates can be provided directly or geocoded from the address.

Authorizations:
Bearer
Request Body schema: application/json
required

Location creation data

name
required
string [ 2 .. 255 ] characters

Location name

address
required
string

Full address of the location

type
required
string
Enum: "warehouse" "customer" "pickup_point" "hub" "other"

Type of location

latitude
number or null <float> [ -90 .. 90 ]

Latitude coordinate

longitude
number or null <float> [ -180 .. 180 ]

Longitude coordinate

Responses

Request samples

Content type
application/json
{
  • "name": "Amsterdam Warehouse",
  • "address": "Keizersgracht 123, 1015 CJ Amsterdam, Netherlands",
  • "type": "warehouse",
  • "latitude": 52.3676,
  • "longitude": 4.9041
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Amsterdam Warehouse",
  • "address": "Keizersgracht 123, 1015 CJ Amsterdam, Netherlands",
  • "coordinates": {
    },
  • "type": "warehouse",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Get a location

Retrieve a single location by its UUID.

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

Location UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Amsterdam Warehouse",
  • "address": "Keizersgracht 123, 1015 CJ Amsterdam, Netherlands",
  • "coordinates": {
    },
  • "type": "warehouse",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Delete a location

Delete a location. This action cannot be undone.

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

Location UUID

Responses

Update a location

Update location details. Provide only the fields you want to change.

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

Location UUID

Request Body schema: application/json
optional

Location update data (partial update supported)

name
string [ 2 .. 255 ] characters

Location name

address
string

Full address of the location

type
string
Enum: "warehouse" "customer" "pickup_point" "hub" "other"

Type of location

latitude
number or null <float>

Latitude coordinate

longitude
number or null <float>

Longitude coordinate

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "address": "string",
  • "type": "warehouse",
  • "latitude": 0.1,
  • "longitude": 0.1
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Amsterdam Warehouse",
  • "address": "Keizersgracht 123, 1015 CJ Amsterdam, Netherlands",
  • "coordinates": {
    },
  • "type": "warehouse",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Tenant Zones

Represents a zone enabled for a tenant with optional customization.

List tenant zones

Retrieve a paginated list of zones enabled for the current tenant.

Authorizations:
Bearer
query Parameters
zoneType
string

Filter by zone type

enabled
boolean

Filter by enabled status

search
string

Search by zone name, code, or custom label

page
integer >= 1
Default: 1

Page number

itemsPerPage
integer [ 1 .. 100 ]
Default: 20

Items per page

Responses

Response samples

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

Enable a zone for tenant

Enable a global zone for the current tenant.

Authorizations:
Bearer
Request Body schema:
required

The new TenantZone resource

zoneId
required
string
Default: ""
customLabel
string or null

Responses

Request samples

Content type
{
  • "zoneId": "",
  • "customLabel": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "zoneId": "string",
  • "zoneCode": "string",
  • "zoneName": "string",
  • "zoneType": "string",
  • "customLabel": "string",
  • "enabled": true,
  • "metadata": {
    },
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a tenant zone

Retrieve a single tenant zone by its ID.

Authorizations:
Bearer
path Parameters
id
required
string <ulid>

Tenant zone ID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "zoneId": "string",
  • "zoneCode": "string",
  • "zoneName": "string",
  • "zoneType": "string",
  • "customLabel": "string",
  • "enabled": true,
  • "metadata": {
    },
  • "createdAt": "string",
  • "updatedAt": "string"
}

Disable a tenant zone

Disable a zone for the current tenant.

Authorizations:
Bearer
path Parameters
id
required
string <ulid>

Tenant zone ID

Responses

Update a tenant zone

Update the custom label or metadata of a tenant zone.

Authorizations:
Bearer
path Parameters
id
required
string <ulid>

Tenant zone ID

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

The updated TenantZone resource

customLabel
string or null
object or null

Responses

Request samples

Content type
application/merge-patch+json
{
  • "customLabel": "string",
  • "metadata": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "zoneId": "string",
  • "zoneCode": "string",
  • "zoneName": "string",
  • "zoneType": "string",
  • "customLabel": "string",
  • "enabled": true,
  • "metadata": {
    },
  • "createdAt": "string",
  • "updatedAt": "string"
}

Zones

Represents a geographic zone in the system.

List all zones

Retrieve a paginated list of zones with optional filters.

Authorizations:
Bearer
query Parameters
type
string
Enum: "continent" "country" "state" "city" "postal_group" "district" "custom"

Filter by zone type

parentId
string

Filter by parent zone ID

status
string
Enum: "active" "inactive"

Filter by status

search
string

Search by name or code

page
integer >= 1
Default: 1

Page number

itemsPerPage
integer [ 1 .. 100 ]
Default: 30

Number of items per page

Responses

Response samples

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

Create a zone

Create a new geographic zone.

Authorizations:
Bearer
Request Body schema:
required

The new Zone resource

code
required
string <= 64 characters
name
required
string <= 255 characters
type
required
string
Enum: "continent" "country" "state" "city" "postal_group" "district" "custom"
parentId
string or null
members
Array of strings
geometry
string or null
description
string or null
sortOrder
integer
Default: 0

Responses

Request samples

Content type
{
  • "code": "string",
  • "name": "string",
  • "type": "continent",
  • "parentId": "string",
  • "members": [
    ],
  • "geometry": "string",
  • "description": "string",
  • "sortOrder": 0
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "string",
  • "name": "string",
  • "parentId": "string",
  • "parentName": "string",
  • "type": "string",
  • "members": [
    ],
  • "geometry": "string",
  • "status": "string",
  • "description": "string",
  • "sortOrder": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a zone

Retrieve a single zone by its ID.

Authorizations:
Bearer
path Parameters
id
required
string

Zone identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "string",
  • "name": "string",
  • "parentId": "string",
  • "parentName": "string",
  • "type": "string",
  • "members": [
    ],
  • "geometry": "string",
  • "status": "string",
  • "description": "string",
  • "sortOrder": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Deactivate a zone

Deactivate a zone (soft-delete).

Authorizations:
Bearer
path Parameters
id
required
string

Zone identifier

Responses

Update a zone

Update zone details. Code is immutable.

Authorizations:
Bearer
path Parameters
id
required
string

Zone identifier

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

The updated Zone resource

name
string <= 255 characters
type
string
Enum: "continent" "country" "state" "city" "postal_group" "district" "custom"
parentId
string or null
members
Array of strings
geometry
string or null
description
string or null
sortOrder
integer
Default: 0

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "type": "continent",
  • "parentId": "string",
  • "members": [
    ],
  • "geometry": "string",
  • "description": "string",
  • "sortOrder": 0
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "string",
  • "name": "string",
  • "parentId": "string",
  • "parentName": "string",
  • "type": "string",
  • "members": [
    ],
  • "geometry": "string",
  • "status": "string",
  • "description": "string",
  • "sortOrder": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}