Emerge logo
API docs by Redocly

Emerge Carrier API V3 (3.0.0)

Download OpenAPI specification:Download

The Emerge carrier API provides integrated carrier (Provider) developers with access to the Emerge platform.

The current version of the API is v3.0.0 This API will evolve as the features in Emerge's product evolve.

Get Started

Welcome to Emerge's REST API Carrier Documentation. Our APIs allow Capacity and Integration Providers to easily interact with Shippers utilizing Emerge's Platform.

If you are interested in implementing a Carrier API integration please submit a request here

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 means that when a provider integrates with our REST API, the API will continue to work until the version is deprecated. If we have to make 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

Our Carrier APIs enable Capacity Providers with more flexibility when working with Shippers using Emerge's Platform. More workflows will become available in the future as we continue growing our Carrier API suite.

While integrating with Emerge, it is helpful to be aware of our nomenclature. Our Shippers create "Opportunities" defined as shipments they are accepting quotes for. When we request a rate, you respond with a "Quote" which is composed of the rate and duration details. Once a Quote is received from our Capacity Providers, it becomes an "Option" for our Shippers to review. You will see these terms throughout our documentation.

Rate Request to Quote Response

In this workflow, Emerge automatically sends Rate Requests to our Capacity Providers on behalf of our Shippers. This workflow makes it easy for Capacity Providers to rate Opportunities while maintaining existing processes. The steps of this workflow include:

  1. Receive a Rate Request Event via Webhook.
    • Rate Requests contain Shipper identifying information in the relationship_identifiers object. These values are provided by the Capacity Provider during Capacity Link onboarding to enable matching in the Provider's application.
  2. Review Opportunity details and determine whether to provide a quote.
  3. Send the Rate or provide the Error Reason for declining to rate via the Quote Response Endpoint.
    • A Quote Response must provide the event_id sourced from the Rate Request Event.
    • Providers can respond with either a Rate or an Error to let the shipper know why they are not providing a rate.
    • Providers responding with a rate can include their Quote ID in the provider_reference field.
  4. The Rate will be available for Review by the Shipper.

Authentication

Gets access token for Integration Provider.

This method allows an Integration Provider to generate an access token from Emerge platform. A client credential pair, composed of a client id and a client secret, must be supplied in the request. The procured access token should be sent by the Integration Provider while calling other Carrier API endpoints.

Request Body schema: application/json
required

Request body of an authentication attempt.

client_id
required
string

The identifier provided during onboarding and used for authentication.

client_secret
required
string

The secret provided during onboarding and used for authentication.

Responses

Request samples

Content type
application/json
{
  • "client_id": "eMF2mQNXue5BXjmUNX1pQ45grwrquuiQ",
  • "client_secret": "1gTmAOzPLqoE5HKxjWgFt8WnAEPu3MQjlNBrR94c1q4o7UTtGgRd1QGwCFzVPsWb"
}

Response samples

Content type
application/json
{
  • "response": {
    },
  • "error": {
    }
}

Options

Respond to Quote

This method is used to respond to a rate request. If a quote is supplied, an option is created inside the Emerge Platform. If an error is sent, the reason the provider did not quote is given to the shipper.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Request model to submit the rates.

rate_request_id
required
string

The identifier for the rate request. This is provided by Emerge in the Rate Request Event.

response_type
string
Enum: "BID" "BOOK_IT_NOW" "NOT_INTERESTED"

The type of response to the rate request.

object

This object identifies all relevant quote details. This object is optional if the "error_messages" object is in use.

error_messages
Array of strings

Identifies reasons for not providing a quote. This field is optional if the "quote_details" object is in use.

Responses

Request samples

Content type
application/json
{
  • "rate_request_id": "31e34816-f50d-4158-88b8-768715f628b2",
  • "response_type": "BID",
  • "quote_details": {
    },
  • "error_messages": [
    ]
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Delete an option

This method is used to delete the specified option.

Authorizations:
BearerAuth
path Parameters
rate_request_id
string
Example: 070C895C-AE61-4629-A603-829FC54CD816

The identifier for the rate request. This is provided by Emerge in the Rate Request Event.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Tender

Respond to Tender

This method is used to receive response for a Tender.

Authorizations:
BearerAuth
path Parameters
shipment_id
string
Example: S123455

The identifier for the shipment. This is provided by Emerge in the Tender Request Event.

Request Body schema: application/json
required

Request model to submit the response.

event_id
required
string

The identifier for the tender request. This is provided by Emerge in the Tender Request Event.

status
required
string
Enum: "ACCEPT" "REJECT"

Defines tender status.

rejection_reason
string
Enum: "NO_CAPACITY" "SHORT_LEAD_TIME" "PICKUP_APPOINTMENT_NOT_FEASIBLE" "DELIVERY_APPOINTMENT_NOT_FEASIBLE" "TRANSIT_TIME_NOT_FEASIBLE" "VOLUME_COMMITMENT_MET"

Identifies reasons for rejecting a tender.

carrier_shipment_id
string

Defines the carrier shipment id.

Responses

Request samples

Content type
application/json
{
  • "event_id": "40dbcdb1-272b-4ee3-8621-208b88fe0beb",
  • "status": "ACCEPT",
  • "rejection_reason": "NO_CAPACITY",
  • "carrier_shipment_id": "S111171611"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Tracking

Update tracking statuses

This method is used to update tracking statuses of a shipment.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Request model to update tracking status.

shipment_id
required
string

The shipment reference identifier.

event_type
required
string
Enum: "LOCATION_UPDATE" "ACTUAL_ARRIVAL" "ACTUAL_DEPARTURE" "ETA"

The type of tracking event.

trailer_number
string

The trailer number.

required
object

This object identifies the data for the tracking event.

Responses

Request samples

Content type
application/json
{
  • "shipment_id": "S111338230",
  • "event_type": "LOCATION_UPDATE",
  • "trailer_number": "12345",
  • "event_data": {
    }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Rate Request Event

rate_request

This object contains Opportunity details used to create a rate by a Capacity Provider. Once a Capacity Provider has received the rate request event, they can respond with a quote using the Quote Response endpoint. If there is no response to the rate request within the time specified by the Integration Provider configuration, a manual rate request will be made available in the Emerge Platform and an email requesting a rate is sent to the Capacity Provider.
event_id
string

The unique identifier for the event.

timestamp
string

The date/time when the event was created in the Emerge application. This is a date/time offset.

event_type
string

The event type name.

object

This object contains all details associated with the event.

message_type
string
Enum: "CREATE" "UPDATE" "AWARDED" "CLOSED"

This indicates the type of message or event.

{
  • "event_id": "31e34816-f50d-4158-88b8-768715f628b2",
  • "timestamp": "2021-09-15T12:46:17.381291+00:00",
  • "event_type": "rate_request",
  • "event_data": {
    },
  • "message_type": "CREATE"
}

Tender Request Event

tender_request

The object contains tender details used to respond by a Capacity Provider.
event_id
string

The unique identifier for the event.

timestamp
string

The date/time when the event was created in the Emerge application. This is a date/time offset.

event_type
string

The event type name.

object

This object contains all details associated with the event.

{
  • "event_id": "31e34816-f50d-4158-88b8-768715f628b2",
  • "timestamp": "2023-04-11T12:46:17.381291+00:00",
  • "event_type": "tender_request",
  • "event_data": {
    }
}