openapi: 3.2.0
info:
version: 1.2.1
title: Emerge Public Shipments API
description: 'The Emerge public API provides partner developers with access to core capabilities of the Emerge platform.
The current version of the API is v1.2.1. This API will evolve as the features in Emerge''s product evolve.
# Get Started
The Emerge API is a ''restish'' API and is designed to allow you to work with objects using familiar HTTP verbs like
* POST
* PUT
* DELETE
* GET
All production level API requests are made to:
`https://api.emergemarket.io`
The testing sandbox is available during development and for testing:
`https://demo-api.emergemarket.dev/`
## Compatibility Policy
Emerge APIs are versioned using a prefix in the endpoint URL. Within an API version, we only make backward-compatible changes. This mean that when a provider integrates with our REST API, the API will continue to work until the version is deprecated. If we have to create a change that is not compatible with the current version, a new version will be created.
### Non-Breaking Changes
* Adding additional optional fields on the API request.
* Adding additional fields on the API response.
* Adding an HTTP method to an API.
* Adding optional headers.
* Adding additional accepted enumerated values.
* Changing Error Response descriptions.
* Added Rate Limits.
### Breaking Changes
* Removing or renaming an API method or endpoint.
* Removing or renaming existing API request or response fields.
* Removing or renaming enumerated values.
* Changing the Error Response values.
### Deprecation Policy
* Emerge will continue to support deprecated APIs for 1 year.
* Documentation will also be updated and integrating providers will be notified via email when a version or endpoint is being deprecated.
# Workflows
The Emerge API is designed to support two primary workflows for a shipper organization: An opportunity-to-tender workflow and an opportunity-to-award workflow.
## Opportunity-to-tender
The opportunity-to-tender is the most common workflow of an integrating system. In this workflow, the Emerge system is used to source the live capacity as well as to tender through Emerge to that live capacity. The benefit of this workflow is that all information, from opportunity through tender and finally tracking is maintained in the Emerge system. The basic steps of this workflow include:
1. Create an Opportunity.
2. Post to the shipper''s (your) marketplace.
3. Receive options from carriers. Retrieval is achieved through a webhook published by you for receiving option events.
4. Tender to a carrier.
5. Get tracking updates through webhook.
## Opportunity-to-award
The opportunity-to-award workflow supports customers who are using the Emerge platform in conjunction with their TMS. In this workflow, Emerge is used as a capacity provider while the TMS is used on the execution side. The basic steps of this workflow include:
1. Create an opportunity.
2. Post to the shipper''s (your) marketplace.
3. Receive options from carriers. Retrieval is achieved through a webhook published by you for receiving option events.
4. Award to a carrier.
Note that awarding to the carrier will automatically close the opportunity, notify the carrier that they "won" the bidding and notify the remaining carriers that they did not win the bidding.
The opportunity-to-award workflow requires that the customer''s TMS tenders to the winning carrier. This happens outside of the Emerge system.
'
servers:
- url: https://api.emergemarket.io/v1
description: Primary production endpoint
- url: https://demo-api.emergemarket.dev/v1
description: Testing sandbox endpoint
tags:
- name: Shipments
paths:
/shipments/{shipment_id}:
get:
tags:
- Shipments
summary: Get shipment.
description: The Get Shipment end point allows shippers to get the full details of a shipment by it's ID.
security:
- BearerAuth: []
parameters:
- name: organization-id
in: header
description: The Organization GUID for the request. This Emerge provided value is only required if your integration user is in multiple organizations. Note that if multiple headers are passed, the organization from the first instance of the header will be used.
example:
- 070C895C-AE61-4629-A603-829FC54CD816
required: false
schema:
type: string
- in: path
name: shipment_id
schema:
type: integer
minimum: 1
example: 12345
required: true
description: ID of the shipment
responses:
'200':
description: 200 | OK. Returns shipment details.
content:
application/json:
schema:
$ref: '#/components/schemas/200_getshipment_response'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
components:
schemas:
equipment_type_id_object:
description: The equipment type identifier.
type: string
enum:
- Other: 0
- Flatbed: 1
- Reefer: 3
- Stepdeck: 4
- Rgn: 5
- Van: 6
- Drayage: 7
- Dump: 8
- VanOrReefer: 9
- TrailerPoolInterchange
- 10
- PowerOnly: 11
- Conestoga: 12
- MaxiTrailer: 38
- Intermodal: 82
- BoxTruck: 84
- Hotshot: 85
- SprinterVan: 86
- StraightTruck: 87
example: 6
equipment_size_object:
description: The length of the trailer.
type: integer
minimum: 1
example: 2
commodities_object:
description: A description of the items to be carried by the capacity provider.
type: array
items:
type: object
required:
- name
- weight
properties:
id:
description: The commodity identifier.
type: integer
default: 0
name:
description: The name and description of the commodity.
type: string
example: FAK
weight:
description: The weight of the commodity in lbs.
type: integer
example: 100
quantity_unit_id:
description: The type of unit the commodity is moved on.
type: string
enum:
- Other: 0
- Pallet: 1
- Box: 2
- Crate: 3
- Bag: 4
- Coils: 5
- Drums: 6
- Reels: 7
- Rolls: 8
- TubesOrPipes: 9
- Slipsheets: 10
- Bale: 11
- Bucket: 12
- Bundle: 13
- Can: 14
- Carton: 15
- Case: 16
- Cylinder: 17
- Pail: 18
- Pieces: 19
- Skid: 20
example: 0
unit_count:
description: The unit count of the commodity.
type: integer
example: 2
piece_count:
description: The piece count of the commodity.
type: integer
example: 24
length:
description: The length of the commodity.
type: integer
example: 48
width:
description: The width of the commodity.
type: integer
example: 40
height:
description: The height of the commodity.
type: integer
example: 60
is_stackable:
description: Flag identifying a stackable commodity. Default value is false.
type: boolean
default: false
example: false
is_hazmat:
description: Flag identifying a hazmat commodity. Default value is false.
type: boolean
default: false
example: true
hazmat:
type: object
properties:
identification_number:
description: The hazmat identification number for the dangerous substances.
type: string
example: UN1000
packing_group_id:
description: The packing group identifier for the hazmat load.
enum:
- High: 1
- Moderate: 2
- Low: 3
- None: 4
type: string
example: 1
class_id:
description: The class of the hazmat load
enum:
- MassExplosiveHazard: 1
- ProjectionHazard: 2
- MassFireHazard: 3
- MinorExplosionHazard: 4
- VeryInsensitiveExplosives: 5
- ExtremelyInsensitiveExplosives: 6
- FlammableGases: 7
- NonFlammableGases: 8
- PoisonousOrToxic: 9
- CombustibleLiquids: 10
- FlammableSolid: 11
- SpontaneouslyCombustibleMaterial: 12
- DangerousWhenWet: 13
- Oxidizer: 14
- OrganicPeroxide: 15
- PoisonousOrToxicMaterial: 16
- InfectiousSubstance: 17
- RadioactiveMaterial: 18
- Corrosives: 19
- MiscellaneousDangerousGoods: 20
type: string
example: 6
emergency_contact:
description: The person to be contacted regarding an emergency with this Hazmat load.
type: object
properties:
name:
description: The name of the contact responsible for the hazmat load.
type: string
example: Kyle Jepsen
phone:
description: The phone number of the emergency contact.
$ref: '#/components/schemas/phone_response_object'
length_of_haul_result_object:
description: The length of haul override.
type: object
properties:
manual:
type: integer
example: 2
phone_response_object:
description: Phone Object
type: object
properties:
number:
description: The 10 digit phone number.
type: string
example: '1234567890'
extension_number:
description: The extension number, supports up to 5 digits.
type: string
example: '1234'
shipment_status:
description: The Shipment status.
type: integer
enum:
- Open: 1
- Tendered: 2
- Closed: 3
- Canceled: 4
- Covered: 5
example: 1
accessorials_object:
description: The accessorials associated with the load.
type: array
items:
type: object
properties:
accessorial_type_id:
description: The type of accessorial required.
Enum: {"Straps":127} {"ETracks":128} {"LoadLocks":129} {"BlockAndBrace":130} {"Blankets":131} {"DriverLoadAssist":132} {"DriverTailgateAssist":133} {"EdgeProtector":134} {"BulkHeads":135} {"SmokedTarps":136} {"StandardTarps":137} {"VBoards":138} {"CoilRacks":139} {"PipeStakes":140} {"Headboard":141} {"Dunnage":142} {"Ramps":143} {"LoadLevelers":144} {"Chains":145} {"Other":146} {"TeamDrivers":147} {"PreCool":148} {"WoodenFloor":153} {"PersonalProtectiveEquipment":154} {"FtlInsideDelivery":155} {"Liftgate":156} {"FoodGrade":157} {"TWICRequired":158} {"TankerEndorsement":159} {"ProtectFromFreeze":160} {"LightScaleTicketRequired":161} {"PalletJack":162}
type: string
example: 131
value:
description: The accessorial quantity.
type: string
example: '1'
200_getshipment_response:
description: 200 | Ok. Returns shipment details.
type: object
properties:
response:
type: object
properties:
id:
type: integer
example: 1305583
opportunity:
type: object
properties:
id:
description: The opportunity ID
type: integer
example: 112020
organization_id:
description: The ID of the organization
type: integer
example: 6338
length_of_haul:
description: The calculated length of haul of the opportunity. Calculated in miles.
type: integer
example: 1084
length_of_haul_source_id:
description: The source of the length of haul calculation.
type: integer
example: 2
is_length_of_haul_override_enabled:
description: Boolean to indicate if the length of haul has been overridden.
type: boolean
example: false
stops:
$ref: '#/components/schemas/opportunity_response_stops_object'
notes:
$ref: '#/components/schemas/notes_object'
commodities:
$ref: '#/components/schemas/commodities_object'
assigned_user_id:
description: The user who is assigned to the opportunity.
type: integer
example: 1206858
references:
$ref: '#/components/schemas/references_object'
created_date:
description: The date the opportunity was created.
type: string
example: '2020-09-15T00:48:15.2148104+00:00'
modified_date:
description: The date the opportunity was modified.
type: string
example: '2020-09-15T00:48:15.2148104+00:00'
reference:
type: string
example: Q11112020
load_type_id:
$ref: '#/components/schemas/load_type_id_object'
equipment_type_id:
$ref: '#/components/schemas/equipment_type_id_object'
freight_provider_organization_equipment_type_id:
type: integer
example: 8679
equipment_size:
$ref: '#/components/schemas/equipment_size_object'
status_id:
$ref: '#/components/schemas/opportunity_status'
is_tracking_required:
type: boolean
example: false
is_hot_load:
type: boolean
example: false
type_id:
$ref: '#/components/schemas/opportunity_type'
is_priced_at:
type: boolean
example: false
is_deleted:
type: boolean
example: false
accessorials:
$ref: '#/components/schemas/accessorials_object'
tags:
$ref: '#/components/schemas/tags_object'
option_count:
description: The number of options currently in the marketplace.
type: integer
example: 0
reference:
type: string
example: S11019753
status_id:
$ref: '#/components/schemas/shipment_status'
current_tender:
type: object
properties:
id:
description: The tender ID. The tender ID is used in subsequent calls.
type: integer
example: 232343
assigned_user_id:
type: integer
example: 1305583
partner_id:
type: integer
example: 953
shipment_id:
type: integer
example: 16679
shipment_status_id:
$ref: '#/components/schemas/shipment_status'
load_type_id:
$ref: '#/components/schemas/load_type_id_object'
equipment_type_id:
$ref: '#/components/schemas/equipment_type_id_object'
freight_provider_organization_equipment_type_id:
type: integer
example: 974
freight_provider_organization_equipment_type_name:
type: string
example: Reefer
length_of_haul:
type: integer
example: 1084
length_of_haul_source_id:
description: The source of the length of haul calculation. Enumeration.
type: integer
example: 2
is_length_of_haul_override_enabled:
description: Boolean to indicate if the length of haul has been overridden.
type: boolean
example: false
length_of_haul_result:
$ref: '#/components/schemas/length_of_haul_result_object'
is_tracking_required:
type: boolean
example: false
rate:
description: The rate for the shipment in USD.
type: integer
example: 3866
rate_per_mile:
description: the rate for the shipment per mile in USD.
type: number
example: 3.57
fuel_rate:
description: The total rate for the fuel in USD.
type: number
example: 238.48
is_hot_load:
type: boolean
example: false
reefer_maximum_temperature:
description: The maximum temperature for reefer in degree Fahrenheit. Only valid for Reefer equipment type.
type: integer
example: 20
reefer_minimum_temperature:
description: The minimum temperature for reefer in degree Fahrenheit. Only valid for Reefer equipment type.
type: integer
example: 1
option_id:
description: The ID of the option associated with the tender
type: integer
example: 15618
option:
description: The option details
type: object
properties:
id:
description: The ID of the option associated with the tender
type: integer
example: 15618
modified_date:
type: string
example: '2020-09-18T20:39:20.8137938+00:00'
type_id:
type: integer
example: 5
opportunity_id:
type: integer
example: 16734
partner_id:
type: integer
example: 953
rate:
type: integer
example: 3866
rate_per_mile:
type: number
example: 3.57
fuel_rate:
type: number
example: 238.48
is_fuel_included:
type: boolean
example: false
line_haul_rate:
type: number
example: 3627.52
line_haul_rate_per_mile:
type: number
example: 3.35
notes:
$ref: '#/components/schemas/notes_object'
commodities:
$ref: '#/components/schemas/commodities_object'
stops:
$ref: '#/components/schemas/opportunity_response_stops_object'
references:
$ref: '#/components/schemas/references_object'
accessorials:
$ref: '#/components/schemas/accessorials_object'
notes:
$ref: '#/components/schemas/notes_object'
public_tracking_link:
description: This feature is limited to ProcureOS Pro plans
type: string
example: https://app.emergemarket.io/en/publictracking/12345
notes_object:
type: array
items:
description: This shipment is ready to go now. Please provide your best options.
properties:
note:
description: The specific note for the opportunity
type: string
opportunity_response_stops_object:
description: The stops associated with the opportunity. An opportunity must have at least two stops.
type: array
items:
type: object
required:
- order
- action_type_id
- postal_code
- city
- state
- country
- appointment_type_id
properties:
type_id:
description: The type of the stop.
type: string
enum:
- Origin: 1
- Middle: 2
- Destination: 3
example: 1
appointment_type_id:
description: The appointment type.
type: string
deprecated: true
enum:
- FCFS: 1
- Appointment: 2
example: 1
standardized_appointment_type_id:
description: The appointment type of the stop.
type: string
enum:
- FCFS: 1
- AppointmentScheduled: 2
- AppointmentRequired: 3
example: 1
standardized_loading_type_id:
description: The loading or unloading type of the stop.
type: string
enum:
- Live: 1
- DropTrailer: 2
example: 1
address1:
type: string
example: 3665 North Harbor Drive
address2:
type: string
example: string
city:
type: string
example: San Diego
contact:
type: object
properties:
name:
description: The contact name for the person at the stop.
type: string
example: Shipper
phone:
description: The phone number for the contact at the stop.
$ref: '#/components/schemas/phone_response_object'
email:
type: string
format: email
example: shipper@stonelogistics.com
country:
description: The country of the stop. Use abbreviation US or USA for United States of America and CA or CAN for Canada.
type: string
example: US
state:
description: The state of the stop. Use abbreviation.
type: string
example: CA
postal_code:
type: string
example: '92101'
latitude:
description: The latitude of the stop (use decimal representation)
type: number
example: 32.7325
longitude:
description: The longitude of the stop (use decimal representation)
type: number
example: -117.2011
name:
description: The name for the stop.
type: string
example: Stone Brewing Company
note:
description: Notes associated with the stop.
type: string
example: Check in with security prior to loading or unloading.
order:
description: The order of the stop-starting with 1.
type: integer
example: 1
action_type_id:
description: The stop action.
type: string
enum:
- Pick: 1
- Drop: 2
example: 1
schedule:
description: The schedule associated with the stop.
type: object
deprecated: true
properties:
date:
description: The date associated with the stop. Supports yyyy-mm-dd format.
type: string
example: '2021-10-06'
start_time:
description: Based upon the local time at the stop, the earliest time the load is available. Supports the format hh:mm:ss
type: string
example: '14:00:00'
end_time:
description: Based upon the local time at the stop, the last time the load is available. Supports the format hh:mm:ss
type: string
example: '20:00:00'
standardized_schedule:
description: The schedule associated with the stop.
type: object
properties:
start_date:
description: The earliest date associated with the stop. Supports yyyy-mm-dd format.
type: string
example: '2021-10-06'
start_time:
description: Based upon the local time at the stop, the earliest time the load is available. Supports the format hh:mm:ss
type: string
example: '14:00:00'
end_date:
description: The latest date associated with the stop. Supports yyyy-mm-dd format.
type: string
example: '2021-10-07'
end_time:
description: Based upon the local time at the stop, the last time the load is available. Supports the format hh:mm:ss
type: string
example: '20:00:00'
raw_address:
description: A string version of the full address
type: string
example: 23, Phoenix
is_schedule_required:
description: Determines if a shipper will allow the carrier to schedule an appointment on their behalf. Not recommended for the marketplace workflow
type: boolean
deprecated: true
example: false
403_forbidden_response:
type: object
properties:
error:
type: object
properties:
code:
description: HTTP code
type: integer
example: 403
messages:
description: Error messages
type: array
items:
type: string
example: Response status code does not indicate success 403 (Forbidden)
references_object:
required:
- Customer
description: References for the opportunity.
type: array
items:
type: object
properties:
type_id:
description: The type of reference.
type: string
enum:
- Other: 1
- Customer: 2
- Appointment: 3
- Bol: 4
- Delivery: 5
- Pickup: 6
- PickupConfirmation: 7
- Po: 8
- Pro: 9
- Trailer: 10
example: 2
value:
description: The reference value.
type: string
example: CustRef123
opportunity_type:
description: The Opportunity type.
type: integer
enum:
- Quote: 1
example: 1
load_type_id_object:
description: The load type identifier.
type: string
enum:
- FTL: 1
example: 1
opportunity_status:
description: The Opportunity status.
type: integer
enum:
- Open: 1
- Closed: 2
example: 1
tags_object:
description: Tags specific to the entity.
type: array
items:
type: string
example: firstTag
responses:
'403':
description: 403 | Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/403_forbidden_response'
'401':
description: 401 | Not Authorized. The request was not authorized. Please add or refresh your authorization token
'404':
description: 404 | Not Found. The requested resource was not found
securitySchemes:
BearerAuth:
type: http
scheme: bearer
x-tagGroups:
- name: Shipper API
tags:
- Authentication
- Network Partners
- Opportunities
- Options
- Awards
- Tenders
- Shipments
- name: Webhook Subscription API
tags:
- Webhooks
- name: Webhook Events
tags:
- Tracking Events
- Opportunity Awarded Event
- Opportunity Deleted Event
- Opportunity Not Awarded Event
- Options Changed Event
- Tender Status Updated Event
- Network Partner Updated Event
- Network Partner Deleted Event
- Current Marketplace Option Event