openapi: 3.0.0
info:
version: 1.2.1
title: Emerge Public 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:
<br />`https://api.emergemarket.io`
The testing sandbox is available during development and for testing:
<br />`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: Webhooks
description: "Webhooks are used to provide updates to the TMS when award or option events are generated within the Emerge\
\ system.\n</br></br>If our webhook message cannot be accepted by the webhook endpoint due to network failures, server\
\ errors, or request timeouts we will attempt delivering the message again. We will retry sending the message 6 times\
\ with varying gaps of time. \nSee table below:\n<table>\n<tr>\n<th>Retry Count</th>\n<th>Time</th>\n</tr>\n<tr>\n<td>1</td>\n\
<td>1 second from initial attempt</td>\n</tr>\n<tr>\n<td>2</td>\n<td>4 seconds from first attempt</td>\n</tr>\n<tr>\n\
<td>3</td>\n<td>9 seconds from second attempt</td>\n</tr>\n<tr>\n<td>4</td>\n<td>16 seconds from third attempt</td>\n\
</tr>\n<tr>\n<td>5</td>\n<td>25 seconds from fourth attempt</td>\n</tr>\n<tr>\n<td>6</td>\n<td>36 seconds from fifth attempt</td>\n\
</tr>\n</table>\t\t\n"
- name: Tracking Events
description: "The tracking events share a common object structure with the exception of ‘event_data’ object, which can change\
\ slightly depending on the updates.\n# Delivery Status Updated Event\n <h3>delivery_status_updated</h3>\n The delivery\
\ status is the on-time status of a shipment. In the event that this changes from one status to another the user can be\
\ notified (for example on-time to late, etc). This can be driven by the ETA being updated or the actual arrival/departure\
\ being updated. The old state will be an empty object if there was no previous data (on creation). \n<SchemaDefinition\
\ schemaRef=\"#/components/schemas/delivery_status_updated_Event\" />\n\n# Tracking Status Updated Event\n <h3>tracking_status_updated</h3>\n\
\ The shipment status is the primary status of the shipment. This determines the shipments progress from tender accepted\
\ > delivered. The old state will be an empty object if there was no previous data (on creation). \n<SchemaDefinition\
\ schemaRef=\"#/components/schemas/tracking_status_updated_Event\" />\n\n# Stop Actual Times Updated Event\n <h3>stop_actual_times_updated\
\ </h3>\n The user can be notified via this event when an actual arrival or departure information is received in the\
\ Emerge system. The old state will be an empty object if there was no previous data (on creation). \n<SchemaDefinition\
\ schemaRef=\"#/components/schemas/stop_actual_times_updated_Event\" />\n\n# Current Location Updated Job Event\n <h3>current_location_updated_job\
\ </h3>\n Emerge will send the most recent location of the truck every 30 minutes. The old state will be an empty object\
\ if there was no previous data (on creation). \n<SchemaDefinition schemaRef=\"#/components/schemas/current_location_updated_Event\"\
\ />\n"
- name: Opportunity Awarded Event
description: "<h3>opportunity_awarded</h3>\nThis object contains details of the Awarded option, so that the subscriber can\
\ do the subsequent actions, including tendering to it, in their own TMS.\n <SchemaDefinition schemaRef=\"#/components/schemas/Opportunity_Awarded_Event\"\
\ />\n"
- name: Options Changed Event
description: "<h3>options_changed</h3>\nThis object contains the list of all the options available for a particular opportunity.\
\ Showing all options or the lowest option can be controlled in the application setting. Whenever there is a change in\
\ the available option(s), this event will get triggered and notify the subscribers.\n <SchemaDefinition schemaRef=\"\
#/components/schemas/Options_Changed_Event\" />\n"
- name: Tender Status Updated Event
description: "<h3>tender_status_updated</h3>\nThis object contains the tender details. Whenever there is a change in the\
\ tender status, this event will get triggered and notify the subscribers.\n <SchemaDefinition schemaRef=\"#/components/schemas/Tender_Status_Updated_Event\"\
\ />\n"
- name: Network Partner Updated Event
description: "<h3>network_partner_updated </h3>\nThis object contains the partner details. Whenever the partner registers\
\ on Emerge platform following an invite by a shipper,or there is a change in the partner details, this event will get\
\ triggered and notify the subscribers\n <SchemaDefinition schemaRef=\"#/components/schemas/Network_Partner_Updated_Event\"\
\ />\n"
- name: Network Partner Deleted Event
description: "<h3>network_partner_deleted </h3>\nThis object contains the partner details. When the partner is deleted then\
\ this event will get triggered and notify the subscribers.\n <SchemaDefinition schemaRef=\"#/components/schemas/Network_Partner_Deleted_Event\"\
\ />\n"
- name: Current Marketplace Option Event
description: "<h3>current_marketplace_option </h3>\nThis object contains the Current Marketplace Option. Whenever there\
\ is a change in the Marketplace Option details this event will get triggered and notify the subscribers.\n <SchemaDefinition\
\ schemaRef=\"#/components/schemas/Current_Marketplace_Option_Event\" />\n"
- name: Opportunity Deleted Event
description: "<h3>opportunity_deleted </h3>\nThis object contains an opportunity identifier and references. When an opportunity\
\ is deleted then this event will get triggered and notify the subscribers.\n <SchemaDefinition schemaRef=\"#/components/schemas/Opportunity_Deleted_Event\"\
\ />\n"
- name: Opportunity Not Awarded Event
description: "<h3>opportunity_not_awarded </h3>\nThis object contains an opportunity identifier and references. When an\
\ opportunity is not awarded at the end of the bid duration then this event will get triggered and notify the subscribers.\n\
\ <SchemaDefinition schemaRef=\"#/components/schemas/Opportunity_NotAwarded_Event\" />\n"
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
paths:
/auth/login:
post:
tags:
- Authentication
summary: Gets access token for shipper user.
security: []
description: This method allows the shipper user to generate an access token from Emerge platform. This access token
is based upon a username/password combination that should be supplied in the request. Authentication has a rate limit
of up to 20 requests per second. This limit may be lower during times of high volumes.
requestBody:
description: Request body of an authentication attempt.
required: true
content:
application/json:
schema:
type: object
properties:
user_name:
description: The user name of the user authenticating against the API.
type: string
example: jsseh@emergemarket.com
password:
description: The password of the user authenticating against the API.
type: string
example: Secret123
required:
- user_name
- password
responses:
'200':
description: 200 | OK. A JSON object containing the access token and additional information.
content:
application/json:
schema:
$ref: '#/components/schemas/200_authentication_response'
'403':
$ref: '#/components/responses/403'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
/auth/refresh:
post:
tags:
- Authentication
summary: Gets a refreshed access token for shipper user.
security: []
description: This method allows users to refresh their access token based upon the original authentication event.
requestBody:
description: Request of the authentication renewal attempt.
required: true
content:
application/json:
schema:
type: object
properties:
refresh_token:
description: The refresh token from the original authentication request.
type: string
example: asdfklwj43asdfja432sjdafjadkkj2345efsdk4ts
required:
- refresh_token
responses:
'200':
description: 200 | OK. A new access token has been generated.
content:
application/json:
schema:
$ref: '#/components/schemas/200_authenticationrefresh_response'
'400':
description: 400 | Bad Request. A bad request was made. Please try again
content:
application/json:
schema:
$ref: '#/components/schemas/400_badrequest_refreshtoken_response'
'403':
$ref: '#/components/responses/403'
/network_partners:
description: This endpoint allows a shipper organization to interact with it's network partners (capacity providers) that
are defined in the Emerge Platform.
get:
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:
- Network Partners
summary: Gets all active network partners associated with the shipper organization.
security:
- BearerAuth: []
description: This method gives the ability to a shipper organization to view its active network partners in the Emerge
system.
responses:
'200':
description: 200 | OK. Returns the list of associated active network partners.
content:
application/json:
schema:
$ref: '#/components/schemas/200_getnetworkpartner_response'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
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:
- Network Partners
summary: Invites a network partner to Emerge platform.
security:
- BearerAuth: []
description: This method gives the ability to the shipper organization to invite it's network partner to the Emerge
platform.
requestBody:
description: Request model to invite a network partner.
required: true
content:
application/json:
schema:
type: object
properties:
contact:
type: object
required:
- first_name
- last_name
- email
- phone
properties:
first_name:
description: First name of the network partner contact.
type: string
example: mycarrier
last_name:
description: Last name of the network partner contact.
type: string
example: test
email:
description: Email id of the network partner contact.
type: string
format: email
example: mycarrier.test@abc.com
phone:
description: Phone number of the network partner contact.
$ref: '#/components/schemas/phone_request_object'
partner_code:
description: Network partner's partner code. Supports upto 10 characters with only uppercase and numeric
values allowed.
type: string
example: AS1234
responses:
'200':
description: 200 | Success. Network partner invited successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/200_invitenetworkpartner_response'
'400':
description: 400 | Bad Request. A bad request was made. Please try again
content:
application/json:
schema:
$ref: '#/components/schemas/400_badrequest_networkpartner_response'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/network_partners/{partner_id}:
delete:
tags:
- Network Partners
summary: Deletes a network partner from Emerge platform.
description: This method gives the ability to a shipper organization to delete it's network partner from the Emerge
platform.
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: partner_id
schema:
type: integer
minimum: 1
example: 1120
required: true
description: ID of the network partner.
responses:
'200':
description: 200 | OK. Network partner deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/errorcode_zero_without_message_object'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/opportunities:
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
post:
tags:
- Opportunities
summary: Creates an opportunity.
security:
- BearerAuth: []
description: Creates an opportunity, also called a quote, in the system. Emerge recommends that the call provides a
pickup date to ensure that this opportunity can be posted to the marketplace.
requestBody:
description: Structure of the call to create an opportunity
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_opportunity_request_object'
responses:
'200':
description: 200 | Success. A new opportunity has been created and an opportunity object is returned
content:
application/json:
schema:
$ref: '#/components/schemas/201_createopportunity_response'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
get:
tags:
- Opportunities
summary: Retrieves the details of opportunities by Reference Numbers
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: query
name: references.customer
schema:
type: string
example: CustRef123
description: 'Reference Number of the opportunity <br />
Keys: <span style="color:rgb(62 65 68); border-radius:4px; padding:1px 5px; border:1px solid rgb(228, 231, 235);
font-size:12px; font-family:''Source Code Pro'', monospace; line-height:1.2em; display:inline-flex; overflow-wrap:anywhere">
references.customer </span>
<span style="color:rgb(62 65 68); border-radius:4px; padding:1px 5px; border:1px solid rgb(228, 231, 235); font-size:12px;
font-family:''Source Code Pro'', monospace; line-height:1.2em; display:inline-flex; overflow-wrap:anywhere"> references.trailer
</span>
<span style="color:rgb(62 65 68); border-radius:4px; padding:1px 5px; border:1px solid rgb(228, 231, 235); font-size:12px;
font-family:''Source Code Pro'', monospace; line-height:1.2em; display:inline-flex; overflow-wrap:anywhere"> references.pro
</span>
<span style="color:rgb(62 65 68); border-radius:4px; padding:1px 5px; border:1px solid rgb(228, 231, 235); font-size:12px;
font-family:''Source Code Pro'', monospace; line-height:1.2em; display:inline-flex; overflow-wrap:anywhere"> references.pickupconfirmation
</span>
<span style="color:rgb(62 65 68); border-radius:4px; padding:1px 5px; border:1px solid rgb(228, 231, 235); font-size:12px;
font-family:''Source Code Pro'', monospace; line-height:1.2em; display:inline-flex; overflow-wrap:anywhere"> references.pickup
</span>
<span style="color:rgb(62 65 68); border-radius:4px; padding:1px 5px; border:1px solid rgb(228, 231, 235); font-size:12px;
font-family:''Source Code Pro'', monospace; line-height:1.2em; display:inline-flex; overflow-wrap:anywhere"> references.bol
</span>
<span style="color:rgb(62 65 68); border-radius:4px; padding:1px 5px; border:1px solid rgb(228, 231, 235); font-size:12px;
font-family:''Source Code Pro'', monospace; line-height:1.2em; display:inline-flex; overflow-wrap:anywhere"> references.appointment
</span>
<span style="color:rgb(62 65 68); border-radius:4px; padding:1px 5px; border:1px solid rgb(228, 231, 235); font-size:12px;
font-family:''Source Code Pro'', monospace; line-height:1.2em; display:inline-flex; overflow-wrap:anywhere"> references.delivery
</span>
<span style="color:rgb(62 65 68); border-radius:4px; padding:1px 5px; border:1px solid rgb(228, 231, 235); font-size:12px;
font-family:''Source Code Pro'', monospace; line-height:1.2em; display:inline-flex; overflow-wrap:anywhere"> references.other
</span>
<span style="color:rgb(62 65 68); border-radius:4px; padding:1px 5px; border:1px solid rgb(228, 231, 235); font-size:12px;
font-family:''Source Code Pro'', monospace; line-height:1.2em; display:inline-flex; overflow-wrap:anywhere"> references.po
</span>
'
responses:
'200':
description: 200 | OK. Returns the matching opportunities
content:
application/json:
schema:
$ref: '#/components/schemas/200_getopportunities_response'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/opportunities/{opportunity_id}:
get:
tags:
- Opportunities
summary: Retrieves the details of an opportunity by 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: opportunity_id
schema:
type: integer
minimum: 1
example: 112020
required: true
description: ID of the opportunity
responses:
'200':
description: 200 | OK. Returns the current opportunity
content:
application/json:
schema:
$ref: '#/components/schemas/200_getopportunity_response'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
delete:
tags:
- Opportunities
summary: Deletes an opportunity by opportunity ID.
description: Deletes an opportunity using the opportunity 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: opportunity_id
schema:
type: integer
minimum: 1
example: 112020
required: true
description: ID of the opportunity
responses:
'200':
description: 200 | OK. Opportunity deleted
content:
application/json:
schema:
$ref: '#/components/schemas/errorcode_zero_without_message_object'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
put:
tags:
- Opportunities
summary: Updates an opportunity by 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: opportunity_id
schema:
type: integer
minimum: 1
example: 112020
required: true
description: ID of the opportunity
requestBody:
description: Structure of the call to create an opportunity
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/update_opportunity_request_object'
responses:
'200':
description: 200 | OK. Returns the current opportunity
content:
application/json:
schema:
$ref: '#/components/schemas/200_updateopportunity_response'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
/opportunities/{opportunity_id}/post_to_marketplace:
post:
tags:
- Opportunities
summary: Posts an opportunity to the Emerge marketplace.
description: This method gives the ability to a shipper organization to post an opportunity to the Emerge marketplace.
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: opportunity_id
schema:
type: integer
minimum: 1
example: 112020
required: true
description: ID of the opportunity
responses:
'200':
description: 200 | OK. Successfully posted to the Emerge marketplace.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: integer
example: 0
'400':
description: 400 | Bad Request. A bad request was made. Please try again
content:
application/json:
schema:
$ref: '#/components/schemas/400_badrequest_opportunitypost_response'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/opportunities/{opportunity_id}/unpost_from_marketplace:
post:
tags:
- Opportunities
summary: Unposts an opportunity from the Emerge marketplace.
description: This method gives the ability to a shipper organization to unpost an opportunity from the Emerge marketplace.
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: opportunity_id
schema:
type: integer
minimum: 1
example: 112020
required: true
description: ID of the opportunity
responses:
'200':
description: 200 | OK. Successfully unposted from the Emerge marketplace
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: integer
example: 0
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
/opportunities/{opportunity_id}/options:
description: Retrieves all the network partner options and market place options.
get:
tags:
- Options
summary: Gets options for an opportunity.
security:
- BearerAuth: []
description: Gets all network partner options and market place options for a specific opportunity.
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 head
# --- truncated at 32 KB (310 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/emerge/refs/heads/main/openapi/emerge-public-api-openapi.yml