openapi: 3.2.0
info:
  title: Emerge Options API
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Options across 2 of this provider''s published API definitions: emerge-carrier-api-openapi.yml, emerge-public-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emergemarket.io/v2
  description: Primary production endpoint
- url: https://demo-api.emergemarket.dev/v2
  description: Testing sandbox endpoint
- url: https://api.emergemarket.io/v1
  description: Primary production endpoint
- url: https://demo-api.emergemarket.dev/v1
  description: Testing sandbox endpoint
tags:
- name: Options
paths:
  /options:
    post:
      tags:
      - Options
      summary: Respond to Quote
      security:
      - BearerAuth: []
      description: This method is used to respond a Rate Request. If a Quote is supplied, an Option is created inside of the Emerge Platform. If an error is sent, the reason the Provider did not quote is given to the Shipper.
      requestBody:
        description: Request model to submit the rates.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rate_request_id:
                  description: The identifier for the rate request. This is provided by Emerge in the Rate Request Event.
                  type: string
                  example: 31e34816-f50d-4158-88b8-768715f628b2
                quote_details:
                  description: This object identifies all relevant quote details. This object is optional if the "error_messages" object is in use.
                  type: object
                  properties:
                    provider_reference:
                      description: The rate identifier number for the Capacity Provider. Providers may expect this value to be returned when the shipment is tendered.
                      type: string
                      example: a55097d0-76e3-427c-bc67-613dd0a2ded2
                    rate:
                      description: Identifies rate value details.
                      type: object
                      properties:
                        amount:
                          description: The rate amount.
                          type: integer
                          example: 100
                        currency:
                          description: Defines the currency of amount. Must be "USD".
                          type: string
                          example: USD
                        type:
                          description: Defines rate type. This value must match the requested rate type in the Rate Request Event.
                          type: string
                          enum:
                          - LH_ONLY
                          - ALL_IN
                          example: LH_ONLY
                    expiration_date:
                      description: Defines when the quote expires. This is a date/time offset.
                      type: string
                      example: '2021-09-22T12:01:56.9726183+00:00'
                error_messages:
                  description: Identifies reasons for not providing a quote. This field is optional if the "quote_details" object is in use.
                  type: array
                  items:
                    type: string
                    example: Unable to Quote due to ...
              required:
              - rate_request_id
      responses:
        '202':
          description: 202 | Accepted. Rates submitted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/200_postoptions_response'
        '400':
          description: 400 | Bad Request. A bad request was made. Please try again
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_badrequest_postoptions_response'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
    servers:
    - url: https://api.emergemarket.io/v2
      description: Primary production endpoint
    - url: https://demo-api.emergemarket.dev/v2
      description: Testing sandbox endpoint
  /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 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: 23892343
        required: true
        description: Id of the opportunity
      responses:
        '200':
          description: 200 | OK. Returns the all network partners and marketplace options for a corresponding opportunity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/200_Alloptions_response'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
    servers:
    - url: https://api.emergemarket.io/v1
      description: Primary production endpoint
    - url: https://demo-api.emergemarket.dev/v1
      description: Testing sandbox endpoint
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)
    errorcode_zero:
      type: object
      properties:
        code:
          description: HTTP code
          type: integer
          example: 0
    400_badrequest_postoptions_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: integer
                    example: amount
                  value:
                    type: string
                    example: Must have at least one reason in case unable to provide rate..
            messages:
              type: array
              items:
                type: string
                example: Validation failed.
    200_postoptions_response:
      description: 202 | Accepted.
      type: object
      properties:
        error:
          $ref: '#/components/schemas/errorcode_zero'
    200_Alloptions_response:
      type: object
      properties:
        response:
          type: array
          items:
            type: object
            properties:
              opportunity_id:
                description: The id of the opportunity.
                type: integer
                example: 238842
              option_id:
                description: The id of the option.
                type: integer
                example: 123
              partner_quote_reference:
                description: The quote reference number of the option.
                type: string
                example: T12334
              expiration_date:
                description: The expiration date of the option.
                type: string
                example: '2021-10-28T07:53:59.402Z'
              availability_date:
                description: The availability date of the option.
                type: string
                example: '2021-10-28T07:53:59.402'
              rate:
                description: Rate of the option.
                type: number
                example: 300
              is_total_rate:
                description: true if linehaul and fuel rate included as part of total rate else false.
                type: boolean
                example: true
              modified_date:
                description: Modified date of the option.
                type: string
                example: '2020-10-28T07:53:59.402Z'
              created_date:
                description: Created date of the option.
                type: string
                example: '2020-10-28T07:53:59.402Z'
              partner:
                $ref: '#/components/schemas/200_getoption_partner_response'
              notes:
                description: option notes.
                type: string
                example: Test notes
              references:
                $ref: '#/components/schemas/references_object'
        error:
          type: object
          properties:
            code:
              description: HTTP code
              type: integer
              example: 0
    200_getoption_partner_response:
      type: object
      description: Details of the partner associated with the option
      properties:
        partner_code:
          description: Partner code of partner.
          type: string
          example: P2314534
        transportation_entity:
          description: Details of the transportation entity associated with the partner.
          type: object
          properties:
            legal_name:
              description: Transportation entity legal name.
              type: integer
              example: Hansal Transport
            dba_name:
              description: Transportation entity dba name.
              type: string
              example: HansalTransport
            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'
    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'
    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-refined-from:
- emerge-carrier-api-openapi.yml
- emerge-public-api-openapi.yml
x-tagGroups:
- name: Provider API
  tags:
  - Authentication
  - Options
  - Tender
- name: Webhook Events
  tags:
  - Rate Request Event
  - Tender Request Event