OneRail Delivery API

openapi: 3.0.1
info:
  version: 0.0.3
  title: OneRail Delivery Cloud - Delivery API
  description: Allows authorized 3rd parties to request new deliveries through the OneRail network
  license:
    name: UNLICENSED
security:
- ApiKey: []
  AppId: []
paths:
  /:
    x-exegesis-controller: Home
    get:
      summary: Root path showing app name and version number
      operationId: index
      security: []
      tags:
      - Home
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                properties:
                  info_payload:
                    description: Basic app info
                    type: object
        '400':
          description: Bad request
    head:
      operationId: healthCheck
      responses:
        '400':
          description: Bad request
        default:
          description: Health check passed.
      security: []
      summary: Health check
      tags:
      - HealthCheck
  /user/authenticate:
    x-exegesis-controller: User
    post:
      summary: Creates and returns an authentication token
      operationId: authenticate
      security: []
      requestBody:
        description: User credetials
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCredentials'
      responses:
        '200':
          description: User token created
          content:
            application/json:
              schema:
                type: object
                required:
                - token
                properties:
                  token:
                    type: string
        '401':
          description: Unauthorized - invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /delivery/create:
    x-exegesis-controller: Delivery
    post:
      summary: Creates a new delivery
      operationId: createDelivery
      security:
      - ApiKeyAndAppId: []
      - ApiKey: []
      - OAuth: []
      - AppId: []
      requestBody:
        description: The delivery to be created with all required components
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Delivery'
      responses:
        '200':
          description: Success. The delivery has been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryCreated'
        '422':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /delivery/get-rates:
    x-exegesis-controller: Delivery
    post:
      summary: Fetches rates of delivery through OneRail network. If saveDraftDelivery is set to true then a delivery will
        be created. If set to false rates will be fetched without creating a delivery.
      operationId: getDeliveryRates
      security:
      - ApiKeyAndAppId: []
      - ApiKey: []
      - OAuth: []
      - AppId: []
      requestBody:
        description: The delivery to be created with all required components
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Delivery'
              - type: object
                properties:
                  saveDraftDelivery:
                    type: boolean
                    nullable: true
                    default: false
      responses:
        '200':
          description: Rates OneRail offers this moment in time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatesResponse'
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /delivery/check-availability:
    x-exegesis-controller: Delivery
    post:
      summary: 'Check delivery availability using progressive input. Minimal requests can return top-level availability only;
        richer requests can include service-level details.

        '
      operationId: checkDeliveryAvailability
      security:
      - ApiKeyAndAppId: []
      - ApiKey: []
      - OAuth: []
      - AppId: []
      requestBody:
        description: 'Delivery data for availability check. Only pickUpData and dropOffData are required, and each may contain
          partial location data.

          '
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeliveryAvailabilityRequest'
      responses:
        '200':
          description: Availability result for the supplied delivery data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryAvailabilityResponse'
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /delivery/{id}/details:
    x-exegesis-controller: Delivery
    get:
      summary: Returns delivery details
      operationId: getDetails
      security:
      - ApiKeyAndAppId: []
      - ApiKey: []
      - OAuth: []
      - AppId: []
      parameters:
      - name: id
        in: path
        description: delivery id
        required: true
        schema:
          type: string
      - name: numericSystem
        in: query
        schema:
          type: string
          default: IMPERIAL
          enum:
          - IMPERIAL
          - METRIC
      responses:
        '200':
          description: Returns delivery details
          content:
            application/json:
              schema:
                type: object
                description: Delivery
                properties:
                  id:
                    type: string
                    format: uuid
                  deliveryType:
                    type: string
                    enum:
                    - BUSINESS
                    - RESIDENTIAL
                  notes:
                    type: string
                  triggeredBy:
                    type: string
                  state:
                    type: string
                    enum:
                    - DRAFT
                    - READY TO DISPATCH
                  isReturn:
                    type: boolean
                  dispatchAt:
                    type: string
                    format: date-time
                  deliverySpeedMin:
                    type: integer
                  createdAt:
                    type: string
                    format: date-time
                  updatedAt:
                    type: string
                    format: date-time
                  shipperExtraData:
                    type: object
                    description: JSON blob that the customer can use to store additional info they may need.
                    nullable: true
                  contractedShipperCostCent:
                    type: integer
                    nullable: true
                  actualShipperCostCent:
                    type: integer
                    nullable: true
                  fromId:
                    type: string
                    format: uuid
                  slaPickupBufferMinute:
                    type: number
                  slaDropoffBufferMinute:
                    type: number
                  computedDistanceMile:
                    type: number
                  computedDistanceKm:
                    type: number
                  deliveryAttemptId:
                    type: string
                    format: uuid
                    nullable: true
                  creationReason:
                    type: string
                  shipmentId:
                    type: string
                  deliveryDeadline:
                    type: string
                    format: date-time
                  shipperContractSla:
                    type: object
                    description: Shipper Contract SLA
                    properties:
                      id:
                        type: string
                        format: uuid
                      pickUpSla:
                        description: Reference to Pick up speed (Acceptable time)
                        type: object
                        properties:
                          id:
                            type: string
                            format: uuid
                          name:
                            type: string
                          value:
                            type: integer
                      dropOffSla:
                        description: Reference to Drop off speed (Acceptable time)
                        type: object
                        properties:
                          id:
                            type: string
                            format: uuid
                          name:
                            type: string
                          value:
                            type: integer
                      latePickupPenaltyPercent:
                        type: number
                        format: float
                        description: Late pick up penalty percentage
                      lateDeliveryPenaltyPercent:
                        type: number
                        format: float
                        description: Late delivery penalty percentage
                      pickUpDesc:
                        type: string
                        description: Pick up description
                      dropOffDesc:
                        type: string
                        description: Drop off description
                      mileageAvg:
                        type: integer
                        description: Mileage average rate
                      mileageMax:
                        type: integer
                        description: Mileage max rate
                      endOfDayTime:
                        type: integer
                      shippingMode:
                        description: Reference to a Shipping Mode
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                      shipperSignature:
                        type: object
                        description: Contract Signature
                        properties:
                          id:
                            type: string
                            format: uuid
                          typedName:
                            type: string
                          ipAddress:
                            type: string
                            oneOf:
                            - format: ipv4
                            - format: ipv6
                          signedOn:
                            type: string
                            format: date-time
                          signedBy:
                            type: object
                            properties:
                              id:
                                type: string
                                format: uuid
                              firstName:
                                type: string
                              lastName:
                                type: string
                      oneRailSignature:
                        $ref: '#/paths/~1delivery~1%7Bid%7D~1details/get/responses/200/content/application~1json/schema/properties/shipperContractSla/properties/shipperSignature'
                      approvedBy:
                        type: object
                        properties:
                          id:
                            type: string
                            format: uuid
                          firstName:
                            type: string
                          lastName:
                            type: string
                        description: Reference to a OneRail User
                      approvedOn:
                        type: string
                        format: date-time
                      shipperContract:
                        type: object
                        description: Reference to Shipper Contract
                        properties:
                          id:
                            type: string
                            format: uuid
                          name:
                            type: string
                          organization:
                            type: object
                            properties:
                              id:
                                type: string
                                format: uuid
                              name:
                                type: string
                  from:
                    description: Pickup location
                    $ref: '#/paths/~1delivery~1%7Bid%7D~1details/get/responses/200/content/application~1json/schema/properties/to'
                  to:
                    description: Drop off location
                    type: object
                    properties:
                      location:
                        $ref: '#/paths/~1delivery~1pre-validation/post/requestBody/content/application~1json/schema/properties/to/properties/location'
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                      address:
                        type: object
                        properties:
                          city:
                            type: string
                          label:
                            type: string
                          state:
                            type: string
                          county:
                            type: string
                          street:
                            type: string
                          street2:
                            type: string
                          stateCode:
                            type: string
                          postalCode:
                            type: string
                          countryCode:
                            type: string
                          countryName:
                            type: string
                          houseNumber:
                            type: string
                      accessCode:
                        type: string
                        nullable: true
                      shippingInstructions:
                        type: string
                        nullable: true
                      receivingInstructions:
                        type: string
                        nullable: true
                      contactName:
                        type: string
                      phoneNumber:
                        type: string
                        nullable: true
                      contactEmailAddress:
                        type: string
                      storeNumber:
                        type: string
                        nullable: true
                      timezone:
                        type: string
                      timezoneOffset:
                        type: number
                      timezoneAbbreviataion:
                        type: string
                      msa:
                        type: string
                        nullable: true
                      cutoffTimeMins:
                        type: number
                        nullable: true
                      organizationId:
                        type: string
                      canDispatchDeliveries:
                        type: boolean
                  deliveryOptions:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        name:
                          type: string
                  deliveryAttempts:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        state:
                          type: string
                        failureReason:
                          type: string
                        durationMin:
                          type: integer
                        createdAt:
                          type: string
                          format: date-time
                        updatedAt:
                          type: string
                          format: date-time
                        deliveryStatus:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                            location:
                              $ref: '#/paths/~1delivery~1pre-validation/post/requestBody/content/application~1json/schema/properties/to/properties/location'
                            driverName:
                              type: string
                            driverPhone:
                              type: string
                            eta:
                              type: string
                              format: date-time
                            driverNotes:
                              type: string
                            tmsLinkURL:
                              type: string
                            lpDeliveryId:
                              type: string
                            lpDeliveryData:
                              type: object
                        deliveryStateChanges:
                          type: array
                          items:
                            type: object
                            properties:
                              state:
                                type: string
                                enum:
                                - ACCEPTED_BY_LP
                                - CANCELED_BY_LP
                                - REVOKED_BY_ONERAIL
                                - DRIVER_ASSIGNED
                                - EN_ROUTE_TO_PICKUP
                                - ARRIVED_FOR_PICKUP
                                - PICKED_UP
                                - EN_ROUTE_TO_DELIVERY
                                - ARRIVED_FOR_DELIVERY
                                - DELIVERED
                                - FAILED
                                - PERMANENTLY_FAILED
                              location:
                                $ref: '#/paths/~1delivery~1pre-validation/post/requestBody/content/application~1json/schema/properties/to/properties/location'
                              happenedOn:
                                type: string
                                format: date-time
                  capabilityTags:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        name:
                          type: string
                  deliveryExceptions:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeliveryList/allOf/1/properties/data/items/properties/deliveryExceptions/items'
                  deliveryRating:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      rating:
                        type: integer
                      feedback:
                        type: string
                  deliveryFiles:
                    $ref: '#/components/schemas/DeliveryCreated/properties/deliveryFiles'
                  order:
                    type: object
                    description: Order details
                    properties:
                      id:
                        type: string
                        format: uuid
                      orderId:
                        type: string
                        description: External order ID
                      netAmountCent:
                        type: number
                        description: Net Amount, in cents
                      barCode:
                        type: string
                      orderItems:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                            description:
                              type: string
                            identifier:
                              type: string
                            priceCent:
                              type: number
                            lengthIn:
                              type: number
                            lengthCm:
                              type: number
                            widthIn:
                              type: number
                            widthCm:
                              type: number
                            heightIn:
                              type: number
                            heightCm:
                              type: number
                            weightLbs:
                              type: number
                            weightKg:
                              type: number
                            quantity:
                              type: integer
                      status:
                        type: string
                      organization:
                        type: object
                        description: Organization the order belongs to
                        properties:
                          id:
                            type: string
                            format: uuid
                          name:
                            type: string
                          organizationTypes:
                            description: The organization's type(s)
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                name:
                                  type: string
                  suggestedFleetVehicle:
                    nullable: true
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                      vehicleType:
                        type: string
                  contactPreference:
                    type: string
                    enum:
                    - EMAIL
                    - SMS
                    - BOTH
                    - null
                    nullable: true
                    default: null
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /delivery/get-historical-rates:
    x-exegesis-controller: Delivery
    get:
      summary: Get historical rates for a delivery
      operationId: getHistoricalDeliveryRates
      security: []
      parameters:
      - name: deliveryId
        in: query
        description: Onerail uuid deliveryId or internal user deliveryId
        required: false
        schema:
          type: string
      - name: orderId
        in: query
        description: Onerail uuid deliveryId or internal user deliveryId
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success. The delivery historical rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalRateInfo'
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No  record found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /delivery/{deliveryId}/reschedule:
    x-exegesis-controller: Delivery
    post:
      summary: Reschedule delivery
      operationId: rescheduleDelivery
      security:
      - ApiKey: []
      - OAuth: []
      - AppId: []
      parameters:
      - name: deliveryId
        in: path
        description: target delivery
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Reschedule delivery dispatch payload.
        content:
          application/json:
            schema:
              type: object
              required:
              - dispatchAt
              properties:
                dispatchAt:
                  type: string
                  description: datetime in ISO format
                  format: date-time
                  nullable: true
                numericSystem:
                  type: string
                  default: IMPERIAL
                  enum:
                  - IMPERIAL
                  - METRIC
      responses:
        '200':
          description: Returns delivery details
          content:
            application/json:
              schema:
                $ref: '#/paths/~1delivery~1%7Bid%7D~1details/get/responses/200/content/application~1json/schema'
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /delivery/{id}/cancel:
    x-exegesis-controller: Delivery
    post:
      summary: Cancel a delivery
      operationId: cancelDelivery
      security:
      - ApiKeyAndAppId: []
      - ApiKey: []
      - OAuth: []
      - AppId: []
      parameters:
      - name: id
        in: path
        description: delivery id
        required: true
        schema:
          type: string
      requestBody:
        description: Reason
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: object
                  properties:
                    title:
                      type: string
      responses:
        '200':
          description: Success. The delivery has been cancelled.
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /delivery/{id}/shipment-id:
    x-exegesis-controller: Delivery
    post:
      summary: Update the shipmentId on a delivery
      operationId: updateShipmentId
      security:
      - ApiKey: []
      - OAuth: []
      - AppId: []
      parameters:
      - name: id
        in: path
        description: delivery id
        required: true
        schema:
          type: string
      requestBody:
        description: shipmentId
        content:
          application/json:
            schema:
              type: object
              properties:
                shipmentId:
                  type: string
      responses:
        '200':
          description: ShipmentId has been updated or cleared
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /delivery/pre-validation:
    x-exegesis-controller: Delivery
    post:
      summary: Validate delivery before creation
      operationId: preValidateDelivery
      security:
      - ApiKeyAndAppId: []
      - ApiKey: []
      - OAuth: []
      - AppId: []
      requestBody:
        description: The delivery to be created with all required parameters
        required: true
        content:
          application/json:
            schema:
              type: object
              description: pre Delivery
              properties:
                from:
                  description: Pickup location
                  $ref: '#/paths/~1delivery~1pre-validation/post/requestBody/content/application~1json/schema/properties/to'
                to:
                  description: Drop off location
                  type: object
                  properties:
                    location:
                      type: object
                      description: Geo Point with latitude and longitude
                      required:
                      - latitude
                      - longitude
                      properties:
                        latitude:
                          type: number
                        longitude:
                          type: number
                order:
                  description: Order data
                  type: object
                  properties:
                    orderItems:
                      type: array
                      items:
                        type: object
                        description: Order Item
                        properties:
                          lengthIn:
                            type: number
                            description: item length
                          lengthCm:
                            type: number
                            description: item length
                          widthIn:
                            type: number
                            description: item width
                          widthCm:
                            type: number
                            description: item width
                          heightIn:
                            type: number
                            description: item height
                          heightCm:
                            type: number
                            description: item height
                          weightLbs:
                            type: number
                            description: item weight
                          weightKg:
                            type: number
                            format: float
                          quantity:
                            type: number
                            description: item quantity
                includePrice:
                  type: boolean
                  description: Flag wether to calculate price or not
      responses:
        '200':
          description: Success. Shipper SLA found for that delivery
          content:
            application/json:
              schema:
                type: object
                description: pre Delivery
                properties:
                  shipperSlaId:
                    type: string
                    description

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