Overview
This article outlines the API functionalities defined for CapacityConnect™ to integrate with the OneRail OmniPoint® platform.
Authentication
Organization-based authentication utilizes a pair of values (App ID and API Key) that are attached to the header of requests intended for the OneRail API Engine. These credentials are provided by OneRail support (support@onerail.io).
These credentials can be used to authenticate any request intended for your organization's OneRail account.
Note: To implement these credentials, their values will need to be added to the header of any request intended for the OneRail API Engine.
The following code block shows the headers and their associated values:
X-ONERAIL-APP-ID: App ID provided by support
X-ONERAIL-API-KEY: API Key provided by support
Important Prerequisite
Before executing deliveries end-to-end, pickup locations must be configured in the platform. Refer to the following steps for setup instructions.
Adding a Location
Endpoint
POST https://onerail-operations-staging.azurewebsites.net/v1/location
POST https://onerail-operations-uat.azurewebsites.net/v1/location
POST https://onerail-operations-prod.azurewebsites.net/v1/location
Example Request Payload
|
Example 200 Response
|
Example Error Response
|
Add Location
Note: Adding a location requires an Administrative role.
To add a new location, complete the following steps from the Organization page:
- Click Locations.
- Click Add Location.
- Enter the following information for the location:
- Name
- Store Number
- Address
- Phone Number
- Contact
- Shipping and Receiving Instructions as needed.
- Enter Cut-off Time for pickup.
- Enter Hours of Operation for each day of the week.
- Enter Holiday Hours.
- Click Add.
Check Delivery Availability
Endpoint
POST https://onerail-delivery-api-staging.azurewebsites.net/delivery/check-availability
POST https://onerail-delivery-api-uat.azurewebsites.net/delivery/check-availability
POST https://onerail-delivery-api-prod.azurewebsites.net/delivery/check-availability
Overview
This endpoint checks whether a delivery can be fulfilled for a given set of pickup and drop-off locations. It supports progressive input — a minimal request with only location data returns top-level availability, while a richer request can include service-level details and estimated pricing.
Parameters
Key Fields and Constraints
| Field | Type | Required | Notes |
| pickUpData | object | Yes | Pickup location data. Provide any combination of address fields and/or a geopoint. |
| dropOffData | object | Yes | Drop-off location data. Provide any combination of address fields and/or a geopoint. |
| items | array of object | No | List of items in the shipment. Required to return valid rate estimates. Each item should include dimensions, weight, quantity, and description. |
| containers | array of object | No | List of containers, for example, boxes, used to package the shipment. Required to return valid rate estimates. Each container should include name, total weight, and the items it contains. |
| serviceLevels | array of string | No | Optional list of service level names to check. |
| contractId | string | No | Contract to deliver this package under. |
| deliveryType | enum | No | Allowed: BUSINESS, RESIDENTIAL. |
| carrierCode | string | No | Code identifying the requested carrier. |
| carrierServiceName | string | No | Specific carrier service level requested. |
| deliveryOptions | array of enum | No | Allowed: REQUIRE_SIGNATURE. |
| requestLabel | boolean | No | Default: false. Request a shipping label in the response. |
| labelType | enum | No | Default: png. Format of the OneRail-generated shipping label. |
| state | enum | No |
Default: READY_TO_DISPATCH. Allowed: DRAFT, READY_TO_DISPATCH. |
| numericSystem | enum | No |
Default: IMPERIAL. Allowed: IMPERIAL, METRIC. |
| dispatchAt | string (date-time) | No | Datetime in ISO 8601 format. |
| nonDeliveryBehavior | enum | No | Allowed: return (package returned to sender), abandon (package discarded at carrier's discretion). |
Note: To receive valid rate estimates in the response, the request must include pickup and drop-off data along with either items, containers, or both. Requests that omit item and container data will return only top-level availability without pricing details.
Progressive Input and Response Detail
The level of detail returned in the response depends on how much data you provide in the request.
A minimal request — one that includes only pickUpData and dropOffData — returns top-level availability. The dataCompleteness field in the response will be MINIMAL.
A richer request that includes fields such as serviceLevels, carrierCode, or carrierServiceName enables service-level details and estimated pricing in the response.
Example Request Payload
|
Example Response
|
The dataCompleteness field reflects how much input data you provided. A value of MINIMAL indicates that only top-level availability is returned. Richer requests enable service-level details, including estimatedPrice.
Error Response Format (400 Bad Request, 401 Unauthorized, and Server Errors)
|
Steps
- Build the request body using the CheckAvailabilityRequest schema defined in the API documentation. At minimum, provide pickUpData and dropOffData. Include more fields to receive service-level details in the response.
- Send a POST request to {base_url}/v1/delivery/check-availability with the required authentication headers.
- A successful request returns 200. Review the response to determine availability and, if applicable, service-level details and estimated pricing.
Delivery Creation
Endpoint
POST https://onerail-delivery-api-staging.azurewebsites.net/v2/order
POST https://onerail-delivery-api-uat.azurewebsites.net/v2/order
POST https://onerail-delivery-api-prod.azurewebsites.net/v2/order
Required Schema Fields
| Field | Type | Notes |
deliveryType |
string |
Allowed values: BUSINESS or RESIDENTIAL. |
orderData |
object |
With: OrderId — string |
pickUpData |
object (LocationInfo) |
With:
|
dropOffData |
object (LocationInfo) |
With:
|
Minimal JSON Example
|
Example Response
|
Steps
- Build the request body using the OrderRequest schema defined in the API documentation.
- Send a POST request to {base_url}/v1/order with your order data payload, including the required authentication headers.
- A successful request returns 202 Accepted. Review the response payload and capture any identifiers returned by the API.
Cancel a Delivery
Endpoint
|
Overview
Cancels a delivery by its unique identifier. Include a cancellation reason in the request body.
Parameters
Required Path Parameter
| Parameter | Type | Location | Description |
| id | UUID | Path | The unique identifier of the delivery to cancel. |
Example Request URL
|
Example Request Payload
The reason field is required and accepts any string describing the reason for cancellation.
|
Steps
- Identify the delivery you want to cancel and copy its id (UUID).
- Send a POST request to the cancel endpoint, replacing {id} in the path with the delivery UUID.
- Include a cancellation reason in the request body.
Responses
200 - Success
The delivery has been cancelled.
|
400 - Bad Request
Example 1 - Generic bad request:
|
Example 2 - Validation error:
|
Review the errors array for field-level detail on validation failures. The path field identifies the specific request field that caused the error.
401 — Unauthorized
The request did not include valid authentication credentials.
|
Default - Internal Server Error
An unexpected error occurred on the server.
|
Adding a User
Endpoint
POST https://onerail-operations-staging.azurewebsites.net/v1/user
POST https://onerail-operations-uat.azurewebsites.net/v1/user
POST https://onerail-operations-prod.azurewebsites.net/v1/user
Schema fields
When creating users, ensure appropriate role assignment. Roles will need to be applied to each user through the UI regardless of whether they were created manually or via an API call. Supported roles include:
- Location/Ops User
- View Only
- Global Admin
The list below includes every property from emailAddress through employeeId in the request payload, with each field marked as Required or Optional.
| Field | Type | Requirement |
|---|---|---|
| emailAddress | string - email | Required |
| firstName | string | Required |
| lastName | string | Required |
| phoneNumber | string | Optional |
| active | boolean | Required |
| driver | object | Optional |
| title | string | Optional |
| organizationId | string - uuid | Required |
| employeeId | string | Optional |
Minimal Request Payload JSON Example
|
200 Successful Response Payload JSON Example
|
Error Response Payload JSON Example
|
Delivery Events and Webhooks
Webhooks allow applications to communicate with each other in real-time, eliminating the need for manual intervention or polling for updates. Information between applications can be shared and processed much faster when requests are sent by the resource that contains the information only when a change is processed as opposed to a requester relying on an arbitrary polling interval.
OneRail provides immediate alerts regarding the change in status of orders processed by your organization. This can be processed by your application to push out notifications to customers/internal staff, or dynamically respond and process depending on the status of the delivery.
Important Requirement: A webhook endpoint (URL) must be provided and configured BEFORE events will be sent to the shipper. Without this configuration, event notifications will not be delivered.
The following list outlines expected results for standard courier events currently supported by OneRail as an example of the capabilities for events and webhooks from our API. Each event here is defined by its associated event type, their results include the OneRail delivery ID and subsequent shipper order ID associated with the event.
ACCEPTED_BY_LP
|
CANCELED_BY_ONERAIL
|
DRIVER_ASSIGNED
|
EN_ROUTE_TO_PICKUP
|
ARRIVED_FOR_PICKUP
|
PICKED_UP
|
EN_ROUTE_TO_DELIVERY
|
ARRIVED_FOR_DELIVERY
|
DELIVERED
|
Troubleshooting
POST /v1/location - Adding a Location
| HTTP Status | Status Description | Likely Cause |
| 202 | Location | Request was accepted and the location was added |
| 500 | Internal server error | An unexpected error occurred on the server |
POST /v1/order - Create an Order
| HTTP Status | Status Description | Likely Cause | Resolution |
| 202 | Accepted | Request was accepted and is being processed | Capture the orderID and deliveryIDs from the response to track the order |
| 400 | Bad request - generic | Malformed request body or missing required fields | Review the message field in the response and verify all required fields are present and correctly formatted |
| 400 | Bad request - validation error | A field value does not match the allowed values (for example, an invalid orderAction, state, or deliveryOptions value) | Review the errors array. The path field identifies the specific field that failed validation. Correct the value and resubmit |
| 401 | Unauthorized | Missing or invalid X-ONERAIL-API-KEY or X-ONERAIL-APP-ID headers | Confirm both authentication headers are included and valid for the target environment |
| 500 | Internal server error | An unexpected error occurred on the server | Retry the request. If the error persists, contact your integration support team |
POST /v1/delivery/{id}/cancel — Cancel a delivery
| HTTP Status | Status Description | Likely Cause | Resolution |
| 200 | Success | Availability check completed successfully | Review the availability field and serviceLevels array in the response for per-service pricing and availability detail |
| 400 | Bad request - generic | Malformed request body or missing required fields | Review the message field in the response and verify all required fields are present and correctly formatted |
| 400 | Bad request - validation error | The reason field value is not one of the accepted cancellation reason codes | Review the errors array. Correct the reason value to one of the accepted codes and resubmit |
| 401 | Unauthorized | Missing or invalid X-ONERAIL-API-KEY or X-ONERAIL-APP-ID headers | Confirm both authentication headers are included and valid for the target environment |
| 500 | Internal server error | An unexpected error occurred on the server | Retry the request. If the error persists, contact your integration support team |
POST /v1/delivery/check-availability — Check delivery availability
| HTTP Status | Status Description | Likely Cause | Resolution |
| 200 | Success | Availability check completed successfully | Review the availability field and serviceLevels array in the response for per-service pricing and availability detail |
| 400 | Bad request - generic | Malformed request body or missing required fields | Review the message field in the response and verify all required fields are present and correctly formatted |
| 400 | Bad request - validation error | A field value does not match the allowed values (for example, an invalid orderAction, state, or deliveryOptions value) | Review the errors array. The path field identifies the specific field that failed validation. Correct the value and resubmit |
| 401 | Unauthorized | Missing or invalid X-ONERAIL-API-KEY or X-ONERAIL-APP-ID headers | Confirm both authentication headers are included and valid for the target environment |
| 500 | Internal server error | An unexpected error occurred on the server | Retry the request. If the error persists, contact your integration support team |
POST /v1/user — Adding a User
| HTTP Status | Status Description | Likely Cause |
| 200 | User Record | Request was accepted and the user was added |
| 500 | Internal server error | An unexpected error occurred on the server |
Common Integration Issues
| Issue | Likely Cause | Solution |
| 401 Unauthorized | Missing or invalid authentication headers | Confirm both X-ONERAIL-APP-ID and X-ONERAIL-API-KEY are included and correct for the target environment. |
202 returned but order not visible |
Processing delay | Allow time for the order to be processed. Capture the identifiers from the response to query the order status |
orderData.orderId rejected on CREATE
|
Order ID already exists | Use a unique orderId value or change orderAction to ADD if associating with an existing order |
orderData.orderId rejected on ADD or RETURN
|
Referenced order does not exist | Verify the orderId value matches an existing order in the target environment |
| Delivery ID is incorrect or delivery is not in a cancellable state | Confirm the UUID is accurate and that the delivery status supports cancellation |
Comments
0 comments
Please sign in to leave a comment.