Before you begin
This API connects to XFM's live freight system. Ensure that all fields are mapped correctly and all required data is filled in before sending a request. Incomplete or incorrectly mapped data can lead to unexpected results.
01
Getting started
Every request runs over HTTPS and carries a single authorisation header built from your XFM-issued account number and Auth Token, separated by a pipe. There are no unauthenticated endpoints.
| Header | Value |
|---|---|
Authorization | AccountNumber|AuthToken |
Getting your credentials
Your account number and Auth Token are issued by XFM. To request them, contact the XFM team and we'll set you up with the credentials for your integration.
Need credentials? Reach out to your XFM contact, or call 13000 XPRESS (97737), to request an Auth Token for your account.
Keep your key secure. These credentials can create and modify live freight. Store them safely, never expose them in client-side code, and contact XFM if a key may have been compromised so it can be reissued.
All calls go to https://api.transvirtual.com.au. The default response format is JSON; XML and JSONP (for cross-domain requests) are also supported. Every response returns a consistent envelope.
Response envelope
| Field | Meaning |
|---|---|
StatusCode | The outcome of the request. If it is not 200, only StatusCode and StatusText are guaranteed to be meaningful. |
StatusText | Human-readable outcome — log it for troubleshooting. |
TransactionID | Always returned, even on errors. Quote it when contacting XFM support. |
Data | Present on all 200 responses, but may be empty. |
Supported formats
| Format | Notes |
|---|---|
| JSON | Default response format. |
| XML | Supported alternative. |
| JSONP | For cross-domain requests via a callback method. |
02
Consignments
Supports POST (insert), PUT (update) and DELETE. Only SenderName and ReceiverName are strictly required for a POST, but a complete address is needed for freight to move correctly.
Request properties (POST & PUT)
| Property | Required | Description |
|---|---|---|
UniqueId | Recommended | Your system's unique key for this consignment. Max 200. |
Number | Optional | Consignment / tracking number. Max 100. |
Date | Optional | Consignment date. Format yyyy-MM-dd. |
SenderName | Required | Sender name. Max 100. |
SenderAddress | Recommended | Sender address line 1. Max 100. |
SenderSuburb | Recommended | Sender suburb (must exist). Max 60. |
SenderPostcode | Recommended | Sender postcode. Max 20. |
SenderState | Recommended | Sender state. Max 30. |
ReceiverName | Required | Receiver name. Max 100. |
ReceiverAddress | Recommended | Receiver address line 1. Max 100. |
ReceiverSuburb | Recommended | Receiver suburb (must exist). Max 60. |
ReceiverPostcode | Recommended | Receiver postcode. Max 20. |
ReceiverState | Recommended | Receiver state. Max 30. |
SpecialInstructions | Optional | Delivery instructions shown to the driver on mobile. Max 500. |
ConsignmentPickupSpecialInstructions | Optional | Pickup instructions shown to the driver on mobile. Max 500. |
ConsignmentSenderContact | Optional | Sender contact name. Max 100. |
ConsignmentSenderPhone | Optional | Sender contact phone. Max 50. |
ConsignmentReceiverContact | Optional | Receiver contact name. Max 100. |
ConsignmentReceiverPhone | Optional | Receiver contact phone. Max 50. |
SenderReference | Optional | Sender reference. Max 100. |
ReceiverReference | Optional | Receiver reference. Max 100. |
SenderEmail | Optional | Sender tracking email (multiple separated by |). Max 500. |
ReceiverEmail | Optional | Receiver tracking email (multiple separated by |). Max 500. |
SignatureRequired | Optional | y or n. |
PickupRequest | Optional | y if pickup required. POST only. |
ConsignmentOtherReferences | Optional | Extra references separated by |. Max 500. |
ConsignmentBookingDateTime | Optional | Delivery booking time. Format yyyy-MM-dd HH:mm or ISO-8601. |
ConsignmentPickupBookingTime | Optional | Pickup booking time. Format yyyy-MM-dd HH:mm or ISO-8601. |
ConsignmentServiceType | Optional | Service level. Max 50. |
ConsignmentAuthToLeaveNote | Optional | Authority-to-leave note — appended to delivery special instructions. |
AdditionalServiceList | Optional | Additional services, separated with |. |
DangerousGoodsNotes | Conditional | Any value flags the consignment as dangerous goods. Max 200. |
ReturnPdfLabels | Optional | 'y' to include Base64 PDF labels in the response. |
ReturnPdfConsignment | Optional | 'y' to include the Base64 PDF consignment in the response. |
Suburb fields. Always supply a complete, valid suburb for both the sender and receiver. If a suburb is missing or unrecognised, the system may apply a default value, which can affect where freight is routed.
POST response properties
| Property | Required | Description |
|---|---|---|
Id | Optional | TransVirtual Id of the created consignment. |
PdfLabels | Optional | PDF labels, Base64 encoded (if requested). |
PdfConsignment | Optional | PDF consignment, Base64 encoded (if requested). |
PUT — additional properties
| Property | Required | Description |
|---|---|---|
Id | Optional | TransVirtual Id. Either Id or UniqueId required for a PUT. |
NewUniqueId | Optional | Override the existing UniqueId. Max 200. |
DELETE — request properties
| Property | Required | Description |
|---|---|---|
Id | Optional | TransVirtual Id. Required if UniqueId not provided. |
UniqueId | Optional | Your unique key. Required if Id not provided. |
Error codes
| Code | Description |
|---|---|
1001 | Invalid TransVirtual number supplied |
1002 | Unknown validation error |
1003 | Consignment already exists |
1004 | Unknown error |
1005 | Sender suburb does not exist |
1006 | Receiver suburb does not exist |
1007 | No line items provided |
1008 | Consignment number missing |
1009 | Date field missing |
1010 | Sender name missing |
1011 | Receiver name missing |
1018 | API consignment creation disabled |
1024 | Consignment is cancelled |
1028 | Customer has disabled API consignment creation |
POST only. Adds an additional service to an existing consignment. Must be enabled in API system settings. Each service can only be added once per consignment.
Request properties
| Property | Required | Description |
|---|---|---|
ConsignmentNumber | Optional | Required if Id or UniqueId not provided. |
Id | Optional | Required if UniqueId or ConsignmentNumber not provided. |
UniqueId | Optional | Required if Id or ConsignmentNumber not provided. |
AdditionalServiceName | Optional | Name of the additional service. |
UserNotes | Optional | Optional driver / user notes. |
AdditionalServiceChargeRateOverride | Optional | Optional charge override. |
AdditionalServiceQtyOverride | Optional | Optional quantity (defaults to 1). |
AdditionalServicePickupRelated | Optional | Relates to pickup activity (default false). |
AdditionalServiceApprovalRequired | Optional | Requires admin approval (default false). |
AdditionalServiceCreatedByOptional | Optional | Name of the creator. |
Error codes
| Code | Description |
|---|---|
1501 | Unknown error |
1502 | Missing consignment link |
1503 | More than 1 consignment |
1504 | Additional service not found |
1505 | Missing service name |
1506 | Service already exists |
POST only. Updates a single field on an existing consignment. Must be enabled in API system settings.
Request properties
| Property | Required | Description |
|---|---|---|
ConsignmentNumber | Optional | Consignment number. Required if Id, Barcode or UniqueId not provided. |
Barcode | Optional | Item barcode. Required if Id, UniqueId or ConsignmentNumber not provided. |
Id | Optional | TransVirtual Id. Required if UniqueId, Barcode or ConsignmentNumber not provided. |
UniqueId | Optional | Your unique key. Required if Id, Barcode or ConsignmentNumber not provided. |
Field | Optional | The field name to update. |
Value | Optional | The new value for the field. |
DateTime formatting
| Type | Format |
|---|---|
| Local | yyyy-MM-dd HH:mm e.g. 2016-05-10 10:30 |
| UTC / ISO-8601 | yyyy-MM-ddTHH:mm±HH:mm e.g. 2016-05-10T10:30+10:00 |
Error codes
| Code | Description |
|---|---|
1401 | Missing field to be updated |
1402 | Unknown error |
1403 | Missing update value |
1404 | Missing valid consignment link number |
1405 | More than 1 consignment discovered |
PUT only. Upload general consignment images. The consignment must already exist.
Request properties
| Property | Required | Description |
|---|---|---|
ConsignmentNumber | Optional | Required if UniqueId or Id not provided. |
Id | Optional | Required if ConsignmentNumber or UniqueId not provided. |
UniqueId | Optional | Required if ConsignmentNumber or Id not provided. |
Base64Image | Required | Base64 encoded image. |
ImageType | Optional | Pod, DamagePhoto, ConsignmentPhoto, LeftAsInstructedPhoto, PaperPodPhoto. |
DateTime | Optional | Image datetime. Format yyyy-MM-dd HH:mm or ISO-8601. |
ImageBy | Optional | User that created the image. |
UniqueIdImage | Optional | Your unique ID for this image. |
PickupRelated | Optional | Image relates to the pickup component. |
Error codes
| Code | Description |
|---|---|
2150 | Consignment missing |
2151 | Image missing |
2152 | Failed Base64 image conversion |
POST only. Inserts additional item rows against an existing consignment on an open customer manifest.
Request properties
| Property | Required | Description |
|---|---|---|
Number | Optional | Consignment number. Max 100. |
UniqueId | Optional | Your unique key. Max 200. |
IdConsignment | Optional | TransVirtual consignment Id. |
CustomerName | Required | Customer name. Max 200. |
CustomerCode | Required | Customer account code. Max 20. |
ReturnAllPdfLabels | Optional | 'y' to include all labels in the response. |
ReturnNewPdfLabels | Optional | 'y' to include new labels only in the response. |
ReturnPdfConsignment | Optional | 'y' to include the consignment PDF in the response. |
Error codes
| Code | Description |
|---|---|
1401 | Missing item data |
1402 | Unknown error |
1403 | Missing consignment link |
1404 | More than 1 consignment |
1405 | Customer manifest already closed |
PUT only. Upload POD images or signatures. The consignment must already exist.
Request properties
| Property | Required | Description |
|---|---|---|
ConsignmentNumber | Optional | Required if UniqueId or Id not provided. |
Id | Optional | Required if ConsignmentNumber or UniqueId not provided. |
UniqueId | Optional | Required if ConsignmentNumber or Id not provided. |
PodType | Optional | Complete, Rejected, LeftAsInstructed, Short. |
Base64PodImage | Optional | Base64 encoded full POD image. |
Base64SignatureImage | Optional | Base64 encoded signature image. |
DateTime | Optional | POD datetime. Format yyyy-MM-dd HH:mm or ISO-8601. |
ReceivedBy | Optional | Person who signed. |
DriverName | Optional | Driver name. |
DriverNotes | Optional | Driver notes. |
RejectedNotes | Optional | Notes for rejected consignments. |
PodQtySignedFor | Optional | Quantity signed for. |
UniqueIdPod | Optional | Your unique ID for this POD. |
PickupRelated | Optional | POD relates to the pickup component. |
Error codes
| Code | Description |
|---|---|
2100 | Consignment missing |
2101 | Image missing |
2102 | Failed Base64 POD image conversion |
2103 | Failed Base64 signature conversion |
2104 | POD type missing |
POST only. Returns PDF labels and/or the consignment document.
Request properties
| Property | Required | Description |
|---|---|---|
ConsignmentNumber | Optional | Required if Barcode not provided. |
Barcode | Optional | Item barcode. Required if ConsignmentNumber not provided. |
IncludeLabelsPdf | Optional | If true, include the labels PDF in the response. |
IncludeConsignmentPdf | Optional | If true, include the consignment PDF in the response. |
Error codes
| Code | Description |
|---|---|
1301 | Does not exist |
1302 | No values provided |
POST only. Returns static consignment data (sender, receiver, items). Does not return live status information.
Request properties
| Property | Required | Description |
|---|---|---|
ConsignmentNumber | Optional | Required if Barcode not provided. |
Barcode | Optional | Item barcode. Required if ConsignmentNumber not provided. |
IncludeLabelsPdf | Optional | If true, include the labels PDF in the response. |
IncludeConsignmentPdf | Optional | If true, include the consignment PDF in the response. |
Key response properties
| Property | Required | Description |
|---|---|---|
Number | Optional | Consignment / tracking number. |
CustomerName | Optional | Customer name. |
SenderName | Optional | Sender name. |
SenderAddress | Optional | Sender address line 1. |
SenderSuburb | Optional | Sender suburb. |
SenderPostcode | Optional | Sender postcode. |
SenderState | Optional | Sender state. |
ReceiverName | Optional | Receiver name. |
ReceiverAddress | Optional | Receiver address line 1. |
ReceiverSuburb | Optional | Receiver suburb. |
ReceiverPostcode | Optional | Receiver postcode. |
ReceiverState | Optional | Receiver state. |
SpecialInstructions | Optional | Current delivery instructions. Max 500. |
ConsignmentPickupSpecialInstructions | Optional | Current pickup instructions. Max 500. |
SenderReference | Optional | Sender reference. |
ReceiverReference | Optional | Receiver reference. |
ConsignmentOtherReferences | Optional | Other references separated by |. |
ConsignmentBookingReference | Optional | Delivery booking reference. |
ServiceType | Optional | Service level. |
LabelsPdf | Optional | Base64 labels PDF (if requested). |
ConsignmentPdf | Optional | Base64 consignment PDF (if requested). |
Error codes
| Code | Description |
|---|---|
1301 | Does not exist |
1302 | No values provided |
POST (query status) and PUT (update status).
POST — query status request
| Property | Required | Description |
|---|---|---|
Number | Required | Consignment number. |
Id | Optional | TransVirtual Id. |
UniqueId | Optional | Your unique key. |
POST — response properties
| Property | Required | Description |
|---|---|---|
Id | Optional | TransVirtual Id. |
UniqueId | Optional | Your unique key. |
ConsignmentNumber | Optional | Consignment number. |
Status | Optional | Current status. |
StatusDateTime | Optional | Status datetime (UTC). Format yyyy-MM-dd HH:mm. |
GeoLatitude | Optional | Last known latitude. |
GeoLongitude | Optional | Last known longitude. |
PUT — update status request
| Property | Required | Description |
|---|---|---|
ConsignmentNumber | Optional | Required if UniqueId or Id not provided. |
UniqueId | Optional | Required if ConsignmentNumber or Id not provided. |
Id | Optional | Required if ConsignmentNumber or UniqueId not provided. |
DateTime | Required | Status change datetime. Format yyyy-MM-dd HH:mm or ISO-8601. |
Status | Required | Status value: InTransit, InDepot, OnDelivery, Delivered. |
Comment | Optional | Driver notes / comments. |
CreatedBy | Optional | Driver / staff member name. |
PickupRelated | Optional | Set if the status relates to the pickup component. |
Error codes
| Code | Description |
|---|---|
2050 | Missing status |
2051 | Missing consignment link |
2052 | More than 1 result |
2053 | Does not exist |
03
Pricing & reference
POST only. Returns one or more price estimates for a given route. This is an estimate only, not a quote.
Request properties
| Property | Required | Description |
|---|---|---|
SenderSuburb | Required | Suburb sending from. |
SenderState | Required | State sending from. |
SenderPostcode | Required | Postcode sending from. |
ReceiverSuburb | Required | Suburb sending to. |
ReceiverState | Required | State sending to. |
ReceiverPostcode | Required | Postcode sending to. |
CustomerName | Required | Customer name (if CustomerCode not provided). Max 200. |
CustomerCode | Required | Customer code (if CustomerName not provided). Max 20. |
ServiceType | Optional | Service level (may be required). Contact XFM for valid values. |
DangerousGoods | Optional | Set to 'Y' if dangerous goods. |
DimensionsUOM | Optional | mm, cm, m, inc, ft, yd. Max 3. |
WeightUOM | Optional | kgs, oz, lb, ton, tonne. Max 5. |
SenderIsResidential | Optional | 'Y' if residential. Max 1. |
ReceiverIsResidential | Optional | 'Y' if residential. Max 1. |
AdditionalServiceList | Optional | Additional services, separated with |. |
Estimate only. Prices returned are indicative, not a binding quote. Present them to end-users as estimates.
Error codes
| Code | Description |
|---|---|
1001 | Invalid sender suburb |
1002 | Invalid receiver suburb |
1003 | Invalid customer account |
1006 | Invalid weight (must be > 0) |
1007 | Invalid dimensions (must be > 0) |
1011 | No price found — contact office |
POST only. Inserts a new suburb. Recommended to use only when a Consignment POST/PUT returns error 1005 or 1006 (suburb does not exist).
Request properties
| Property | Required | Description |
|---|---|---|
Suburb | Required | Suburb name. |
Postcode | Required | Corresponding postcode. |
State | Optional | State / province (highly recommended). |
Country | Required | Full country name. |
Error codes
| Code | Description |
|---|---|
1101 | Suburb already exists |
1102 | Unknown error |
1103 | Suburb field missing |
1104 | Postcode field missing |
1105 | Country field missing |
1106 | Invalid country name |
04
Getting help
This guide covers a curated subset of the platform. If your integration needs something you can't find here, get in touch before improvising — we're happy to help you get it right.
Talk to us before going live. Share your integration plan and a couple of test consignment numbers with your XFM contact and we'll confirm everything is routing correctly. Always quote the
TransactionID from any failed response.