Appearance
Common Data Structures
There are several data structures involved when using the API (properties marked with * are mandatory).
Instruction
A generic structure for defining instructions for pickup, collection, delivery, etc. A shipment can contain zero or more instructions of different types.
| Property | * | Type | Description |
|---|---|---|---|
| From | DateTime | A date/time instance (instruction valid from). | |
| To | DateTime | A date/time instance (instruction valid to). | |
| Comments | *1 | Text | Instruction comments. |
Warning
*1
Mandatory only when a normal shipment request is made. Not mandatory for shipping cost calculation request. See Shipment Cost Calculation section for details.
Currency Value
A structure used to define amounts along with the relevant currency.
| Property | * | Type | Description |
|---|---|---|---|
| CurrencyCode | Text | 3-letter ISO-4217 currency code. “EUR” (default). | |
| Value | * | Decimal | The currency amount. |
Weight/Volume
A structure used to define a weight or volume value.
| Property | * | Type | Description |
|---|---|---|---|
| UnitType | Enum | The unit type. Valid values are: “kg” (default), “lb”, “oz”, “mg”, “g”, “gal”, “mL”, “L”, “t”. | |
| Value | * | Decimal | The actual weight or volume value. |
Dimensions
A structure used to define the dimensions of an object.
| Property | * | Type | Description |
|---|---|---|---|
| UnitType | Enum | The unit type of each dimension. Valid values are: “cm” (default), “in”, “ft”, “yd”, “mm”, “m”. | |
| Length | * | Decimal | The actual length of an object. |
| Width | * | Decimal | The actual width of an object. |
| Height | * | Decimal | The actual height of an object. |
COD
A structure used to define the details when a shipment has cash on delivery.
| Property | * | Type | Description |
|---|---|---|---|
| CodType | Text | The type of the COD. Valid values are: “Cash” (default), “Check”, “Bill”, “MoneyCollection”, “Other”. | |
| Amount | * | Currency Value | The actual amount of the COD. |
| Date | Date | COD date (i.e. the date of the check). | |
| Comments | Text | COD comments. | |
| InvoiceNo | Text | Related invoice number. | |
| ReturnTo | Enum | The beneficiary of the cash. Valid values are: “Requestor” (default), “Shipper”, “Consignee”, “Payee”. | |
| ReturnToAccountNumber | Text | The system account number of the cash beneficiary. Used in cases when we need to return the COD amount to a specific account number. |
Package
Package structure is used to define a unique package item of a shipment. A shipment can contain one or more package items.
| Property | * | Type | Description |
|---|---|---|---|
| Code | Text | The AWB code of the item. | |
| PackageType | *1 | Text | The code/name of the package type. i.e. “Letter”, “SmallBox” etc. Package type codes should be agreed with the carrier. |
| References | Text(array) | An array or free text references. The values are used in queries against shipments/items. | |
| Description | Text | A description of the item. | |
| IsDocs | Boolean | “true” if the package contains documents only, “false” otherwise. | |
| IsDangerous | Boolean | “true” if the content is dangerous,“false” otherwise. | |
| IsFragile | Boolean | “true” if the content is fragile,“false” otherwise. | |
| DeclaredValue | CurrencyValue | The declared amount of the content. | |
| Weight | *1 | Weight/Volume | The weight or volume of the package. |
| Dimensions | *1 | Dimensions | The dimensions of the package. |
Warning
*1
When “PackageType” is defined, the “Weight” and “Dimensions” properties are not considered as mandatory because the weight and volumetric calculations are defined at the “PackageType” level. When “PackageType” is missing, then you should provide at least one of “Weight” or “Dimensions” values.
Party
A party structure is used whenever a shipment counterparty should be defined. That is, the Requestor, the Shipper, the Consignee and/or any other participant in the shipment lifecycle are all considered parties.
| Property | * | Type | Description |
|---|---|---|---|
| AccountNumber | Text | The system account number of the party. Used in cases where the specific party is already registered as a customer and has a valid account number in the system. May be obtained by the carrier or by using the Customer Accounts endpoints. | |
| Name | Text | The name of the party. This should be empty or contain the location name or company name. | |
| ContactName | *1 | Text | The contact name. This should be the physical person’s name. |
| BuildingFloorOffice | Text | Additional free text information regarding exact location details such as building number, floor or office number. | |
| Address | *2 | Text | The address of the location. |
| City | *2 | Text | The city name. |
| Area | Text | The city area name. | |
| PostalCode | *2 | Text | The postal code. |
| Country | Text | 2-letter ISO-3166-1 code of the country | |
| Phones | Text | A comma separated list of phone numbers. | |
| Fax | Text | A fax number. | |
| Emails | Text | A comma separated list of email addresses. | |
| NotificationPhone | Text | The phone number that should be used in cases where SMS notifications are required. | |
| NotificationEmail | Text | The email address that should be used in cases where e-mail notifications are required. | |
| Reference | Text | A free text reference of the specific party. | |
| TaxNumber | Text | The tax identification number of the party. | |
| IdType | Enum | The identification type of the party. Valid values are: “IdCard”, “Passport”, “DrivingLicense” and “Other”. | |
| IdTypeData | Text | The identification data according to “IdType” property. i.e. the IdCard number, the passport number etc. |
Warning
*1
Mandatory only when used in any Party structure on a normal shipment request. Not mandatory for shipping cost calculation request. See Shipment Cost Calculation section for details.
Warning
*2
The address location fields are mandatory only for Consignee objects and only when we are shipping in a door location address. That is, when we deliver to a door, address is required, when we deliver to a station (Clever Point), address is not required.