API docs by RedoclyBitfreighter API (1.0)
Download OpenAPI specification:Download
The Bitfreighter API is an HTTP API that allows you to integrate your system with Bitfreighter.
Warning The Bitfreighter API will make additive changes that can break client code if built too strictly. Enums can have new values added, and new fields can be added to objects. It is recommended to build clients that are resilient to these changes.
EDI
Use standard Bearer token authentication. The token can by obtained by reaching out to your Bitfreighter Customer Success representative.
Send the token as a header in the following format:
Content-Type: application/json
Authentication: Bearer <token>
Security Scheme Type: HTTP
HTTP Authorization Scheme:
bearerLiveQuote
LiveQuote auth works seperately from the EDI endpoints. It uses an Oauth 2.0 Client Credentials workflow. These credentials can also be obtained by reaching out to your Bitfreighter Customer Success representative.
First, obtain an token from our authentication server. The authentication server takes your client_id and client_secret as basic auth, and requires the following key/value pairs to be sent over as Form URL Encoded.
| Key | Value |
|---|---|
| grant_type | client_credentials |
| scope | https://api.bitfreighter.com/live_quote |
POST https://bitfreighter.auth.us-east-2.amazoncognito.com/oauth2/token
Authentication: Basic <client_id:client_secret base64 encoded>
Content-Type: application/form-url-encoded
POST BODY:
<see form url encoded table above>
If done properly, the response will look like the following:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"expires_in": 3600,
"token_type": "Bearer"
}
Send the access_token as a header in the following format:
Content-Type: application/json
Authentication: Bearer <token>
Security Scheme Type: HTTP
HTTP Authorization Scheme:
bearer2025-04-02
- added the abliity to add a reason to the AppointmentUpdate event
2025-02-25
- Changed Note type from enum to string length 3
- We now support top level references in ShipmentStatusUpdate and AppointmentUpdate Events
2024-11-13
- All addresses now accept any 3 letter code for country
- [LQ - Custom Pricing Engine] Added 'fuel' and 'fuel_strategy_response' to data response object
- [LQ - Custom Pricing Engine] Removed 'line_haul_rate' field from data object
2024-11-08
- [LQ - Rate Request] added total_cargo_value.
- [LQ - Custom Pricing Engine] Added cargo_value to outgoing request.
2024-10-25
- [LQ - Custom Pricing Engine] Added new shipper object to outgoing request, moved shipper_identifier into shipper object, and renamed shipper_identifier to identifier
- [LQ - Custom Pricing Engine] Added profile_name to shipper object
2024-10-02
- Changed Equipment type from enum to string length 2
2024-09-30
- Added new BillToParty, BillToAddress, which allows any country code for bill to parties
- Added FlexAddress which allows 2 and 3 letter country codes for North America
2024-08-02
- Added LiveQuote specific authentication documentation
2024-06-18
- Added more accessorials to Rate Request
2024-06-10
- Added an optional Rate Request Response API endpoint to allow shippers to communicate what bids they accept/reject
2024-06-05
- Added field 'buy_it_now_price' to Rate Request and added possible value 'accept_buy_it_now` to Rate Request Success Response 'rate_type' enum
2024-05-20
- Grouped EDI and LiveQuote endpoints under separate tags
2024-05-15
- Removed custom Rate Request error structure in favor of common OpenAPI Error Response
- Reworked Rate Request schema to match naming conventions used in existing EDI endpoints
2024-05-14
- changed ShipmentStatusUpdate.reason.code and ReferenceNumber.type from enum types to string types
2024-04-11
- added Rate Request action to documentation. This is a new public API that will be coming soon!
2024-03-22
- added possible value 'delayed' to the ShipmentStatusUpdate.status enum
- added field 'reason' to ShipmentStatusUpdate for sending status reasons
Carrier Events
LoadTender- Motor Carrier Load Tender (EDI 204, B2A-01 = 00 or 02)LoadTenderUpdate- Motor Carrier Load Tender Update (EDI 204, B2A-01 = 04 or 05)LoadTenderCancel- Motor Carrier Load Tender Cancellation (EDI 204, B2A-01 = 01 or 03)
Shipper Events
Accept- Accept Load Tender (EDI 990)Decline- Decline Load Tender (EDI 990)Invoice- Invoice (EDI 210)ShipmentStatusUpdate- Carrier Shipment Status Message (EDI 214)AppointmentUpdate- Shipment Appointment Update (EDI 214)
Typical ShipmentStatusUpdate (214) events sequence
Accept Webhook
Request Body schema: application/json
| type required | string Default: "Accept" Value: "Accept" |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner sending the message |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner receiving the message |
| shipment_id required | string (ShipmentId) <= 30 characters Shipment identifier assigned by the shipper. This number is used on all load tenders, accept, decline, updates, cancellations and invoices |
| carrier_number | string or null (CarrierNumber) <= 30 characters Carrier's Reference Number (PRO/Invoice) |
| mode | string (Mode) Enum: "test" "production" "test" or "production" |
| notes | string or null <= 600 characters Default: "" To transmit information in a free-form format, if necessary, for comment or special instruction |
Request samples
- Payload
Content type
application/json
{- "carrier_number": "CX-1234-5678",
- "mode": "test",
- "notes": "You'll need a lift-gate",
- "receiver": {
- "bf_id": 123
}, - "sender": {
- "bf_id": 123
}, - "shipment_id": "1234567890",
- "type": "Accept"
}AppointmentUpdate Webhook
Request Body schema: application/json
| type required | string Default: "AppointmentUpdate" Value: "AppointmentUpdate" |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner sending the message |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner receiving the message |
| shipment_id required | string (ShipmentId) <= 30 characters Shipment identifier assigned by the shipper. This number is used on all load tenders, accept, decline, updates, cancellations and invoices |
| carrier_number required | string or null (CarrierNumber) <= 30 characters Carrier's Reference Number (PRO/Invoice) |
required | object (ShipmentStatusStop) Stop information for a load |
required | (Appointment (Appointment.DateWindow (object) or Appointment.DateTimeWindow (object))) or DateTime (string) or Date (string) Date and/or time of the appointment |
| mode | string (Mode) Enum: "test" "production" "test" or "production" |
object or null (ShipmentStatusReason) Indicating the reason a shipment status reason was transmitted (typically for delayed status) | |
Array of objects (ReferenceNumber) <= 10 characters Default: [] Reference Numbers |
Request samples
- Payload
Content type
application/json
{- "carrier_number": "ABC1234567890",
- "datetime": "2025-04-18T21:04:52.063421Z",
- "mode": "test",
- "reason": {
- "code": "A1"
}, - "receiver": {
- "bf_id": 123
}, - "reference_numbers": [
- {
- "type": "MB",
- "value": "123456789"
}
], - "sender": {
- "bf_id": 123
}, - "shipment_id": "1234567890",
- "stop": {
- "location": {
- "additional_names": [
- "Bitfreighter Location",
- "Building 42"
], - "address": {
- "city": "Akron",
- "country": "USA",
- "line1": "1234 Main St.",
- "line2": "suite a",
- "postal_code": "44312",
- "state": "OH"
}, - "contacts": [
- {
- "email": "peter@example.com",
- "name": "Peter Pan",
- "phone": "1234567890"
}
], - "identification": {
- "duns": "123456789"
}, - "name": "Bitfreighter"
}, - "notes": [
- {
- "content": "You'll need a lift-gate",
- "type": "LOI"
}
], - "reason": "pickup",
- "reference_numbers": [
- {
- "type": "MB",
- "value": "123456789"
}
], - "sequence_number": 1
}, - "type": "AppointmentUpdate"
}Decline Webhook
Request Body schema: application/json
| type required | string Default: "Decline" Value: "Decline" |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner sending the message |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner receiving the message |
| shipment_id required | string (ShipmentId) <= 30 characters Shipment identifier assigned by the shipper. This number is used on all load tenders, accept, decline, updates, cancellations and invoices |
| mode | string (Mode) Enum: "test" "production" "test" or "production" |
| reason | string or null Short code indicating the decline reason Examples, non-exhaustive:
|
Request samples
- Payload
Content type
application/json
{- "mode": "production",
- "reason": "ABN",
- "receiver": {
- "bf_id": 123
}, - "sender": {
- "bf_id": 123
}, - "shipment_id": "1234567890",
- "type": "Decline"
}Invoice Webhook
Request Body schema: application/json
| type required | string Default: "Invoice" Value: "Invoice" |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner sending the message |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner receiving the message |
| shipment_id required | string (ShipmentId) <= 30 characters Shipment identifier assigned by the shipper. This number is used on all load tenders, accept, decline, updates, cancellations and invoices |
| invoice_id required | string <= 100 characters Invoice ID |
| billing_date required | string <date> (Date) Date as ISO8601 formatted string |
required | object or null (Payment) Payment info for a load tender |
required | Array of objects (LineItem) [ 1 .. 999 ] characters Line items |
required | Array of objects (InvoiceStop) [ 2 .. 999 ] characters Pickup and dropoff stop completion dates |
object or null (Party) Bill-To party (if different from shipper) | |
object or null (CorrectionIndicator) Invoice correction reason | |
| currency | string or null (Currency) Enum: "USD" "CAD" "MXN" Currency |
Array of objects (InvoiceItem) [ 1 .. 999 ] characters Default: [] Items | |
| mode | string (Mode) Enum: "test" "production" "test" or "production" |
| net_amount | string or null (Decimal) [ 1 .. 30 ] characters ^-?\d+(.\d+)?$ Net amount if different than total of line items |
Array of objects (ReferenceNumber) <= 10 characters Default: [] Reference Numbers |
Request samples
- Payload
Content type
application/json
{- "billing_date": "2025-04-18",
- "correction_indicator": {
- "type": "CO"
}, - "currency": "USD",
- "invoice_id": "INV-123",
- "items": [
- {
- "number": "123456789",
- "weight": {
- "amount": "123.45",
- "unit": "K"
}
}, - {
- "number": "123456789",
- "weight": {
- "amount": "123.45",
- "unit": "K"
}
}
], - "line_items": [
- {
- "amount": "1234.56",
- "charge_code": "fuel",
- "description": "Fuel",
- "quantity": {
- "count": "42",
- "unit": "UNT"
}
}, - {
- "amount": "1234.56",
- "charge_code": "fuel",
- "description": "Fuel",
- "quantity": {
- "count": "42",
- "unit": "UNT"
}
}
], - "mode": "test",
- "net_amount": "123.45",
- "payment": {
- "terms": "PP"
}, - "receiver": {
- "bf_id": 123
}, - "sender": {
- "bf_id": 123
}, - "shipment_id": "1234567890",
- "stops": [
- {
- "completed_at": "2025-04-18",
- "location": {
- "additional_names": [
- "Bitfreighter Location",
- "Building 42"
], - "address": {
- "city": "Akron",
- "country": "USA",
- "line1": "1234 Main St.",
- "line2": "suite a",
- "postal_code": "44312",
- "state": "OH"
}, - "contacts": [
- {
- "email": "peter@example.com",
- "name": "Peter Pan",
- "phone": "1234567890"
}
], - "identification": {
- "duns": "123456789"
}, - "name": "Bitfreighter"
}, - "reason": "pickup",
- "sequence_number": 1
}, - {
- "completed_at": "2025-04-18",
- "location": {
- "additional_names": [
- "Bitfreighter Location",
- "Building 42"
], - "address": {
- "city": "Akron",
- "country": "USA",
- "line1": "1234 Main St.",
- "line2": "suite a",
- "postal_code": "44312",
- "state": "OH"
}, - "contacts": [
- {
- "email": "peter@example.com",
- "name": "Peter Pan",
- "phone": "1234567890"
}
], - "identification": {
- "duns": "123456789"
}, - "name": "Bitfreighter"
}, - "reason": "pickup",
- "sequence_number": 1
}
], - "type": "Invoice"
}LoadTender Webhook
Request Body schema: application/json
| type required | string Default: "LoadTender" Value: "LoadTender" |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner sending the message |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner receiving the message |
| shipment_id required | string (ShipmentId) <= 30 characters Shipment identifier assigned by the shipper. This number is used on all load tenders, accept, decline, updates, cancellations and invoices |
required | Array of objects (LoadTenderStop) [ 2 .. 999 ] characters Pickup and dropoff stop details |
object or null (Party) Bill-To party (if different from shipper) | |
Array of objects (Charge) Default: [] Charges pertaining to the shipment | |
object or null (Party) Contact (if different from shipper) | |
object or null (Equipment) Equipment Details | |
Array of objects (LoadTenderItem) Default: [] Information about items to be shipped | |
| mode | string (Mode) Enum: "test" "production" "test" or "production" |
Array of objects (Note) <= 10 characters Default: [] Notes or special instructions for the Load | |
object or null (Payment) Payment info for a load tender | |
Array of objects (ReferenceNumber) <= 10 characters Default: [] Load Reference Numbers | |
| respond_by | string or null <date-time> (DateTime) Date/Time as ISO8601 formatted string |
object or null (Party) Shipper who is tendering the load |
Request samples
- Payload
Content type
application/json
{- "charges": [
- {
- "amount": "1234.56",
- "description": "400: Line Haul",
- "type": "line_haul"
}
], - "equipment": {
- "type": "TV"
}, - "items": [
- {
- "commodity_code": "42",
- "description": "Widgets",
- "dropoff_stop_sequence_number": 2,
- "handling_quantity": {
- "count": "10",
- "unit": "PLT"
}, - "is_hazardous": false,
- "number": "123456789",
- "packaging_quantity": {
- "count": "42",
- "unit": "PCK"
}, - "pickup_stop_sequence_number": 1,
- "volume": {
- "amount": "123.45",
- "unit": "E"
}, - "weight": {
- "amount": "123.45",
- "unit": "K"
}
}, - {
- "commodity_code": "42",
- "description": "Widgets",
- "dropoff_stop_sequence_number": 2,
- "handling_quantity": {
- "count": "10",
- "unit": "PLT"
}, - "is_hazardous": false,
- "number": "123456789",
- "packaging_quantity": {
- "count": "42",
- "unit": "PCK"
}, - "pickup_stop_sequence_number": 1,
- "volume": {
- "amount": "123.45",
- "unit": "E"
}, - "weight": {
- "amount": "123.45",
- "unit": "K"
}
}
], - "mode": "test",
- "notes": [
- {
- "content": "You'll need a lift-gate",
- "type": "LOI"
}
], - "payment": {
- "terms": "PP"
}, - "receiver": {
- "bf_id": 123
}, - "respond_by": "2025-04-18T21:04:52.063421Z",
- "sender": {
- "bf_id": 123
}, - "shipment_id": "1234567890",
- "stops": [
- {
- "location": {
- "additional_names": [
- "Bitfreighter Location",
- "Building 42"
], - "address": {
- "city": "Akron",
- "country": "USA",
- "line1": "1234 Main St.",
- "line2": "suite a",
- "postal_code": "44312",
- "state": "OH"
}, - "contacts": [
- {
- "email": "peter@example.com",
- "name": "Peter Pan",
- "phone": "1234567890"
}
], - "identification": {
- "duns": "123456789"
}, - "name": "Bitfreighter"
}, - "notes": [
- {
- "content": "You'll need a lift-gate",
- "type": "LOI"
}
], - "reason": "pickup",
- "reference_numbers": [
- {
- "type": "MB",
- "value": "123456789"
}
], - "scheduled_at": {
- "end_datetime": "2023-01-01T14:00:00Z",
- "start_datetime": "2023-01-01T12:00:00Z"
}, - "sequence_number": 1
}, - {
- "location": {
- "additional_names": [
- "Bitfreighter Location",
- "Building 42"
], - "address": {
- "city": "Akron",
- "country": "USA",
- "line1": "1234 Main St.",
- "line2": "suite a",
- "postal_code": "44312",
- "state": "OH"
}, - "contacts": [
- {
- "email": "peter@example.com",
- "name": "Peter Pan",
- "phone": "1234567890"
}
], - "identification": {
- "duns": "123456789"
}, - "name": "Bitfreighter"
}, - "notes": [
- {
- "content": "You'll need a lift-gate",
- "type": "LOI"
}
], - "reason": "pickup",
- "reference_numbers": [
- {
- "type": "MB",
- "value": "123456789"
}
], - "scheduled_at": {
- "end_datetime": "2023-01-01T14:00:00Z",
- "start_datetime": "2023-01-01T12:00:00Z"
}, - "sequence_number": 2
}
], - "type": "LoadTender"
}LoadTenderCancel Webhook
Request Body schema: application/json
| type required | string Default: "LoadTenderCancel" Value: "LoadTenderCancel" |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner sending the message |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner receiving the message |
| shipment_id required | string (ShipmentId) <= 30 characters Shipment identifier assigned by the shipper. This number is used on all load tenders, accept, decline, updates, cancellations and invoices |
| mode | string (Mode) Enum: "test" "production" "test" or "production" |
Request samples
- Payload
Content type
application/json
{- "mode": "test",
- "receiver": {
- "bf_id": 123
}, - "sender": {
- "bf_id": 123
}, - "shipment_id": "1234567890",
- "type": "LoadTenderCancel"
}LoadTenderUpdate Webhook
Request Body schema: application/json
| type required | string Default: "LoadTenderUpdate" Value: "LoadTenderUpdate" |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner sending the message |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner receiving the message |
| shipment_id required | string (ShipmentId) <= 30 characters Shipment identifier assigned by the shipper. This number is used on all load tenders, accept, decline, updates, cancellations and invoices |
required | Array of objects (LoadTenderStop) [ 2 .. 999 ] characters Pickup and dropoff stop details |
object or null (Party) Bill-To party (if different from shipper) | |
Array of objects (Charge) Default: [] Charges pertaining to the shipment | |
object or null (Party) Contact (if different from shipper) | |
object or null (Equipment) Equipment Details | |
Array of objects (LoadTenderItem) Default: [] Information about items to be shipped | |
| mode | string (Mode) Enum: "test" "production" "test" or "production" |
Array of objects (Note) <= 10 characters Default: [] Notes or special instructions for the Load | |
object or null (Payment) Payment info for a load tender | |
Array of objects (ReferenceNumber) <= 10 characters Default: [] Load Reference Numbers | |
| respond_by | string or null <date-time> (DateTime) Date/Time as ISO8601 formatted string |
object or null (Party) Shipper who is tendering the load |
Request samples
- Payload
Content type
application/json
{- "charges": [
- {
- "amount": "1234.56",
- "description": "400: Line Haul",
- "type": "line_haul"
}
], - "equipment": {
- "type": "TV"
}, - "items": [
- {
- "commodity_code": "42",
- "description": "Widgets",
- "dropoff_stop_sequence_number": 2,
- "handling_quantity": {
- "count": "10",
- "unit": "PLT"
}, - "is_hazardous": false,
- "number": "123456789",
- "packaging_quantity": {
- "count": "42",
- "unit": "PCK"
}, - "pickup_stop_sequence_number": 1,
- "volume": {
- "amount": "123.45",
- "unit": "E"
}, - "weight": {
- "amount": "123.45",
- "unit": "K"
}
}, - {
- "commodity_code": "42",
- "description": "Widgets",
- "dropoff_stop_sequence_number": 2,
- "handling_quantity": {
- "count": "10",
- "unit": "PLT"
}, - "is_hazardous": false,
- "number": "123456789",
- "packaging_quantity": {
- "count": "42",
- "unit": "PCK"
}, - "pickup_stop_sequence_number": 1,
- "volume": {
- "amount": "123.45",
- "unit": "E"
}, - "weight": {
- "amount": "123.45",
- "unit": "K"
}
}
], - "mode": "test",
- "notes": [
- {
- "content": "You'll need a lift-gate",
- "type": "LOI"
}
], - "payment": {
- "terms": "PP"
}, - "receiver": {
- "bf_id": 123
}, - "respond_by": "2025-04-18T21:04:52.063421Z",
- "sender": {
- "bf_id": 123
}, - "shipment_id": "1234567890",
- "stops": [
- {
- "location": {
- "additional_names": [
- "Bitfreighter Location",
- "Building 42"
], - "address": {
- "city": "Akron",
- "country": "USA",
- "line1": "1234 Main St.",
- "line2": "suite a",
- "postal_code": "44312",
- "state": "OH"
}, - "contacts": [
- {
- "email": "peter@example.com",
- "name": "Peter Pan",
- "phone": "1234567890"
}
], - "identification": {
- "duns": "123456789"
}, - "name": "Bitfreighter"
}, - "notes": [
- {
- "content": "You'll need a lift-gate",
- "type": "LOI"
}
], - "reason": "pickup",
- "reference_numbers": [
- {
- "type": "MB",
- "value": "123456789"
}
], - "scheduled_at": {
- "end_datetime": "2023-01-01T14:00:00Z",
- "start_datetime": "2023-01-01T12:00:00Z"
}, - "sequence_number": 1
}, - {
- "location": {
- "additional_names": [
- "Bitfreighter Location",
- "Building 42"
], - "address": {
- "city": "Akron",
- "country": "USA",
- "line1": "1234 Main St.",
- "line2": "suite a",
- "postal_code": "44312",
- "state": "OH"
}, - "contacts": [
- {
- "email": "peter@example.com",
- "name": "Peter Pan",
- "phone": "1234567890"
}
], - "identification": {
- "duns": "123456789"
}, - "name": "Bitfreighter"
}, - "notes": [
- {
- "content": "You'll need a lift-gate",
- "type": "LOI"
}
], - "reason": "pickup",
- "reference_numbers": [
- {
- "type": "MB",
- "value": "123456789"
}
], - "scheduled_at": {
- "end_datetime": "2023-01-01T14:00:00Z",
- "start_datetime": "2023-01-01T12:00:00Z"
}, - "sequence_number": 2
}
], - "type": "LoadTenderUpdate"
}ShipmentStatusUpdate Webhook
Request Body schema: application/json
| type required | string Default: "ShipmentStatusUpdate" Value: "ShipmentStatusUpdate" |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner sending the message |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner receiving the message |
| shipment_id required | string (ShipmentId) <= 30 characters Shipment identifier assigned by the shipper. This number is used on all load tenders, accept, decline, updates, cancellations and invoices |
| carrier_number required | string or null (CarrierNumber) <= 30 characters Carrier's Reference Number (PRO/Invoice) |
| status required | string Enum: "arrived" "departed" "enroute" "delayed" "estimate" |
| datetime required | string <date-time> (DateTime) Date/Time of update |
object or null (Location) Location Information | |
| mode | string (Mode) Enum: "test" "production" "test" or "production" |
object or null (ShipmentStatusReason) Indicating the reason a shipment status reason was transmitted (typically for delayed status) | |
Array of objects (ReferenceNumber) <= 10 characters Default: [] Reference Numbers | |
object or null (ShipmentStatusStop) Stop information for a load |
Request samples
- Payload
Content type
application/json
{- "carrier_number": "ABC1234567890",
- "datetime": "2025-04-18T21:04:52.063421Z",
- "location": {
- "city": "Akron",
- "country": "USA",
- "latitude": 41.081445,
- "longitude": -81.519005,
- "state": "OH"
}, - "reason": {
- "code": "A1"
}, - "receiver": {
- "bf_id": 123
}, - "reference_numbers": [
- {
- "type": "MB",
- "value": "123456789"
}
], - "sender": {
- "bf_id": 123
}, - "shipment_id": "1234567890",
- "status": "arrived",
- "stop": {
- "location": {
- "additional_names": [
- "Bitfreighter Location",
- "Building 42"
], - "address": {
- "city": "Akron",
- "country": "USA",
- "line1": "1234 Main St.",
- "line2": "suite a",
- "postal_code": "44312",
- "state": "OH"
}, - "contacts": [
- {
- "email": "peter@example.com",
- "name": "Peter Pan",
- "phone": "1234567890"
}
], - "identification": {
- "duns": "123456789"
}, - "name": "Bitfreighter"
}, - "notes": [
- {
- "content": "You'll need a lift-gate",
- "type": "LOI"
}
], - "reason": "pickup",
- "reference_numbers": [
- {
- "type": "MB",
- "value": "123456789"
}
], - "sequence_number": 1
}, - "type": "ShipmentStatusUpdate"
}Send event
Authorizations:
None
Request Body schema: application/jsonrequired
Event
| type required | string Default: "Accept" |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner sending the message |
required | TradingPartnerRef.BF (object) (TradingPartner) Trading Partner receiving the message |
| shipment_id required | string (ShipmentId) <= 30 characters Shipment identifier assigned by the shipper. This number is used on all load tenders, accept, decline, updates, cancellations and invoices |
| carrier_number | string or null (CarrierNumber) <= 30 characters Carrier's Reference Number (PRO/Invoice) |
| mode | string (Mode) Enum: "test" "production" "test" or "production" |
| notes | string or null <= 600 characters Default: "" To transmit information in a free-form format, if necessary, for comment or special instruction |
Responses
Response Schema: application/json
| event_id required | string Unique ID for this event. Will be returned on any subsequent Error events coorelating with this event |
Request samples
- Payload
Content type
application/json
Example
{- "carrier_number": "CX-1234-5678",
- "mode": "test",
- "notes": "You'll need a lift-gate",
- "receiver": {
- "bf_id": 123
}, - "sender": {
- "bf_id": 123
}, - "shipment_id": "1234567890",
- "type": "Accept"
}Response samples
- 200
- 422
Content type
application/json
{- "event_id": "F-22jsppb3tJYRIAAidi"
}CSV Formats Specification
Example CSV file
customer_id,shipment_id_number,...
123,SID1,...
456,SID2,...
LoadTender (204)
| Field name | Type | Description |
|---|---|---|
| customer_id required |
integer | |
| shipment_id_number required |
string | length: 1..30 |
| po_number | string | length: 1..80 |
| item_number | string | length: 1..48 |
| item_description | string | length: 1..50 |
| item_qty | integer | |
| item_total_weight | decimal (dd.dd, e.g. 12.34) |
|
| handling_qty | integer | |
| pickup_date required |
date (ISO8601, YYYY-MM-DD, e.g. 2024-01-02) |
|
| pickup_appointment_time | time (HH:MM, e.g. 12:34) |
|
| shipper_name required |
string | length: 1..60 |
| shipper_street_1 required |
string | length: 1..55 |
| shipper_street_2 | string | length: 1..55 |
| shipper_city required |
string | length: 2..30 |
| shipper_state required |
string | length: 2 |
| shipper_postal_code | string | length: 3..15 |
| shipper_country_code required |
string | length: 2..3 |
| delivery_date required |
date (ISO8601, YYYY-MM-DD, e.g. 2024-01-02) |
|
| delivery_appointment_time | time (HH:MM, e.g. 12:34) |
|
| delivery_name required |
string | length: 1..60 |
| delivery_street_1 required |
string | length: 1..55 |
| delivery_street_2 | string | length: 1..55 |
| delivery_city required |
string | length: 2..30 |
| delivery_state required |
string | length: 2 |
| delivery_postal_code | string | length: 3..15 |
| delivery_country_code required |
string | length: 2..3 |
| base_rate required |
decimal (dd.dd, e.g. 12.34) |
|
| fuel | decimal (dd.dd, e.g. 12.34) |
|
| equip_type | string | length: 2 |
| equip_length | string | length: 2..5 |
| temp | decimal (dd.dd, e.g. 12.34) |
|
| reference_XXX | string | replace XXX with qualifier |
ShipmentStatusUpdate (214)
| Field name | Type | Description |
|---|---|---|
| customer_id required |
integer | |
| shipment_id_number required |
string | length: 1..30 |
| carrier_number | string | length: 1..80 |
| status required |
string | one of APPOINTMENT, ENROUTE, ARRIVED, DEPARTED, DELIVERED |
| stop_type required |
string | one of PICKUP, DELIVERY |
| stop_sequence_number required |
integer | |
| location_name required |
string | |
| city required |
string | length: 2..30 |
| state required |
string | length: 2 |
| country required |
string | length: 3 |
| latitude | float | |
| longitude | float | |
| status_date required |
date (ISO8601, YYYY-MM-DD, e.g. 2024-01-02) |
|
| status_time required |
time (HH:MM, e.g. 12:34) |
|
| reference_XXX | string | replace XXX with qualifier |
Rate Request
Request a real time rate for a shipment from a carrier
Request Body schema: application/jsonrequired
RateRequest
| external_reference_id required | string A unique identifier for the web request - helpful for debugging with the API caller |
required | Array of objects (RateRequestStop) An array of stops for the shipment |
| mode required | string Enum: "truckload" "ltl" "airfreight" "rail" The transportation mode requested for the shipment |
| is_all_in required | boolean If true, Bitfreighter will return an all in rate with fuel costs included. Otherwise, Bitfreighter will return the line haul rate |
| equipment required | Array of strings (Equipment) Items Enum: "van" "reefer" "flatbed" An array of equipment types that could be used for delivering the shipment |
| shipper_identifier required | string unique identifier for the shipper |
| accessorials | Array of strings (Accessorials) Items Enum: "drydraught" "hazardous" "insurance" "liftgate" "lowboy" "pallet jack" "plated trailer" "safe transport of food" "stepdeck" "straps" … 3 more An array of additional services requested for the shipment |
| buy_it_now_price | number The rate in USD a carrier may accept for instant booking |
| external_load_reference_id | string A unique identifier for the load. This is useful for helping identify what requests are tied to a particular load. |
| integration | string Recommended. |
| total_cargo_value | number The sum total value of all cargo in the shipment. USD only. |
object The total distance of the shipment | |
object The total volume of the shipment | |
object The total weight of the shipment |
Responses
Response Schema: application/json
| outcome required | string Enum: "success" "no_rate_available" The outcome of the rate request |
object The quote response data returned from the rate request. This will not be present if the outcome is 'no_rate_available' or 'error' | |
| message | string A message describing the outcome of the rate request. This is only provided when the outcome is 'no_rate_available' or 'error' |
Request samples
- Payload
Content type
application/json
{- "accessorials": [
- "hazardous",
- "liftgate"
], - "buy_it_now_price": 0,
- "equipment": [
- "van"
], - "external_load_reference_id": "string",
- "external_reference_id": "string",
- "integration": "string",
- "is_all_in": true,
- "mode": "truckload",
- "shipper_identifier": "string",
- "stops": [
- {
- "location": {
- "address": {
- "city": "Akron",
- "country": "US",
- "line1": "1234 Main St.",
- "line2": "suite a",
- "postal_code": "44312",
- "state": "OH"
}, - "latitude": null,
- "longitude": null
}, - "reason": "load",
- "scheduled_at": "2024-04-11T12:00:00.0Z",
- "sequence_number": 1
}, - {
- "location": {
- "address": {
- "city": "Los Angeles",
- "line1": null,
- "postal_code": "90001",
- "state": "CA"
}
}, - "reason": "unload",
- "scheduled_at": "2024-04-11T12:00:00.0Z",
- "sequence_number": 2
}
], - "total_cargo_value": 1250.5,
- "total_distance": {
- "unit_of_measure": "mi",
- "value": 781
}, - "total_volume": {
- "unit_of_measure": "cubic_feet",
- "value": 0
}, - "total_weight": {
- "unit_of_measure": "lbs",
- "value": 0
}
}Response samples
- 200
- 401
- 403
- 422
- 500
Content type
application/json
{- "data": {
- "quote_id": "string",
- "rate_expiration_datetime": "2019-08-24T14:15:22Z",
- "rate_type": "line_haul",
- "total_rate": 0
}, - "message": "string",
- "outcome": "success"
}Rate Request Response
Respond to a Rate Request
Request Body schema: application/jsonrequired
RateRequestResponse
| quote_id required | string The quote ID provided by the rate_request endpoint |
| status required | string Enum: "accepted" "rejected" The determination the shipper made on behalf of this quote |
Responses
Response Schema: application/json
| outcome required | string Value: "success" The outcome of the rate request |
| message | string A message describing the outcome of the response. |
Request samples
- Payload
Content type
application/json
{- "quote_id": "string",
- "status": "accepted"
}Response samples
- 200
- 401
- 422
- 500
Content type
application/json
{- "message": "string",
- "outcome": "success"
}Fetch Truck Rate
Defines an interface into a customer's custom pricing tool. Note that this defines an API contract that will be consumed Bitfreighter - the implementer will provide Bitfreighter with their Oauth 2.0 server for authorization, and the URL that Bitfreigher will post the request body (disregard the URL defined above)
Request Body schema: application/jsonrequired
CustomPricingEngineRequest
| quote_id required | string The ID for this quote in Bitfreighter |
required | Array of objects (RateRequestStop) An array of stops for the shipment |
| mode required | string Enum: "truckload" "ltl" "airfreight" "rail" The transportation mode requested for the shipment |
| equipment required | string (EquipmentType) Enum: "van" "reefer" "flatbed" The selected equipment type Bitfreighter has determined based off the incoming request and your settings. |
required | object Information on the shipper |
| accessorials | Array of strings (Accessorials) Items Enum: "drydraught" "hazardous" "insurance" "liftgate" "lowboy" "pallet jack" "plated trailer" "safe transport of food" "stepdeck" "straps" … 3 more An array of additional services requested for the shipment |
| available_equipment_types | Array of strings (EquipmentType) Items Enum: "van" "reefer" "flatbed" The full list of requested equipment types that are acceptable for this shipment |
| buy_it_now_price | number or null A price provided by the shipper that can be accepted immediately. If the final quote generated by Bitfreighter is lower than this price, Bitfreighter will automatically accept this load on your behalf. |
| cargo_value | number or null The cargo value of the shipment in USD. |
| comments | string or null Comments from the integration. If available, this could be provided either as freeform text, or a stringified JSON object. |
object The total distance of the shipment | |
object or null The total volume of the shipment | |
object or null The total weight of the shipment |
Responses
Response Schema: application/json
| outcome required | string Enum: "success" "no_rate_available" The outcome of the custom pricing engine request |
object The custom pricing response data. This will not be present if the outcome is 'no_rate_available' | |
| message | string A message describing the outcome of the request. This is only provided when the outcome is 'no_rate_available' |
Request samples
- Payload
Content type
application/json
{- "accessorials": [
- "hazardous",
- "liftgate"
], - "available_equipment_types": [
- "van"
], - "buy_it_now_price": 0,
- "cargo_value": 0,
- "comments": "This is a freeform comment, but a \"{\"stringified\":\"json object\"}\" might be provided instead",
- "equipment": "van",
- "mode": "truckload",
- "quote_id": "132651209",
- "shipper": {
- "identifier": "string",
- "profile_name": "string"
}, - "stops": [
- {
- "location": {
- "address": {
- "city": "Akron",
- "country": "US",
- "line1": "1234 Main St.",
- "line2": "suite a",
- "postal_code": "44312",
- "state": "OH"
}, - "latitude": null,
- "longitude": null
}, - "reason": "load",
- "scheduled_at": "2024-04-11T12:00:00.0Z",
- "sequence_number": 1
}, - {
- "location": {
- "address": {
- "city": "Los Angeles",
- "country": "US",
- "line1": null,
- "postal_code": "90001",
- "state": "CA"
}
}, - "reason": "unload",
- "scheduled_at": "2024-04-11T12:00:00.0Z",
- "sequence_number": 2
}
], - "total_distance": {
- "unit_of_measure": "mi",
- "value": 781
}, - "total_volume": {
- "unit_of_measure": "cubic_feet",
- "value": 0
}, - "total_weight": {
- "unit_of_measure": "lbs",
- "value": 0
}
}Response samples
- 200
- 401
- 403
- 422
- 500
Content type
application/json
{- "data": {
- "all_in_rate": 0,
- "fuel": 0,
- "fuel_strategy_response": "line_haul",
- "updated_equipment_type": "van"
}, - "message": "string",
- "outcome": "success"
}These schemas describe the JSON data stored for each row within a 'Chunk' file available via DataDriver. The files will be stored in NDJSON format so each line in the file will be a JSON object that adheres to one of these schemas. Let us know if you don't see the data you need here so we can add it.
| accessorials required | Array of strings (Accessorials) Default: [] Additional services requested for the shipment Examples, non-exhaustive: "drydraught", "hazardous", "insurance", "liftgate", "lowboy", "pallet jack", "plated trailer", "safe transport of food", "stepdeck", "straps", "tanker endorsement", "tarps", "team drivers" |
required | Array of objects List of bids placed for this quote |
required | object Default: {} Prices determined for the quote |
| equipment required | string (Equipment) An equipment type that could be used for delivering the shipment Examples, non-exhaustive: "van", "reefer", "flatbed" |
| ingested_at required | string <date-time> (DateTime) The Date/Time the quote was ingested by Bitfreighter as an ISO8601 formatted string. |
| quote_id required | string A Bitfreighter identifier for this quote. |
required | Array of objects List of statuses |
required | Array of objects (RateRequestStop) An array of stops for the shipment |
| event_id | string A unique sequential identifier for the event. |
| external_load_reference_id | string or null A unique identifier for the load. |
| external_reference_id | string or null A unique identifier of the request. |
| replaced_by_quote_id | string or null This field may contain the ID of a quote that represents an updated version of this quote. For example, some LiveQuote integrations publish updates to auctions or loads. In this context, Bitfreighter creates a new quote for the new information and updates the origin quote with the new quote's ID in the this field. |
object or null The Shipper Profile associated with this quote. | |
object or null The total distance of the shipment | |
object or null The total weight of the shipment | |
| won_at | string or null <date-time> (DateTime) The Date/Time the quote was won as an ISO8601 formatted string. This will be null if the Quote has not been won. |
{- "accessorials": [
- "hazardous"
], - "bids": [
- {
- "all_in": 3347.09,
- "amount": 2735,
- "bid_at": "2024-07-09T17:18:56+0000",
- "placed_by": "Automated",
- "source": "automated"
}
], - "costs": {
- "base": 2789.24,
- "determination": 2735,
- "determination_type": "line_haul",
- "fuel": 612.27,
- "markup": 557.85
}, - "equipment": "flatbed",
- "event_id": "01J2C82S0R00000000000004AV",
- "external_load_reference_id": "7c3e24a6-4355-4fe5-8748-1939bc7f296e",
- "external_reference_id": "a86a2da1-5758-44ba-9681-2db1aed1444f",
- "ingested_at": "2024-07-09T17:18:55+0000",
- "quote_id": "4443",
- "shipper_profile": {
- "id": "18",
- "meta": {
- "shipper_code_id": "ABC123"
}, - "name": "Flying Rs"
}, - "statuses": [
- {
- "inserted_at": "2024-07-09T15:10:31+0000",
- "name": "auction_won"
}, - {
- "inserted_at": "2024-07-09T17:18:56+0000",
- "name": "active_bid_in_progress"
}
], - "stops": [
- {
- "location": {
- "address": {
- "city": "Los Angeles",
- "country": "USA",
- "line1": null,
- "postal_code": "90001",
- "state": "CA"
}, - "latitude": 34.05223,
- "longitude": -118.24368
}, - "reason": "load",
- "scheduled_at": "2024-07-10T13:00:00+0000",
- "sequence_number": 1
}, - {
- "location": {
- "address": {
- "city": "Austin",
- "country": "USA",
- "line1": null,
- "postal_code": "78748",
- "state": "TX"
}, - "latitude": 30.30116,
- "longitude": -97.7527
}, - "reason": "unload",
- "scheduled_at": "2024-07-13T13:00:00+0000",
- "sequence_number": 2
}
], - "total_distance": {
- "unit_of_measure": "mi",
- "value": 1361
}, - "total_weight": {
- "unit_of_measure": "lbs",
- "value": 24000
}, - "won_at": "2024-07-09T15:10:31+0000"
}