/Api/Consignment

The consignment API method allows HTTP Post, HTTP Put and HTTP Delete actions. The HTTP Post should be used for all fresh inserts. HTTP Put should be used for all updates of field values and HTTP Delete to be used for any consignment deletes.

HTTP Post

Allows you to insert a new consignment into your TransVirtual database.

Request Properties (Shared Post and Put)

The request properties that are shared between HTTP Post and HTTP Put for your request data

Property Name Required Description
ReturnPdfLabels Include PDF of Labels in response (Base64Encoded) - 'y' to include
ReturnPdfConsignment Include PDF of Consignment in response (Base64Encoded) - 'y' to include
UniqueId A unique key value that your system will identify with the consignment. Max length: 200
NewUniqueId If you require to override your unique key (only valid for 'put' requests). Max length: 200
Number Consignment number (also the tracking number). Max length: 100
Date The date of the consignment. Format: yyyy-MM-dd
CustomerName The customer name of this consignment (can map to your customer name). Max length: 200
CustomerIdentifier A extra identifier for the original customer (can be different to your customer name). Max length: 200
CustomerCode Used to attempt to link to one of your TransVirtual customers. Max length: 20
SenderAutoCompleteAddress Ability to send the address code in place of full address details. If valid code, it will override all sender details. Max length: 50
ReceiverAutoCompleteAddress Ability to send the address code in place of full address details. If valid code, it will override all receiver details. Max length: 50
SenderName Yes The senders name. Max length: 100
SenderName2 The 2nd senders name. Max length: 50
SenderAddress The senders address (line 1). Max length: 100
SenderAddress2 The senders address (line 2). Max length: 100
SenderSuburb The senders suburb. Note, if suburb does not exist it will return error and the suburb will need to be created. Max length: 60
SenderPostcode The senders postcode (used with sender suburb to find existing suburb). Max length: 20
SenderState The senders state/province (used with sender suburb to find existing suburb). Max length: 30
ReceiverName Yes The receivers name. Max length: 100
ReceiverName2 The 2nd receivers name. Max length: 50
ReceiverAddress The receivers address (line 1). Max length: 100
ReceiverAddress2 The receivers address (line 2). Max length: 100
ReceiverSuburb The receivers suburb. Note, if suburb does not exist it will return error and the suburb will need to be created. Max length: 60
ReceiverPostcode The receivers postcode (used with receiver suburb to find existing suburb). Max length: 20
ReceiverState The receivers state/province (used with receiver suburb to find existing suburb). Max length: 30
SenderReference A senders reference for the consignment. Max length: 100
ReceiverReference A receivers reference for the consignment. Max length: 100
SenderEmail A sender email address that will be sent tracking info (multi use | separator). Max length: 500
ReceiverEmail A receiver email address that will be sent tracking info (multi use | separator). Max length: 500
OnforwardName An onforward company name used for labels/consignments etc. Max length: 100
OnforwardAddress1 An onforward address line 1 used for labels/consignments etc. Max length: 100
OnforwardSuburb An onforward suburb used for labels/consignments etc. Max length: 100
OnforwardPostcode An onforward postcode used for labels/consignments etc. Max length: 20
OnforwardState An onforward state used for labels/consignments etc. Max length: 30
OnforwardAddress2 An onforward address line 2 used for labels/consignments etc. Max length: 100
OnforwardContactName An onforward contact name used for labels/consignments etc. Max length: 100
OnforwardContactPhone An onforward phone number used for labels/consignments etc. Max length: 50
OnforwardContactEmail An onforward email address used for labels/consignments etc (multi use | separator). Max length: 100
AdditionalServiceHandlingQty Additional Service qty for a handling fee. Integer
AdditionalServicesRequired Additional Service required. Contact office for available codes and seperate with |. Max length: 500
SpecialInstructions Instructions given for the delivery, and will appear on mobile devices for delivery driver. Max length: 500
AutoAssignAgentEmployee Only use if advised to do so. This will assign consignment to relavent agent or driver. Max length: 100
ConsignmentSenderContact Senders contact name, will assist with pickup details. Max length: 100
ConsignmentSenderPhone Senders contact number, will assist with pickup details. Max length: 50
ConsignmentReceiverContact Receivers contact name, will assist with delivery details. Max length: 100
ConsignmentReceiverPhone Receivers contact number, will assist with delivery details. Max length: 50
DangerousGoodsNotes Dangerous goods notes (Hazardous material). If this field has a value, it will indicate the consignment contains dangerous goods, Max length: 200
DangerousGoodsUNNumber Dangerous goods UN Number (Hazardous material). If this field has a value, it will be used with Class, Packaging Group and Subrisk to find exact lookup, Max length: 50
DangerousGoodsClass Dangerous goods Class (Hazardous material). If this field has a value, it will be used with UN Number, Packaging Group and Subrisk to find exact lookup, Max length: 50
DangerousGoodsPackagingGroup Dangerous goods Packaging Group (Hazardous material). If this field has a value, it will be used with Class, UN Number and Subrisk to find exact lookup, Max length: 50
DangerousGoodsSubRisk Dangerous goods SubRisk (Hazardous material). If this field has a value, it will be used with Class, UN Number and Packaging Group to find exact lookup, Max length: 150
ConsignmentLengthUom Values can only be m, cm, mm, inc, ft, yd
ConsignmentPickupSpecialInstructions Instructions given for the pickup instructions, will appear on mobile devices for pickup driver. Max length: 500
PickupRequest If the consignment requires a pickup, value should be y. Only available in Post
SignatureRequired If the consignment requires a signature, value should be y or n
VipConsignment If the consignment requires special attention, value should be y (contact office before use)
IsPointToPoint If the consignment is point to point (not returned to depot), value should be y
ConsignmentSenderIsResidential If sender is residential address, value should be y
ConsignmentReceiverIsResidential If receiver is residential address, value should be y
ConsignmentOtherReferences Place all remaining references in this field separated by |. Max length: 500
ConsignmentOtherReferences2 Place all remaining references in this field separated by | (2nd). Max length: 500
ConsignmentBookingReference References the driver will require on pickup. Max length: 500
ConsignmentPickupBookingReference References the driver will require on delivery. Max length: 500
ConsignmentTotalWeightOverride Override total weight display - ignores the summation of the item weight values. Decimal
ConsignmentPickupBookingTime If a booking time is known for the pickup component Format: yyyy-MM-dd HH:mm (for Local Ex: 2016-05-10 10:30) or yyyy-MM-ddTHH:mm+Z (for UTC Ex: 2016-05-10T10:30+10:00)
ConsignmentBookingDateTime If a booking time is known for the delivery component Format: yyyy-MM-dd HH:mm (for Local Ex: 2016-05-10 10:30) or yyyy-MM-ddTHH:mm+Z (for UTC Ex: 2016-05-10T10:30+10:00)
ConsignmentBookingDateTimeTo If a booking time range is known for the delivery component Format: HH:mm (for local Ex: 10:30) or HH:mm+Z (for UTC Ex: 10:30+10:00)
ConsignmentPickupBookingTimeTo If a booking time range is known for the pickup component Format: HH:mm (for local Ex: 10:30) or HH:mm+Z (for UTC Ex: 10:30+10:00)
ConsolidationManifestNumber If set will generate a general consolidation manifest and add auto add all items to scanned 'On Delivery' manifest so driver can scan just the manifest number to load their vehicle. Max length: 50
ConsignmentServiceType The service level that the customer is expecting. Max length: 50
ConsignmentServiceTypeExtension The service level that the customer is expecting extended, only use if directed. Max length: 50
ConsignmentApiImportTag A tag that can be used to assist with generating advanced export rules. Max length: 50
ConsignmentPickupCloseTime Close time of the pickup location Format: HH:mm (for local Ex: 10:30) or HH:mm+Z (for UTC Ex: 10:30+10:00)
ConsignmentDeliveryCloseTime Close time of the delivery location Format: HH:mm (for local Ex: 10:30) or HH:mm+Z (for UTC Ex: 10:30+10:00)
ConsignExpectedDeliveryDate If expected delivery date is known, Format: yyyy-MM-dd HH:mm (for Local Ex: 2016-05-10 10:30) or yyyy-MM-ddTHH:mm+Z (for UTC Ex: 2016-05-10T10:30+10:00)
ConsignExpectedFirstScanDate If expected first scan date is known, Format: yyyy-MM-dd HH:mm (for Local Ex: 2016-05-10 10:30) or yyyy-MM-ddTHH:mm+Z (for UTC Ex: 2016-05-10T10:30+10:00)
ConsignmentBaseCustomerPriceOverrideString Override base customer price for the consignment - if set, price calculations are ignored. Decimal
EquipmentType1Count Equipment Count 1 - ensure both parties understand which equipment type this refers to
EquipmentType2Count Equipment Count 2 - ensure both parties understand which equipment type this refers to
EquipmentType3Count Equipment Count 3 - ensure both parties understand which equipment type this refers to
EquipmentType4Count Equipment Count 4 - ensure both parties understand which equipment type this refers to
EquipmentType5Count Equipment Count 5 - ensure both parties understand which equipment type this refers to
ConsignmentAuthToLeaveNote Authority to Leave Note, note displayed to driver and also appended to delivery special instructions.
AdditionalServiceList Additional Services Requested - contact office for list of valid values, separate with |
ConsignmentOverrideCustomerEmail Optional, only used if instructed to do so. Max length: 200
ConsignmentThirdPartyChargeCode Optional, only used if instructed to do so, third party charge code. Max length: 50

Property Name Required Description
RemoteRowUniqueId Remote Unique Row ID - used in API ConsignmentItem Post. Max length: 200
Qty Yes The number of items in this row. Integer
QtyDecimal The number of items in this row. Decimal
Description Yes The description given to this row of items. Max length: 200
ItemContentsDescription Yes The freight contents description given to this row of items. Max length: 200
ItemRowChargeQty Allows you to override the charge qty only
Weight The total weight of this row of items. Integer
Length The length of each (or total) of the row of items - Used with CubicQty field. Decimal
Width The Width of each (or total) of the row of items - Used with CubicQty field. Decimal
Height The Height of each (or total) of the row of items - Used with CubicQty field. Decimal
CubicQty The qty to multiply with the Length/Width/Height to calculate total cubic. Decimal
CubicTotalFallback The item row total cubic used as fallback only if no dimensions provided. Decimal
CubicTotalConsignment The item row total cubic used as fallback only if no dimensions provided. Will not be summed if item rows are combined. Decimal
Reference A reference number given to this row of items. Max length: 50
StockCode A stock code for this row of items. Max length: 50
Uom Values can only be kgs, oz, lb, ton, tonne
DangerousGoodsNotes Dangerous Goods notes (Hazard material) - Item Level. If this field has a value, it will indicate the consignment contains dangerous goods, Max length: 200
DangerousGoodsUNNumber Dangerous Goods UN Number (Hazard material) - Item Level. If this field has a value, it will be used with Class, Packaging Group and Subrisk to find exact lookup, Max length: 50
DangerousGoodsClass Dangerous Goods Class (Hazard material) - Item Level. If this field has a value, it will be used with UN Number, Packaging Group and Subrisk to find exact lookup, Max length: 50
DangerousGoodsPackagingGroup Dangerous goods Packaging Group (Hazard material) - Item Level. If this field has a value, it will be used with Class, UN Number and Subrisk to find exact lookup, Max length: 50
DangerousGoodsSubRisk Dangerous Goods SubRisk (Hazard material) - Item Level. If this field has a value, it will be used with Class, UN Number and Packaging Group to find exact lookup, Max length: 150
DangerousGoodsUNNumber2 2nd Dangerous Goods UN Number (Hazard material) - Item Level. If this field has a value, it will be used with Class, Packaging Group and Subrisk to find exact lookup, Max length: 50
DangerousGoodsClass2 2nd Dangerous Goods Class (Hazard material) - Item Level. If this field has a value, it will be used with UN Number, Packaging Group and Subrisk to find exact lookup, Max length: 50
DangerousGoodsPackagingGroup2 2nd Dangerous Goods Packaging Group (Hazard material) - Item Level. If this field has a value, it will be used with Class, UN Number and Subrisk to find exact lookup, Max length: 50
DangerousGoodsSubRisk2 2nd Dangerous Goods SubRisk (Hazard material) - Item Level. If this field has a value, it will be used with Class, UN Number and Packaging Group to find exact lookup, Max length: 150
DangerousGoodsContainerType 2nd Dangerous Goods Container Type (Hazard material) - Item Level. Optional user along side UN Number, Max length: 200
DangerousGoodsNumberOfContainers Dangerous Goods Number of Containers (Hazard material) - Item Level. Optional user along side UN Number, Max length: 50
DangerousGoodsAggregateWeight Dangerous Goods Aggregate Weight (Hazard material) - Item Level. Optional user along side UN Number, Max length: 50
DangerousGoodsContainerType2 2nd Dangerous Goods Container Type (Hazard material) - Item Level. Optional user along side UN Number, Max length: 200
DangerousGoodsNumberOfContainers2 2nd Dangerous Goods Number of Containers (Hazard material) - Item Level. Optional user along side UN Number, Max length: 50
DangerousGoodsAggregateWeight2 2nd Dangerous Goods Aggregate Weight (Hazard material) - Item Level. Optional user along side UN Number, Max length: 50

Property Name Required Description
Barcode Yes The article barcode of the item
AlternateBarcode An alternate article barcode of the item - only use if advised

Response Properties

The response properties for the HTTP Post found within the Data field of the reponse

Property Name Description
Id The TransVirtual Id of the consignment created
PdfLabels PDF of Labels (Base64Encoded)
PdfConsignment PDF of Consignment (Base64Encoded)

Example Post

Request (json)
Response (json)

HTTP Put

Allows you to modify the properties of a consignment.

Request Properties (in addition to HTTP Post request properties)

The additional request properties that are available for HTTP Put. Note, either Id or UniqueId is a required field for all HTTP Put requests. If neither provided or no match found in the TransVirtual API, a error will be returned.

Property Name Required Description
Id The TransVirtual Id of the consignment

Response Properties

The Data field of the response does not contain any data

Example Put

Request (json)
Response (json)

HTTP Delete

Allows you to delete a consignment from your TransVirtual database.

Request Properties

The request properties that are available for your HTTP Delete calls.

Property Name Required Description
Id The TransVirtual Id of the consignment. This must be provided in the absence of UniqueId.
UniqueId A unique key value that your system will identify with the consignment. This must be provided in the absence of Id.

Response Properties

The Data field of the response does not contain any data

Example Delete

Request (json)
Response (json)

Error Codes

Error Code Description
1001 Invalid TransVirtual number supplied
1002 Unknown validation error - report if this persists
1003 Consignment already exists
1004 Unknown error - report if this persists
1005 Sender suburb does not exist, please Post to the Suburb API to continue
1006 Receiver suburb does not exist, please Post to the Suburb API to continue
1007 No line items have been provided
1008 Consignment number field missing
1009 Date field missing
1010 Sender name field missing
1011 Receiver name field missing
1012 Line item quantity field missing
1013 Line item description field missing
1014 Barcode field provided but is empty. Do not provide field if not relavent
1015 Consignment date field not formated correctly
1016 Sender postcode field is missing
1017 Receiver postcode field missing
1018 Creation of consignments via the API has been disabled. If this is in error, please contact us
1019 Customer Code field missing
1020 Pickup Area not serviced
1021 Delivery Area not serviced
1022 Weights are missing
1023 Dimensions are missing
1024 The consignment is cancelled
1025 The consignment would exceed the service level max quantity
1026 The consignment would exceed the service level max item weight
1027 The consignment service level does not include Dangerous Goods