Skip to main content

Carriers API

The Carriers API provides endpoints for managing carrier configurations and integrations.

Endpoints Overview​

MethodEndpointDescription
GET/api/carriersList all carriers
GET/api/carriers/configuredList configured carriers
GET/api/carriers/lookupsGet carrier lookups
POST/api/carriers/configureConfigure a carrier
GET/api/carriers/{carrierId}Get carrier details
PATCH/api/carriers/{carrierId}Update carrier
DELETE/api/carriers/{carrierId}Remove carrier
GET/api/carriers/contactsList carrier contacts
POST/api/carriers/contactsAdd carrier contact

List All Carriers​

Get all available carriers.

GET /api/carriers

Response​

{
  "data": [
    {
      "guid": "carrier-uuid",
      "name": "Express Delivery",
      "code": "EXPRESS",
      "type": "courier",
      "isConfigured": true,
      "isActive": true
    },
    {
      "guid": "carrier-uuid-2",
      "name": "Standard Shipping",
      "code": "STANDARD",
      "type": "freight",
      "isConfigured": false,
      "isActive": false
    }
  ],
  "success": true
}

List Configured Carriers​

Get carriers configured for your business.

GET /api/carriers/configured

Response​

{
  "data": [
    {
      "guid": "carrier-uuid",
      "name": "Express Delivery",
      "code": "EXPRESS",
      "type": "courier",
      "isActive": true,
      "accountNumber": "ACC123456",
      "serviceLevels": [
        {
          "code": "standard",
          "name": "Standard Delivery"
        },
        {
          "code": "express",
          "name": "Express Delivery"
        }
      ]
    }
  ],
  "success": true
}

Get Carrier Lookups​

Get carrier options and lookup data.

GET /api/carriers/lookups

Response​

{
  "data": {
    "carrierTypes": [
      { "code": "courier", "name": "Courier Service" },
      { "code": "freight", "name": "Freight Carrier" },
      { "code": "lastmile", "name": "Last Mile Delivery" }
    ],
    "serviceLevels": [
      { "code": "standard", "name": "Standard" },
      { "code": "express", "name": "Express" },
      { "code": "sameday", "name": "Same Day" }
    ]
  },
  "success": true
}

Configure Carrier​

Set up a carrier for your business.

POST /api/carriers/configure

Request Body​

{
  "carrierId": "carrier-uuid",
  "accountNumber": "ACC123456",
  "apiKey": "your-api-key",
  "apiSecret": "your-api-secret",
  "testMode": false,
  "defaultServiceLevel": "standard"
}

Response​

{
  "data": {
    "guid": "carrier-uuid",
    "name": "Express Delivery",
    "isConfigured": true,
    "isActive": true
  },
  "success": true
}

Get Carrier Details​

Retrieve details for a specific carrier.

GET /api/carriers/{carrierId}

Path Parameters​

ParameterTypeDescription
carrierIduuidCarrier identifier

Response​

{
  "data": {
    "guid": "carrier-uuid",
    "name": "Express Delivery",
    "code": "EXPRESS",
    "type": "courier",
    "isActive": true,
    "configuration": {
      "accountNumber": "ACC123456",
      "defaultServiceLevel": "standard"
    },
    "serviceLevels": [
      {
        "code": "standard",
        "name": "Standard Delivery",
        "estimatedDays": "3-5"
      },
      {
        "code": "express",
        "name": "Express Delivery",
        "estimatedDays": "1-2"
      }
    ],
    "features": [
      "tracking",
      "signature",
      "insurance"
    ]
  },
  "success": true
}

Update Carrier​

Update carrier configuration.

PATCH /api/carriers/{carrierId}

Request Body​

{
  "isActive": true,
  "defaultServiceLevel": "express",
  "apiKey": "updated-api-key"
}

Response​

{
  "data": {
    "guid": "carrier-uuid",
    "name": "Express Delivery",
    "isActive": true
  },
  "success": true
}

Remove Carrier​

Remove a carrier configuration.

DELETE /api/carriers/{carrierId}

Response​

{
  "data": {
    "guid": "carrier-uuid"
  },
  "success": true
}

List Carrier Contacts​

Get contacts for carrier relationships.

GET /api/carriers/contacts

Response​

{
  "data": [
    {
      "guid": "contact-uuid",
      "name": "John Smith",
      "email": "john@carrier.com",
      "phone": "+1234567890",
      "role": "Account Manager",
      "carrierId": "carrier-uuid"
    }
  ],
  "success": true
}

Add Carrier Contact​

Add a contact for carrier communication.

POST /api/carriers/contacts

Request Body​

{
  "carrierId": "carrier-uuid",
  "name": "Jane Doe",
  "email": "jane@carrier.com",
  "phone": "+0987654321",
  "role": "Support Representative"
}

Response​

{
  "data": {
    "guid": "contact-uuid",
    "name": "Jane Doe",
    "email": "jane@carrier.com"
  },
  "success": true
}

Error Responses​

404 Not Found​

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Carrier not found"
  }
}

400 Bad Request​

{
  "success": false,
  "error": {
    "code": "CONFIGURATION_ERROR",
    "message": "Invalid carrier credentials"
  }
}