openapi: 3.2.0
info:
version: 1.2.1
title: Emerge Public Tenders 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: Tenders
paths:
/tenders:
summary: Creates a tender
description: Tenders allow the shipper to award the shipment to Emerge Transportation. The Marketplace workflow does allow Emerge to reject a tender. At this time, however, a rejected tender will be performed manually to ensure the best customer experience and to simplify the integration experience.
post:
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
tags:
- Tenders
description: The opportunity_id must be included in the create tender call.
summary: Creates a tender
security:
- BearerAuth: []
requestBody:
description: Structure of the call to create the tender
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/tenders'
responses:
'200':
description: 200 | Success. A new tender has been created and an tender object is returned
content:
application/json:
schema:
$ref: '#/components/schemas/201_createtender_response'
'400':
description: 400 | Bad Request. A bad request was made. Please try again
content:
application/json:
schema:
$ref: '#/components/schemas/400_badrequest_createtender_response'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/tenders/{tender_id}:
get:
tags:
- Tenders
summary: Retrieves the details of a tender.
description: Tenders allow the shipper to award the shipment to Emerge Transportation. The get tender endpoint allows a developer to retrieve a specific tender.
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: tender_id
schema:
type: integer
minimum: 1
example: 112020
required: true
description: ID of the tender
responses:
'200':
description: 200 | OK. Returns the current tender.
content:
application/json:
schema:
$ref: '#/components/schemas/201_createtender_response'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
put:
tags:
- Tenders
summary: Updates a tender.
description: The shipment_id and rate value must be included in the update tender call.
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: tender_id
schema:
type: integer
minimum: 1
example: 112020
required: true
description: ID of the tender
requestBody:
description: Structure of the call to create the tender
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/tenders'
responses:
'200':
description: 200 | OK. The tender has been updated and tender object is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/201_createtender_response'
'400':
description: 400 | Bad Request. A bad request was made. Please try again
content:
application/json:
schema:
$ref: '#/components/schemas/400_badrequest_updatetender_response'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/tenders/{tender_id}/cancel:
post:
tags:
- Tenders
summary: Cancel a tender.
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: tender_id
schema:
type: integer
minimum: 1
example: 112020
required: true
description: ID of the tender
responses:
'200':
description: 200 | OK. The tender has been canceled.
content:
application/json:
schema:
$ref: '#/components/schemas/errorcode_zero_without_message_object'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'409':
$ref: '#/components/responses/409'
components:
schemas:
409_response:
type: object
properties:
error:
type: object
properties:
code:
type: integer
example: 409
messages:
type: array
items:
type: string
example: The tender status is invalid.
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
request_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
- Pallet
- Box
- Crate
- Bag
- Coils
- Drums
- Reels
- Rolls
- TubesOrPipes
- Slipsheets
- Bale
- Bucket
- Bundle
- Can
- Carton
- Case
- Cylinder
- Pail
- Pieces
- Skid
example: Other
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
- Moderate
- Low
- None
type: string
example: High
class_id:
description: The class of the hazmat load
enum:
- MassExplosiveHazard
- ProjectionHazard
- MassFireHazard
- MinorExplosionHazard
- VeryInsensitiveExplosives
- ExtremelyInsensitiveExplosives
- FlammableGases
- NonFlammableGases
- PoisonousOrToxic
- CombustibleLiquids
- FlammableSolid
- SpontaneouslyCombustibleMaterial
- DangerousWhenWet
- Oxidizer
- OrganicPeroxide
- PoisonousOrToxicMaterial
- InfectiousSubstance
- RadioactiveMaterial
- Corrosives
- MiscellaneousDangerousGoods
type: string
example: ExtremelyInsensitiveExplosives
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'
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'
400_badrequest_updatetender_response:
type: object
properties:
error:
type: object
properties:
code:
description: HTTP code
type: integer
example: 400
detailed_errors:
description: Error messages
type: array
items:
type: object
properties:
key:
type: string
example: shipment_id
value:
type: string
example: shipment_id must not be empty.
messages:
type: array
items:
type: string
example: Validation failed.
length_of_haul_result_object:
description: The length of haul override.
type: object
properties:
manual:
type: integer
example: 2
equipment_size_object:
description: The length of the trailer.
type: integer
minimum: 1
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
400_badrequest_createtender_response:
type: object
properties:
error:
type: object
properties:
code:
description: HTTP code
type: integer
example: 400
detailed_errors:
description: Error messages
type: array
items:
type: object
properties:
key:
type: string
example: opportunity_id
value:
type: string
example: opportunity_id must not be empty.
messages:
type: array
items:
type: string
example: Validation failed.
request_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
- Customer
- Appointment
- Bol
- Delivery
- Pickup
- PickupConfirmation
- Po
- Pro
- Trailer
example: Customer
value:
description: The reference value.
type: string
example: CustRef123
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: