openapi: 3.0.0
info:
title: 'Cargomatic Public 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
x-amazon-apigateway-cors:
allowOrigins:
- "*"
allowCredentials: true
exposeHeaders:
- "x-apigateway-header"
- "x-amz-date"
- "content-type"
maxAge: 3600
allowMethods:
- "*"
allowHeaders":
- "x-apigateway-header"
- "x-amz-date"
- "content-type"
- "Authorization"
servers:
- url: https://api-acceptance.cargomatic.com
tags:
- name: Authorization
description: Endpoints dealing with authenticating to the API
- name: Shipper
description: Endpoints for Cargomatic Shippers
- name: Carrier
description: Endpoints for Cargomatic Carriers and Drivers
- name: Stops
description: Endpoints for managing shipment stops
paths:
/auth:
post:
operationId: auth
summary: Retrieves an access token.
description: >-
This route returns an access `token` which is to be used for all subsequent requests in the Authorization header.
tags:
- Authorization
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthRequestBody'
responses:
'200':
description: 'Status Code 200: Successful Response - the request was successful!'
content:
application/json:
schema:
$ref: '#/components/schemas/AuthResponse'
'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'
/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
/shipments/appointment:
post:
operationId: updateAppointment
summary: Updates an existing appointment with a new status, start time, and/or end time. Requires the client to send at least one of new `windowStart` time, new `windowEnd` time, or `appointmentConfirmed`.
tags:
- Carrier
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateShipmentRequest'
responses:
'200':
description: 'Status Code 200: Successful Response - the request was successful!'
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateShipmentResponse'
'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/accept:
post:
operationId: acceptShipment
summary: Accepts a Shipment
tags:
- Carrier
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptShipmentRequest'
responses:
'200':
description: 'Status Code 200: Successful Response - the request was successful!'
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptShipmentResponse'
'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'
/carrier/{carrierid}/driver:
post:
operationId: createDriver
summary: Creates a new Driver
tags:
- Carrier
security:
- bearerAuth: []
parameters:
- name: carrierid
in: path
description: Id of the carrier
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDriverRequest'
responses:
'200':
description: 'Status Code 200: Successful Response - the request was successful!'
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDriverResponse'
'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'
/shipment/assign:
post:
operationId: assignDriver
summary: Assigna a Driver to a Shipment
tags:
- Carrier
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AssignDriverRequest'
responses:
'200':
description: 'Status Code 200: Successful Response - the request was successful!'
content:
application/json:
schema:
$ref: '#/components/schemas/AssignDriverResponse'
'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'
/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:
- Stops
- 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:
- Stops
- 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:
- Stops
- 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'
/create-documents:
post:
operationId: createDocuments
summary: endpoint for uploading documents
description: >-
` Use this endpoint to create 1 or multiple document records within our system and use the response to
upload the actual files to our secure s3 buckets
`
tags:
- Document
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UploadDocumentRequest'
responses:
'200':
description: 'Status Code 200: Successful Response - the request was successful!'
content:
application/json:
schema:
$ref: '#/components/schemas/UploadDocumentResponse'
'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'
/get-documents:
post:
operationId: getDocuments
summary: Retrive document on a specified entity
description: >-
` Use this endpoint to retrive document links and metadata attached to specific entities `
tags:
- Document
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GetDocumentRequest'
responses:
'200':
description: 'Status Code 200: Successful Response - the request was successful!'
content:
application/json:
schema:
$ref: '#/components/schemas/GetDocumentResponse'
'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:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
AuthRequestBody:
type: object
properties:
username:
type: string
password:
type: string
example:
username: 'Username'
password: 'MyPassword'
required:
- username
- password
AuthResponse:
type: object
properties:
success:
type: boolean
token:
type: string
example:
success: true
token: '{token-value}'
BadRequestResponse:
type: object
properties:
message:
type: string
example:
message: 'Invalid Request Body'
InternalServerErrorResponse:
type: object
properties:
message:
type: string
example:
message: 'Internal Server Error'
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`.
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
QuoteRequestPallets:
type: object
required:
- type
- quantity
- length
- width
- height
- languageCodeId
- currency
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`.
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
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-12T03:41:08.784Z
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-19T03:41:08Z
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-12T03:41:06.029Z
shipper:
type: string
example: badri.shipper@cargomatic.com
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.
OrderRequestEquipments:
type: object
required:
- equipment_id
- _equipmentType
properties:
equipment_id:
type: string
example: AAAU1231234
_equipmentType:
type: string
example: container
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
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cargomatic/refs/heads/main/openapi/cargomatic-openapi-original.yml