Endpoint Reference

← Back to Developers

Overview

All endpoints live under https://api.livecourier.com/v1/. Requests and responses are JSON. Every request must include Authorization: Bearer <token> and X-Tenant: CLIENT_ID headers (see Authentication).

Common Response Format

Success:

{
  "ok": true,
  "data": { ... }
}

Error:

{
  "ok": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": { "field": "error" }
  }
}

Authentication

Get Token

POST /v1/auth/token
X-Tenant: CLIENT_ID

Field	Required	Description
username	Yes	API user username
password	Yes	API user password
name	No	Optional token label

Returns: token string and user info. Tokens do not expire - they remain valid until revoked.

Verify Token

GET /v1/auth/me
Authorization: Bearer <token>
X-Tenant: CLIENT_ID

Returns: authenticated user ID, username, and role.

Revoke Token

DELETE /v1/auth/token
Authorization: Bearer <token>
X-Tenant: CLIENT_ID

Revokes the token used in the request.

Shipments

Create Shipment

POST /v1/shipments
Permission: api_shipments_create

Accepts nested or flat JSON format.

Nested format (recommended):

Field	Required	Description
date	No	Shipment date (YYYY-MM-DD, defaults to today)
service_id or service_code	Yes	Service to use
sender.company	Yes	Sender company name
sender.country	Yes	2-letter country code
sender.city, .state, .zip	No	Sender location
sender.address1	No	Street address
sender.name, .phone, .email	No	Contact info
sender.customer_id	No	Link to existing customer
recipient.company	Yes	Recipient company name
recipient.country	Yes	2-letter country code
recipient.*	No	Same fields as sender
package.weight	Yes	Total weight
package.pieces	No	Number of pieces (default 1)
package.weight_unit	No	lb or kg (default lb)
package.length, .width, .height	No	Dimensions
contents	No	Package contents description
customs_value	No	Declared value for customs
cod_amount	No	Cash on delivery amount
reference	No	Customer reference
notes	No	Shipment notes
pieces	No	Array of individual piece objects

Flat format alternative: Use sender_company, recipient_company, total_weight, etc. as top-level fields.

Returns: Shipment ID, AWB number, status. If the service uses a carrier API (e.g., FedEx), includes carrier submission result and tracking number.

Get Shipment

GET /v1/shipments/{awb}
Permission: api_shipments_read

Returns full shipment details: addresses, package info, service, charges, carrier status, and individual pieces.

Cancel Shipment

DELETE /v1/shipments/{awb}
Permission: api_shipments_cancel

Cancels the shipment and its carrier submission (if applicable). Only works for shipments with status Created or In Transit.

Track Shipment

GET /v1/shipments/{awb}/track
Permission: api_tracking

Returns AWB, current status, and array of tracking events. Each event includes status, description, date, time, city, and country.

Download Label

GET /v1/shipments/{awb}/label
Permission: api_labels

Returns the shipping label as a base64-encoded PDF string. Uses the carrier label when available, otherwise uses the internal label template.

Rates

Quote Rate

POST /v1/rates/quote
Permission: api_rates

Field	Required	Description
service_id or service_code	Yes	Service to quote
sender.country, .zip	Yes	Origin location
recipient.country, .zip	Yes	Destination location
package.weight	Yes	Package weight
package.pieces	No	Number of pieces (default 1)
package.weight_unit	No	lb or kg (default lb)
cod_amount	No	COD amount
customs_value	No	Customs value
distance	No	Distance in km (for distance-based services)
package_type_id	No	Filter to a specific package type

Returns: service info, and for each package type: base rate, itemized surcharges, total, zone used, and chargeable weight.

Note: If the API user is linked to a customer, rates use that customer's pricing configuration.

Services

List Services

GET /v1/services
GET /v1/services?type=domestic
GET /v1/services?type=international
Permission: api_services

Returns active services with their ID, code, name, service type, charge type, and available package types.

Pickups

Create Pickup

POST /v1/pickups
Permission: api_pickups_create

Field	Required	Description
customer_id	Yes	Customer ID
address.company	Yes	Pickup company
address.address1	Yes	Street address
address.city	Yes	City
address.country	Yes	2-letter country code
scheduled_date	Yes	Pickup date (YYYY-MM-DD)
ready_time	No	Earliest pickup time (HH:MM:SS)
latest_time	No	Latest pickup time (HH:MM:SS)
num_packages	No	Package count
total_weight	No	Total weight
destination	No	domestic or international
payment_type	No	prepaid or collect
notes	No	Pickup notes
awb	No	Link to an existing shipment AWB

Returns: pickup ID, confirmation number, status, assigned driver (if auto-assigned), and all details.

Get Pickup

GET /v1/pickups/{id}
Permission: api_pickups_read

Returns full pickup details including address, schedule, driver assignment, and status.

Cancel Pickup

DELETE /v1/pickups/{id}
Permission: api_pickups_cancel

Cancels the pickup. Cannot cancel completed or already-cancelled pickups.

CORS

All API endpoints include CORS headers allowing cross-origin requests:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Requested-With, X-Tenant

OPTIONS requests return 200 OK for preflight checks.

Tips

• Use service_code instead of service_id for more readable integrations - codes are stable across environments.
• The nested JSON format is recommended for clarity, but the flat format works identically.
• Label downloads return base64 - decode and save as PDF on your end.
• Rate quotes return multiple package types per service - filter by package_type_id if only one is needed.

Next: Errors & Rate Limits →