openapi: 3.0.0
info:
title: Cargomatic Public Authorization Shipper API
description: '## Welcome to the Cargomatic API!
Our quoting, booking, and status APIs allow you to automate common workflows similar to features available within the Cargomatic portal.
Please reach out to [apisupport@cargomatic.com](apisupport@cargomatic.com) for sandbox credentials to get started.'
version: 3.0.0
servers:
- url: https://api-acceptance.cargomatic.com
tags:
- name: Shipper
description: Endpoints for Cargomatic Shippers
paths:
/quotes:
post:
operationId: createQuote
summary: Creates a quote
description: 'Creates a quote based on the factors provided in the request body.
This API endpoint is only accessible by Shippers and Admins!'
tags:
- Shipper
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QuoteRequest'
responses:
'200':
description: 'Status Code 200: Successful Response - the request was successful!'
content:
application/json:
schema:
$ref: '#/components/schemas/QuoteResponse'
'400':
description: 'Status Code 400: Bad Request Response - the request header and/or body is invalid'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'500':
description: 'StatusCode 500: Internal Server Error Response - there''s a problem with the Public API service'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
/orders:
post:
operationId: createOrder
summary: Creates an order
description: Creates an order based on the factors provided in the request body. This API endpoint can only be accessed by Shippers!
tags:
- Shipper
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRequest'
responses:
'200':
description: 'Status Code 200: Successful Response - the request was successful!'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'400':
description: 'Status Code 400: Bad Request Response - the request header and/or body is invalid'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'500':
description: 'StatusCode 500: Internal Server Error Response - there''s a problem with the Public API service'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
/shipments:
post:
operationId: createShipment
summary: Create a shipment/offer
description: 'Creates a shipment based on the factors provided in the request body. This API endpoint can only be accessed by Admins and Shippers!
`action` - add, update, cancel'
tags:
- Shipper
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OfferRequest'
responses:
'200':
description: 'Status Code 200: Successful Response - the request was successful!'
content:
application/json:
schema:
$ref: '#/components/schemas/OfferResponse'
'400':
description: 'Status Code 400: Bad Request Response - the request header and/or body is invalid'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'500':
description: 'StatusCode 500: Internal Server Error Response - there''s a problem with the Public API service'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
get:
operationId: listShipments
summary: Lists all shipments with a pagination option
tags:
- Shipper
security:
- bearerAuth: []
parameters:
- name: page
in: query
description: Page number, indicates the page of results that you want returned. Default value is 1.
required: false
schema:
type: number
- name: per_page
in: query
description: \# of results per page
required: false
schema:
type: number
responses:
'200':
description: 'Status Code 200: Successful Response - the request was successful!'
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentResponse'
'400':
description: 'Status Code 400: Bad Request Response - the request header and/or body is invalid'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'500':
description: 'StatusCode 500: Internal Server Error Response - there''s a problem with the Public API service'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
/shipments/status:
get:
operationId: shipmentStatus
summary: Returns a shipment with status info
description: ''
tags:
- Shipper
security:
- bearerAuth: []
parameters:
- name: shipmentReference
in: query
description: Shipment Id
required: true
schema:
type: string
responses:
'200':
description: 'Status Code 200: Successful Response - the request was successful!'
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentResponse'
'400':
description: 'Status Code 400: Bad Request Response - the request header and/or body is invalid'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'500':
description: 'StatusCode 500: Internal Server Error Response - there''s a problem with the Public API service'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
/webhooks/loads:
post:
operationId: processLoads
summary: Process loads
tags:
- Shipper
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json: {}
responses:
'204':
description: Status 204 Response
/stops/complete:
post:
operationId: completeStop
summary: Mark a stop as complete
description: Marks a stop as "complete". The `stopId`, and `shipmentReference` is required for all shipment types. If the shipment is shorthaul, only admins can access this route and file data must also be provided. If the shipment is drayage, `chassis`, `trailerId`, and `containerId` may be required.
tags:
- Shipper
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CompleteStopRequest'
responses:
'200':
description: 'Status Code 200: Successful Response - the request was successful!'
content:
application/json:
schema:
$ref: '#/components/schemas/CompleteStopResponse'
'400':
description: 'Status Code 400: Bad Request Response - the request header and/or body is invalid'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
/stops/transition:
post:
operationId: arriveAtStop
summary: Mark a stop as "arrived"
description: 'Marks a stop as "arrived". `status`, `stopId`, and `shipmentReference` are required. The only acceptable value for `status` is `arrived` (see example request body). If `date` is not provided, the current time will be used as the arrival time.
Admins, shippers, carriers, and drivers are authorized to use this API endpoint.'
tags:
- Shipper
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ArriveAtStopRequest'
responses:
'200':
description: 'Status Code 200: Successful Response - the request was successful!'
content:
application/json:
schema:
$ref: '#/components/schemas/ArriveAtStopResponse'
'400':
description: 'Status Code 400: Bad Request Response - the request header and/or body is invalid'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'500':
description: 'Status Code 500: Internal Server Error Response - there''s a problem with the Public API service'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
/stops/add:
post:
operationId: addStop
summary: Add additional stops to a shipment
description: '`shipmentReference` and at least one new stop are required. Each new stop must include `address`, `action`, `name`, `sequence`, `windowStart`, `windowEnd`, and other fields dependent on the type of shipment.
For US-based clients, the address must include street address, city, state, and zipcode. The `action` is either "pickup" or "delivery". The sequence number is sequence of the stop within the shipment. The `name` of the stop is the location name. `windowStart` is when the pickup/delivery window starts for that stop. `windowEnd` is when the pickup/delivery window ends for that stop.
If the shipment is shorthaul, the new stop must include load data and it must be indicated whether the cargo is a full truckload or not. If the shipment is drayage, the new stop must indicate whether the container is empty or not and location must be included.'
tags:
- Shipper
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddStopRequest'
responses:
'200':
description: 'Status Code 200: Successful Response - the request was successful!'
content:
application/json:
schema:
$ref: '#/components/schemas/AddStopResponse'
'400':
description: 'Status Code 400: Bad Request Response - the request header and/or body is invalid'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'500':
description: 'Status Code 500: Internal Server Error Response - there''s a problem with the Public API service'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
components:
schemas:
QuoteRequestStops:
type: object
required:
- action
- location
properties:
action:
type: string
example: pickup
description: Acceptable values for `action` are `pickup` and `deliver`.
location:
type: object
required:
- name
- address
properties:
name:
type: string
example: Atlas Marine
address:
type: string
example: 1550 Cota Ave Long Beach CA 90813
AddStopRequest:
type: object
required:
- shipmentReference
- newStops
properties:
shipmentReference:
type: string
example: ABC-123
newStops:
type: array
items:
type: object
required:
- sequence
- address
- action
- name
- windowStart
- windowEnd
properties:
sequence:
type: number
example: 1
address:
type: string
example: 1550 Cota Ave, Long Beach, CA 90813, USA
action:
type: string
example: pickup
name:
type: string
example: Atlas Marine
windowStart:
type: string
example: '2023-01-01T21:00:00.000Z'
windowEnd:
type: string
example: '2024-01-01T21:00:00.000Z'
fullTruckload:
type: boolean
example: false
isEmptyContainer:
type: boolean
example: true
loads:
type: array
items:
type: object
properties:
type:
type: string
example: pallets
quantity:
type: number
width:
type: number
length:
type: number
OrderRequestShipmentsStagingStops:
type: object
properties:
sequence:
type: integer
format: int32
example: 1
action:
type: string
example: pickup
empty:
type: boolean
location:
$ref: '#/components/schemas/OrderRequestLocation'
window_start:
type: string
format: date-time
example: 2022-09-09 19:00:45.440000+00:00
window_end:
type: string
format: date-time
example: 2022-09-09 22:00:50.317000+00:00
equipments:
type: array
items:
type: object
properties:
equipment_id:
type: string
example: AAAU1231234
_equipmentType:
type: string
example: container
InternalServerErrorResponse:
type: object
properties:
message:
type: string
example:
message: Internal Server Error
QuoteResponse:
type: object
properties:
success:
type: boolean
quote:
type: object
properties:
full_truckload:
type: boolean
shipment_type:
type: string
example: shorthaul
weight:
type: integer
format: int32
example: 4000
distance:
type: integer
format: int32
example: 4276
courier:
type: boolean
created_at:
type: string
format: date-time
example: 2023-07-12 03:41:08.784000+00:00
total_cost:
type: string
example: 190.85
origin:
type: object
properties:
address:
type: string
example: 1550 Cota Ave Long Beach CA 90813 USA
coords:
type: array
items:
type: number
example: -118.2162816
name:
type: string
example: Atlas Marine
destination:
type: object
properties:
address:
type: string
example: 211 E Ocean Blvd Long Beach CA 90802
coords:
type: array
items:
type: number
example: -118.19072819999997
name:
type: string
example: Cargomatic
loads:
type: array
items:
type: object
properties:
type:
type: string
example: pallets
dimensional_units:
type: string
example: in
quantity:
type: integer
format: int32
example: 3
width:
type: integer
format: int32
example: 40
height:
type: integer
format: int32
example: 60
length:
type: integer
format: int32
example: 48
weight:
type: integer
format: int32
example: 4000
spaces:
type: integer
format: int32
example: 3
weight_units:
type: string
example: lb
_id:
type: string
example: 64ae20d4814c928bbafbeade
quote_id:
type: string
example: BAD-QT-1796
expiration_date:
type: string
format: date-time
example: 2023-07-19 03:41:08+00:00
receivables:
type: array
items:
type: object
properties:
message:
type: string
example: Residential
value:
type: integer
format: int32
example: 35
timestamp:
type: string
format: date-time
example: 2023-07-12 03:41:06.029000+00:00
shipper:
type: string
example: badri.shipper@cargomatic.com
OrderRequestShipmentsStaging:
type: object
properties:
weight:
type: integer
format: int32
example: 35000
stops:
type: array
items:
$ref: '#/components/schemas/OrderRequestShipmentsStagingStops'
QuoteRequest:
type: object
required:
- full_truckload
- stops
- weight
properties:
accessorials:
type: array
items:
type: object
properties:
type:
type: string
example: residential_delivery
description: Allowed values for type are `cfs`, `hazmat`, `liftgate_origin`, `liftgate_destination`, `residential_delivery`, `room_of_choice`, `white_glove`, `airport_pickup`, `tsa_certification`, `flatbed_truck`, `two_man` and `inside_delivery`.
courier:
type: boolean
distance:
type: integer
format: int32
example: 12583
loads:
type: array
items:
type: object
$ref: '#/components/schemas/QuoteRequestLoads'
market:
type: string
example: SFO
description: The valid values for `market` are the three letter identifiers for the market, like LAX, SFO, ATL, etc.
stops:
type: array
items:
$ref: '#/components/schemas/QuoteRequestStops'
weight:
description: Total weight of the shipment.
type: integer
format: int32
example: 40000
weight_units:
description: Default unit is `lb`.
type: string
example: lb
shipper:
type: object
properties:
_id:
type: string
example: 62879ea006bfa2d915861ba6
full_truckload:
type: boolean
example: true
description: If `full_truckload` is `false`, `loads` is a required field.
shipment_type:
type: string
example: shorthaul
CompleteStopResponse:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
stopId:
type: string
status:
type: string
example: complete
locationName:
type: string
locationAddress:
type: string
windowStart:
type: string
example: '2021-06-02T15:54:29.728Z'
windowEnd:
type: string
example: '2021-07-02T15:54:29.728Z'
appointmentConfirmed:
type: boolean
complete:
type: boolean
missingDocs:
type: boolean
documents:
type: array
items:
type: string
example: stop_info.txt
OrderRequestLocation:
type: object
required:
- name
- address
properties:
name:
type: string
example: APMT
description: Name of the location. Can be an internal identifier, name of the location (ex. LAX Terminal 7), etc.
address:
type: string
example: 2500 Navy Way San Pedro CA 90731
description: US-based addresses must include street address, suite (if applicable), state, and zip code.
AddStopResponse:
type: object
properties:
success:
type: boolean
shipment:
type: object
properties:
market:
type: object
properties:
name:
type: string
example: San Antonio
code:
type: string
example: SAT
_id:
type: string
shipment_id:
type: string
example: ABC-123
stops:
type: array
items:
type: object
properties:
_id:
type: string
example: stopID123
action:
type: string
example: deliver
full_truckload:
type: boolean
example: false
location:
type: array
items:
type: object
properties:
id:
type: string
example: 1234567890z9310
address:
type: string
example: 211 E. Ocean Blvd, Suite 350, Long Beach, CA 90802, USA
street:
type: string
example: 211 E. Ocean Blvd
suite_or_apt:
type: string
example: Suite 350
zipcode:
type: string
example: '90802'
city:
type: string
example: Long Beach
state:
type: string
example: CA
lng:
type: number
example: -123.456789
lat:
type: number
example: 37.1234567
status:
type: string
example: unstarted
shipment_type:
type: string
example: shorthaul
sequence:
type: number
example: 2
window_start:
type: string
example: 2023-07-24 23:30:00+00:00
window_end:
type: string
example: 2023-07-24 23:30:00+00:00
OfferResponse:
type: object
properties:
action:
type: string
example: add
shipment:
type: object
properties:
shipment_type:
type: string
example: shorthaul
shipper:
type: string
example: shipper@cargomatic.com
reference_numbers:
type: array
items:
type: object
properties:
name:
type: string
example: My Primary Reference
value:
type: string
example: cargomatic123
primary:
type: boolean
stops:
type: array
items:
type: object
properties:
sequence:
type: integer
format: int32
example: 1
location:
type: object
properties:
name:
type: string
example: Cargomatic HQ
address:
type: string
example: 211 E. Ocean Blvd Long Beach CA 90802
suite_or_apt:
type: string
example: Suite 350
loads:
type: array
items:
type: object
properties:
type:
type: string
example: pallets
quantity:
type: integer
format: int32
example: 5
width:
type: integer
format: int32
example: 40
height:
type: integer
format: int32
example: 48
length:
type: integer
format: int32
example: 40
weight:
type: integer
format: int32
example: 2500
contacts:
type: array
items:
type: object
properties:
name:
type: string
example: support
email:
type: string
example: support@cargomatic.com
phone:
type: string
example: 555-555-5555
action:
type: string
example: pickup
window_start:
type: string
format: date-time
example: 2022-03-31 18:00:00+00:00
window_end:
type: string
format: date-time
example: 2022-03-31 21:00:00+00:00
reference_numbers:
type: array
items:
type: object
properties:
name:
type: string
example: My Stop Reference Number
value:
type: string
example: cargomatic123456
loads:
type: array
items:
type: object
properties:
type:
type: string
example: pallets
quantity:
type: integer
format: int32
example: 5
width:
type: integer
format: int32
example: 40
height:
type: integer
format: int32
example: 48
length:
type: integer
format: int32
example: 40
weight:
type: integer
format: int32
example: 2500
accessorials:
type: array
items:
type: object
properties:
type:
type: string
example: pallet_jack
weight:
type: integer
format: int32
example: 2500
notes:
type: string
example: These are my notes!
BadRequestResponse:
type: object
properties:
message:
type: string
example:
message: Invalid Request Body
QuoteRequestLoads:
type: object
description: 'If `full_truckload` is `false`, `loads` data are required: `loads` must contain at least one entry and the required data for each entry is `quantity`, `length`, `width`, `height`, and `weight`.'
required:
- quantity
- height
- length
- width
- dimensional_units
- weight_units
- type
properties:
type:
type: string
example: pallets
quantity:
type: integer
format: int32
example: 1
length:
type: integer
format: int32
example: 48
width:
type: integer
format: int32
example: 40
height:
type: integer
format: int32
example: 60
weight:
type: integer
format: int32
example: 0
weight_units:
type: string
example: lb
description: Default value is `lb`.
dimensional_units:
type: string
example: in
description: Default value is `in`.
languageCodeId:
type: string
example: en-us
distance_units:
type: string
example: mi
currency:
type: string
example: USD
temperature_units:
type: string
example: F
stackable:
type: boolean
example: false
description: Default value is `false`.
ArriveAtStopResponse:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
shipmentReference:
type: string
status:
type: string
example: arrived
stopId:
type: string
meta:
type: object
properties:
date:
type: string
ArriveAtStopRequest:
type: object
properties:
shipmentReference:
type: string
example: ABC-123
stopId:
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cargomatic/refs/heads/main/openapi/cargomatic-shipper-api-openapi.yml