Skip to main content

Usage Guide

This guide covers the carrier integration flow: receive shipments from Cargors, update status, and upload proof of delivery.

Carriers do not use the Cargors Portal for API keys. Keys are created only via the key management API.

Step 1: Authentication​

Generate an API key via the key management REST API (HTTP Basic Auth). Carriers have no portal view for API key management.

Full walkthrough: Carrier Generate API key.

Send these headers with every carrier API request:

  • x-api-key: <API_KEY_VALUE>
  • Content-Type: application/json (or multipart/form-data for file uploads)

API base URL: https://app.cargors.com/api/edi (see Endpoints).

Step 2: Receive shipments from Cargors​

Before status/POD APIs are used, your team must onboard with Cargors so shipments can be pushed to your system.

What you need to share with Cargors​

  • Your incoming API endpoint URL
  • Authentication details for your endpoint
  • Any custom payload mapping requirements

Example payload Cargors can send to your system​

{
  "shipmentID": "SH-6880A",
  "shipperName": "Cargors B.V - Guide",
  "pickupDetails": {
    "streetName": "Science Park",
    "streetNo": "608",
    "postCode": "1098 XH",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "country": "Netherlands",
    "countryCode": "NL",
    "date": "2024-02-12T19:00:00.000Z",
    "fromTime": "19:00",
    "toTime": "20:00",
    "reference": "NA",
    "person": "Najeeb",
    "company": "Cargors B.V.",
    "email": "najeeb@cargors.com",
    "phone": "0655772164"
  },
  "deliveryDetails": {
    "streetName": "Contactweg",
    "streetNo": "22",
    "postCode": "1014 BH",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "country": "Netherlands",
    "countryCode": "NL",
    "date": "2024-02-13T19:00:00.000Z",
    "fromTime": "08:30",
    "toTime": "17:00",
    "reference": "NA",
    "person": "Inara",
    "company": "Cargors",
    "email": "operations@cargors.com",
    "phone": "0031655772164"
  },
  "vehicleType": "No preference",
  "transportType": "Standard - dry",
  "loadType": "LTL"
}

Step 3: Update shipment status​

Endpoint​

What this endpoint does​

Updates the status of an assigned shipment during execution.

Supported shipmentStatus values​

  • SHIPMENT_STARTED
  • DRIVER_ON_THE_WAY
  • LOAD_PICKED_UP
  • OUT_FOR_DELIVERY
  • LOAD_DELIVERED

Example request​

{
  "shipmentStatus": "DRIVER_ON_THE_WAY",
  "pickupData": {
    "date": "2026-05-25",
    "fromTime": "08:00",
    "toTime": "09:00"
  },
  "deliveryData": {
    "date": "2026-05-26",
    "fromTime": "08:00",
    "toTime": "09:00"
  }
}

Example success response​

{
  "message": "Shipment status changed successfully",
  "shipmentId": "SH12A",
  "shipmentStatus": "DRIVER_ON_THE_WAY"
}

Step 4: Upload proof of delivery (POD)​

Endpoint​

What this endpoint does​

Uploads POD files for a delivered shipment.

Supported request formats​

  • application/json with base64 file content
  • multipart/form-data with binary file uploads

Example JSON request​

{
  "shipmentNo": "SH12A",
  "files": [
    {
      "name": "delivered_proof.pdf",
      "data": "BASE64_ENCODED_DATA_HERE",
      "mimetype": "application/pdf"
    }
  ]
}

Example success response​

{
  "message": "POD uploaded successfully",
  "uploads": [{ "name": "delivered_proof.pdf", "url": "https://..." }]
}