Emerge Awards API

openapi: 3.2.0
info:
  version: 1.2.1
  title: Emerge Public Awards 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: Awards
paths:
  /awards:
    description: The award endpoints allow a shipper to award a carrier in the Emerge system a load. Note that awards are not replacements for tenders. The awards endpoints are typically used when the Emerge system is used to source capacity, while the shipper's TMS is used to tender to the carrier.
    summary: Returns an array of awards.
    get:
      tags:
      - Awards
      summary: Returns an array of awards.
      security:
      - BearerAuth: []
      description: Returns a list of awards for a particular account. An opportunity can have either an award or a shipment.
      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: opportunity_id
        schema:
          type: integer
        description: Emerge system identifier for the awarded opportunity.
        example: 344392
      - in: query
        name: option_id
        schema:
          type: integer
        description: Emerge system identifier for the option associated with the awarded opportunity.
        example: 12545
      - in: query
        name: customer_reference_number
        schema:
          type: string
        description: Customer's identifier to match the awarded opportunity on.
        example: 1212934
      - in: query
        name: start_date
        schema:
          type: string
        description: Start of the date range within which the Awards should be searched. Supports yyyy-mm-dd format.
        example: '2021-10-28'
      - in: query
        name: end_date
        schema:
          type: string
        description: End of the date range within which the Awards should be searched. Supports yyyy-mm-dd format.
        example: '2021-10-30'
      responses:
        '200':
          description: 200 | OK. A JSON array of awards
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: array
                    items:
                      type: object
                      properties:
                        award_id:
                          description: The id of the award.
                          type: integer
                          example: 238842
                        opportunity_id:
                          description: The id of the awarded opportunity.
                          type: integer
                          example: 238842
                        partner_quote_reference:
                          description: The quote reference number of the winning partner.
                          type: string
                          example: T12334
                        expiration_date:
                          description: The expiration date of the winning option.
                          type: string
                          example: '2021-10-28T07:53:59.402'
                        availability_date:
                          description: The availability date of the winning option.
                          type: string
                          example: '2021-10-28T07:53:59.402'
                        option_id:
                          description: The id of the winning option.
                          type: integer
                          example: 123
                        rate:
                          description: Rate of the winning option.
                          type: number
                          example: 300
                        is_total_rate:
                          description: Indicates whether the rate contains fuel surcharge or not.
                          type: boolean
                        modified_date:
                          description: Modified date of the winning option.
                          type: string
                          example: '2021-10-28T07:53:59.402'
                        created_date:
                          description: Created date of the winning option.
                          type: string
                          example: '2021-10-28T07:53:59.402'
                        partner:
                          $ref: '#/components/schemas/200_getawards_partner_response'
                        notes:
                          description: Notes on the award.
                          type: string
                          example: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
                        emerge_opportunity_reference:
                          description: Emerge reference for the awarded opportunity.
                          type: string
                          example: Q11238842
                        references:
                          $ref: '#/components/schemas/references_object'
                        award_method:
                          description: Award method for the awarded opportunity.
                          type: string
                          enum:
                          - Manual
                          - AutoAward
                          - BookItNow
                          example: Manual
                  error:
                    type: object
                    properties:
                      code:
                        description: HTTP code
                        type: integer
                        example: 0
        '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:
      - Awards
      summary: Creates an award.
      security:
      - BearerAuth: []
      description: Creates an award. Awarding is the process of informing the carrier that they have won the shipment without tendering to them.
      requestBody:
        description: Request body of award
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                option_id:
                  description: The winning option id.
                  type: integer
                  example: 3233
                not_awarding_to_lowest_option_reason_code:
                  description: Reason code for not awarding to the lowest option, if applicable.
                  type: string
                  enum:
                  - ContractedLane
                  - ServiceLevel
                  - Accountability
                  - NoLongerAvailable
                  - Other
                  - NotProvided
                  example: ContractedLane
                not_awarding_to_lowest_option_reason:
                  description: Custom reason text for not awarding to the lowest option, when selected Reason Code is "Other".
                  type: string
                  example: The lowest option carrier is black listed in my organization.
              required:
              - option_id
      responses:
        '200':
          description: 200 | OK. A JSON award
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      award_id:
                        description: The id of the award.
                        type: integer
                        example: 238842
                      opportunity_id:
                        description: The id of the awarded opportunity.
                        type: integer
                        example: 238842
                      partner_quote_reference:
                        description: The quote reference number of the winning partner.
                        type: string
                        example: test123
                      expiration_date:
                        description: The expiration date of the winning option.
                        type: string
                        example: '2020-10-28T07:53:59.402Z'
                      availability_date:
                        description: The availability date of the winning option.
                        type: string
                        example: '2020-10-28T07:53:59.402'
                      option_id:
                        description: The id of the winning option.
                        type: integer
                        example: 123
                      rate:
                        description: Rate of the winning option.
                        type: number
                        example: 300
                      is_total_rate:
                        description: Indicates whether the rate contains fuel surcharge or not.
                        type: boolean
                      modified_date:
                        description: Modified date of the winning option.
                        type: string
                        example: '2020-10-28T07:53:59.402Z'
                      created_date:
                        description: Created date of the winning option.
                        type: string
                        example: '2020-10-28T07:53:59.402Z'
                      partner:
                        $ref: '#/components/schemas/200_getawards_partner_response'
                      notes:
                        description: Notes on the award.
                        type: string
                        example: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
                      emerge_opportunity_reference:
                        description: Emerge reference for the awarded opportunity.
                        type: string
                        example: Q11238842
                      references:
                        $ref: '#/components/schemas/references_object'
                      award_method:
                        description: Award method for the awarded opportunity.
                        type: string
                        enum:
                        - Manual
                        - AutoAward
                        - BookItNow
                        example: Manual
                  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_createaward_response'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
  /awards/{id}:
    description: The award endpoints allow a shipper to award a carrier in the Emerge system a load. Note that awards are not replacements for tenders. The awards endpoints are typically used when the Emerge system is used to source capacity, while the shipper's TMS is used to tender to the carrier.
    summary: Returns an award for award identifier.
    get:
      tags:
      - Awards
      summary: Retrieves the details of an award.
      security:
      - BearerAuth: []
      description: Returns an award. An opportunity can have either an award or a shipment.
      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: id
        schema:
          type: integer
          minimum: 1
          example: 112020
        required: true
        description: Id of the award
      responses:
        '200':
          description: 200 | OK. A JSON award
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      award_id:
                        description: The id of the award.
                        type: integer
                        example: 238842
                      opportunity_id:
                        description: The id of the awarded opportunity.
                        type: integer
                        example: 238842
                      partner_quote_reference:
                        description: The quote reference number of the winning partner.
                        type: string
                        example: T12334
                      expiration_date:
                        description: The expiration date of the winning option.
                        type: string
                        example: '2021-10-28T07:53:59.402Z'
                      availability_date:
                        description: The availability date of the winning option.
                        type: string
                        example: '2021-10-28T07:53:59.402'
                      option_id:
                        description: The id of the winning option.
                        type: integer
                        example: 123
                      rate:
                        description: Rate of the winning option.
                        type: number
                        example: 300
                      is_total_rate:
                        description: Indicates whether the rate contains fuel surcharge or not.
                        type: boolean
                      modified_date:
                        description: Modified date of the winning option.
                        type: string
                        example: '2021-10-28T07:53:59.402Z'
                      created_date:
                        description: Created date of the winning option.
                        type: string
                        example: '2021-10-28T07:53:59.402Z'
                      partner:
                        $ref: '#/components/schemas/200_getawards_partner_response'
                      notes:
                        description: Notes on the award.
                        type: string
                        example: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
                      emerge_opportunity_reference:
                        description: Emerge reference for the awarded opportunity.
                        type: string
                        example: Q11238842
                      references:
                        $ref: '#/components/schemas/references_object'
                      award_method:
                        description: Award method for the awarded opportunity.
                        type: string
                        enum:
                        - Manual
                        - AutoAward
                        - BookItNow
                        example: Manual
                  error:
                    type: object
                    properties:
                      code:
                        description: HTTP code
                        type: integer
                        example: 0
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
components:
  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
  schemas:
    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)
    400_badrequest_createaward_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: option_id
                  value:
                    type: string
                    example: option_id must not be empty.
            messages:
              type: array
              items:
                type: string
                example: Validation failed.
    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'
    200_getawards_partner_response:
      type: object
      description: 200 | OK. Details of the partner winning the award
      properties:
        partner_code:
          description: Partner code of the winning partner as assigned by shipment provider.
          type: string
          example: P2314534
        transportation_entity:
          description: Details of the transportation entity associated with the winning partner .
          type: object
          properties:
            legal_name:
              description: Transportation entity legal name.
              type: integer
              example: name
            dba_name:
              description: Transportation entity dba name.
              type: string
              example: testName
            dot_number:
              description: Transportation entity DOT number.
              type: integer
              example: 2894801
            docket_number:
              description: Transportation entity Docket number.
              type: string
              example: MC143583
            type:
              description: Transportation entity type.
              type: string
              example: testType
        contact:
          description: Contact information of the winning partner.
          type: object
          properties:
            first_name:
              description: First name of the contact.
              type: string
              example: FirstName
            last_name:
              description: Last name of the contact.
              type: string
              example: LastName
            email:
              description: Email of the contact.
              type: string
              format: email
              example: example@emergetms.com
            phone:
              description: Phone details of the contact.
              $ref: '#/components/schemas/phone_response_object'
    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
  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