Emerge Opportunities API

openapi: 3.2.0
info:
  version: 1.2.1
  title: Emerge Public Opportunities 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: Opportunities
paths:
  /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}/post_to_network_partners:
    description: This method gives the ability to a shipper organization to post an opportunity to its network partners (capacity providers).
    post:
      tags:
      - Opportunities
      summary: Posts an opportunity to shipper's network partners.
      security:
      - BearerAuth: []
      description: This method gives the ability to a shipper organization to post an opportunity to its network partners (capacity providers).
      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: Request model to post an opportunity to selected network partners.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                post_to_all:
                  type: boolean
                  description: Use this flag to control to whom the request needs to be posted. If set as true, system will post request to all the network partners ignoring the other two fields. If set as false, it becomes mandatory to input values in either partner_ids or partner_codes field. If the request payload is sent with input in both partner_ids or partner_codes field, the system will merge both and post request to all the valid partners_ids and partner_codes.
                partner_codes:
                  description: The list of codes of the selected network partners to whom the opportunity should be posted.
                  type: array
                  items:
                    description: The network partner code.
                    type: string
                  example:
                  - AS1234,X9898
                partner_ids:
                  description: The list of IDs of the selected network partners to whom the opportunity should be posted.
                  type: array
                  items:
                    description: The network partner ID.
                    type: string
                  example:
                  - 1111
                  - 9088
                  - 3456
      responses:
        '200':
          description: 200 | OK. Details of the network partners to whom the request could not be sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    $ref: '#/components/schemas/200_sendrequest_partners_response'
                  error:
                    type: object
                    properties:
                      code:
                        description: HTTP 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_opportunity_notification_response'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
  /opportunities/by_customer_reference/{customer_reference_number}:
    delete:
      tags:
      - Opportunities
      summary: Deletes an opportunity by customer reference number.
      description: Delete an opportunity using the Customer Reference Number. If there are multiple matches for the Customer Reference number, all open opportunities with that Customer Reference number will be deleted.
      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: customer_reference_number
        schema:
          type: string
        required: true
        description: Customer reference number.
      responses:
        '200':
          description: 200 | OK. Opportunities deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorcode_zero_without_message_object'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
components:
  schemas:
    opportunity_request_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
        - standardized_appointment_type_id
        - standardized_loading_type_id
        properties:
          type_id:
            description: The type of the stop.
            type: string
            enum:
            - Origin
            - Middle
            - Destination
            example: Origin
          appointment_type_id:
            description: The appointment type.
            type: string
            deprecated: true
            enum:
            - FCFS
            - Appointment
            example: Appointment
          standardized_appointment_type_id:
            description: The appointment type of the stop.
            type: string
            enum:
            - FCFS
            - AppointmentScheduled
            - AppointmentRequired
            example: FCFS
          standardized_loading_type_id:
            description: The loading or unloading type of the stop.
            type: string
            enum:
            - Live
            - DropTrailer
            example: Live
          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
            - Drop
            example: Pick
          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
    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_book_it_now_object:
      description: Book it now related data.
      type: object
      properties:
        enabled:
          description: Defines if Book it Now will populate n a quote upon creation. This overrides the “Set Dynamic BIN using the default starting and ceiling rates for API and Bulk Upload quotes” organization setting.
          type: boolean
          default: false
          example: false
        start:
          description: Starting price for dynamic book it now. When not provided, the starting rate will calculate based on the rate pulse or ceiling rate.
          type: integer
        ceiling:
          description: Ceiling price for the dynamic book it now.
          type: integer
    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
                - MiscellaneousDangerousGoo

# --- truncated at 32 KB (92 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/emerge/refs/heads/main/openapi/emerge-opportunities-api-openapi.yml