The Shipment Lifecycle
Booking a shipment begins by providing ARTA with location and object information. You can also request specific services in the initial request.
We’ll use the details you provide to generate quotes across three service levels: Premium, Select, and Parcel. The number of quotes returned may vary depending on the object details and where they’re being shipped. Quotes include packing recommendations, transportation costs, and additional services, such as Condition Reports, Assembly, and Installation. Insurance coverage may also be requested in creating the quote request.
Generating a quote request
To get started, create a request for quotes by sending a POST request to the /requests endpoint with the object and location details.
curl https://api.arta.io/requests
-X POST -d @input.json
-H "Content-Type: application/json"
-H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"In this example, input.json is the following file:
{
"request": {
"destination": {
"title": "Home",
"address_line_1": "87 Richardson St",
"city": "New York",
"postal_code": "11249",
"region": "NY",
"country": "US",
"contacts": [
{
"name": "Alfred Barr",
"email_address": "al@example.com",
"phone_number": "(222) 222-2222"
}
]
},
"objects": [
{
"subtype": "painting_unframed",
"unit_of_measurement": "in",
"depth": 2,
"width": 10,
"height": 10.5,
"weight": 3.5,
"weight_unit": "lb",
"details": {
"creator": "Robert Irwin",
"title": "All That Jazz"
},
"value": 15000.0,
"value_currency": "USD"
}
],
"origin": {
"title": "Warehouse",
"address_line_1": "11 W 53rd St",
"city": "New York",
"region": "NY",
"country": "US",
"postal_code": "10019",
"contacts": [
{
"name": "Mary Quinn Sullivan",
"email_address": "mary@example.com",
"phone_number": "(333) 333-3333"
}
]
}
}
}Certain fields such as
request.objects.subtypeorrequest.objects.value_currencyaccept a limited list of values for the request to be valid. The permitted values for each of these fields may be retrieved from ARTA's metadata endpoints prior to submitting your quote request.
This request will return bookable transport quotes for your objects. These quotes will span ARTA's three service tiers: Premium, Select, and Parcel.
{
"additional_services": [],
"bookable": {
"missing": [],
"ready": true
},
"created_at": "2021-07-23T04:39:20.180070",
"currency": "USD",
"destination": {
"access_restrictions": [],
"address_line_1": "87 Richardson St",
"address_line_2": null,
"address_line_3": null,
"city": "New York",
"contacts": [
{
"email_address": "al@example.com",
"name": "Alfred Barr",
"phone_number": "(222) 222-2222"
}
],
"country": "US",
"postal_code": "11249",
"region": "NY",
"title": "Home"
},
"disqualifications": [],
"hosted_session_id": null,
"id": "928e89cd-ea34-4304-a29f-4f222693fbd7",
"insurance": null,
"internal_reference": null,
"log_request_id": "FpRRqu5HseOrlDkAC2ZB",
"object_count": 1,
"objects": [
{
"current_packing": [],
"depth": "2",
"details": {
"creation_date": null,
"creator": "Robert Irwin",
"is_cites": false,
"is_fragile": false,
"materials": [],
"notes": null,
"title": "All That Jazz"
},
"height": "10.5",
"images": [],
"internal_reference": null,
"public_reference": null,
"subtype": "painting_unframed",
"type": "art",
"unit_of_measurement": "in",
"value": "15000.00",
"value_currency": "USD",
"weight": "3.5",
"weight_unit": "lb",
"width": "10"
}
],
"origin": {
"access_restrictions": [],
"address_line_1": "11 W 53rd St",
"address_line_2": null,
"address_line_3": null,
"city": "New York",
"contacts": [
{
"email_address": "mary@example.com",
"name": "Mary Quinn Sullivan",
"phone_number": "(333) 333-3333"
}
],
"country": "US",
"postal_code": "10019",
"region": "NY",
"title": "Warehouse"
},
"preferred_quote_types": [],
"public_reference": null,
"quote_types": [
"parcel",
"premium",
"select"
],
"quotes": [
{
"id": 323735,
"included_insurance_policy": null,
"included_services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Next Day Air",
"sub_subtype": "parcel",
"subtype": "parcel",
"type": "transport"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Collection",
"sub_subtype": "collection",
"subtype": "collection",
"type": "location"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Parcel Crate",
"sub_subtype": "parcel_crate",
"subtype": "packing_materials",
"type": "packing"
}
],
"optional_services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Signature Required",
"sub_subtype": "signature_delivery",
"subtype": "delivery",
"type": "location"
}
],
"quote_type": "parcel",
"status": "published",
"total": "3.00",
"total_currency": "USD"
},
{
"id": 323734,
"included_insurance_policy": null,
"included_services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Second Day Air",
"sub_subtype": "parcel",
"subtype": "parcel",
"type": "transport"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Collection",
"sub_subtype": "collection",
"subtype": "collection",
"type": "location"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Parcel Crate",
"sub_subtype": "parcel_crate",
"subtype": "packing_materials",
"type": "packing"
}
],
"optional_services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Signature Required",
"sub_subtype": "signature_delivery",
"subtype": "delivery",
"type": "location"
}
],
"quote_type": "parcel",
"status": "published",
"total": "3.00",
"total_currency": "USD"
},
{
"id": 323733,
"included_insurance_policy": null,
"included_services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Ground",
"sub_subtype": "parcel",
"subtype": "parcel",
"type": "transport"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Collection",
"sub_subtype": "collection",
"subtype": "collection",
"type": "location"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Parcel Crate",
"sub_subtype": "parcel_crate",
"subtype": "packing_materials",
"type": "packing"
}
],
"optional_services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Signature Required",
"sub_subtype": "signature_delivery",
"subtype": "delivery",
"type": "location"
}
],
"quote_type": "parcel",
"status": "published",
"total": "3.00",
"total_currency": "USD"
},
{
"id": 323732,
"included_insurance_policy": null,
"included_services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Next Day Air",
"sub_subtype": "parcel",
"subtype": "parcel",
"type": "transport"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Collection",
"sub_subtype": "collection",
"subtype": "collection",
"type": "location"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Parcel Crate",
"sub_subtype": "parcel_crate",
"subtype": "packing_materials",
"type": "packing"
}
],
"optional_services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Signature Required",
"sub_subtype": "signature_delivery",
"subtype": "delivery",
"type": "location"
}
],
"quote_type": "parcel",
"status": "published",
"total": "3.00",
"total_currency": "USD"
},
{
"id": 323731,
"included_insurance_policy": null,
"included_services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Second Day Air",
"sub_subtype": "parcel",
"subtype": "parcel",
"type": "transport"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Collection",
"sub_subtype": "collection",
"subtype": "collection",
"type": "location"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Parcel Crate",
"sub_subtype": "parcel_crate",
"subtype": "packing_materials",
"type": "packing"
}
],
"optional_services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Signature Required",
"sub_subtype": "signature_delivery",
"subtype": "delivery",
"type": "location"
}
],
"quote_type": "parcel",
"status": "published",
"total": "3.00",
"total_currency": "USD"
},
{
"id": 323730,
"included_insurance_policy": null,
"included_services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Ground",
"sub_subtype": "parcel",
"subtype": "parcel",
"type": "transport"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Collection",
"sub_subtype": "collection",
"subtype": "collection",
"type": "location"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Parcel Crate",
"sub_subtype": "parcel_crate",
"subtype": "packing_materials",
"type": "packing"
}
],
"optional_services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Signature Required",
"sub_subtype": "signature_delivery",
"subtype": "delivery",
"type": "location"
}
],
"quote_type": "parcel",
"status": "published",
"total": "3.00",
"total_currency": "USD"
},
{
"id": 323729,
"included_insurance_policy": null,
"included_services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Shadowbox",
"sub_subtype": "shadow_box",
"subtype": "packing_materials",
"type": "packing"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Specialized Shuttle",
"sub_subtype": "specialized_shuttle",
"subtype": "specialized",
"type": "transport"
}
],
"optional_services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Double Blind BOLs",
"sub_subtype": "double_blind_bols",
"subtype": "administration",
"type": "administration"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Signature Required",
"sub_subtype": "signature_delivery",
"subtype": "delivery",
"type": "location"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Condition Report (origin)",
"sub_subtype": "origin_full_condition_report",
"subtype": "condition",
"type": "handling"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [
{
"name": "Soft Packed Disposal",
"sub_subtype": "soft_packed_disposal",
"subtype": "debris_disposal",
"type": "handling"
}
],
"name": "Debris Disposal",
"sub_subtype": "debris_disposal",
"subtype": "debris_disposal",
"type": "handling"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Assembly",
"sub_subtype": "assembly",
"subtype": "installation",
"type": "handling"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Placement",
"sub_subtype": "placement",
"subtype": "installation",
"type": "handling"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Installation",
"sub_subtype": "installation",
"subtype": "installation",
"type": "handling"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Condition Check (destination)",
"sub_subtype": "destination_condition_check",
"subtype": "condition",
"type": "handling"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Condition Check (origin)",
"sub_subtype": "origin_condition_check",
"subtype": "condition",
"type": "handling"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Condition Report (destination)",
"sub_subtype": "destination_full_condition_report",
"subtype": "condition",
"type": "handling"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [
{
"name": "Unpacking Soft Materials (destination)",
"sub_subtype": "destination_unpacking_soft",
"subtype": "unpacking",
"type": "handling"
}
],
"name": "Unpacking (destination)",
"sub_subtype": "destination_unpacking",
"subtype": "unpacking",
"type": "handling"
}
],
"quote_type": "premium",
"status": "published",
"total": "2.00",
"total_currency": "USD"
},
{
"id": 323728,
"included_insurance_policy": null,
"included_services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [
{
"name": "Soft Packed Disposal",
"sub_subtype": "soft_packed_disposal",
"subtype": "debris_disposal",
"type": "handling"
}
],
"is_requested": false,
"is_required": true,
"name": "Debris Disposal",
"sub_subtype": "debris_disposal",
"subtype": "debris_disposal",
"type": "handling"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Strongbox",
"sub_subtype": "strongbox",
"subtype": "packing_materials",
"type": "packing"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Consolidated Trucking",
"sub_subtype": "road_groupage",
"subtype": "consolidated",
"type": "transport"
}
],
"optional_services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Signature Required",
"sub_subtype": "signature_delivery",
"subtype": "delivery",
"type": "location"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Condition Check (destination)",
"sub_subtype": "destination_condition_check",
"subtype": "condition",
"type": "handling"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [
{
"name": "Unpacking Soft Materials (destination)",
"sub_subtype": "destination_unpacking_soft",
"subtype": "unpacking",
"type": "handling"
}
],
"name": "Unpacking (destination)",
"sub_subtype": "destination_unpacking",
"subtype": "unpacking",
"type": "handling"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Double Blind BOLs",
"sub_subtype": "double_blind_bols",
"subtype": "administration",
"type": "administration"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"name": "Condition Check (origin)",
"sub_subtype": "origin_condition_check",
"subtype": "condition",
"type": "handling"
}
],
"quote_type": "select",
"status": "published",
"total": "3.00",
"total_currency": "USD"
}
],
"shipping_notes": null,
"shortcode": "DEMO-R3E87O",
"status": "quoted",
"updated_at": "2021-07-23T04:39:21.701365"
}Note that this response includes a list of quotes for your request. Each quote has a total which reflects the price of a booked shipment, a quote_type which describes the ARTA service level, and an id which is the numerical identifier for the quote. The id value is used when booking a particular quote.
If for any reason ARTA was unable to provide a quote in a particular service tier for your transport details, the reasons are returned in the disqualifications field.
Booking a shipment
To book a quote and create a shipment, you’ll simply a call to the /shipments endpoint with the ID of the Quote you are booking.
curl https://api.arta.io/shipments
-X POST -d @input.json
-H "Content-Type: application/json"
-H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"In this example, input.json is the following file:
{
"shipment": {
"quote_id": 323728
}
}This will create a Pending shipment that the ARTA team will review and confirm. The shipment response will look like the following:
{
"created_at": "2021-07-23T04:40:07.285018",
"destination": {
"access_restrictions": [],
"address_line_1": "87 Richardson St",
"address_line_2": null,
"address_line_3": null,
"city": "New York",
"contacts": [
{
"email_address": "al@example.com",
"name": "Alfred Barr",
"phone_number": "(222) 222-2222"
}
],
"country": "US",
"postal_code": "11249",
"region": "NY",
"title": "Home"
},
"hosted_session_id": null,
"id": "928e89cd-ea34-4304-a29f-4f222693fbd7",
"insurance_policy": null,
"internal_reference": null,
"log_request_id": "FpRRtfCY80dMVoMABd-y",
"object_count": 1,
"origin": {
"access_restrictions": [],
"address_line_1": "11 W 53rd St",
"address_line_2": null,
"address_line_3": null,
"city": "New York",
"contacts": [
{
"email_address": "mary@example.com",
"name": "Mary Quinn Sullivan",
"phone_number": "(333) 333-3333"
}
],
"country": "US",
"postal_code": "10019",
"region": "NY",
"title": "Warehouse"
},
"package_count": 1,
"packages": [
{
"depth": "6.0",
"handle_with_care": false,
"height": "14.5",
"id": 541345,
"is_sufficiently_packed": false,
"objects": [
{
"current_packing": [],
"depth": "2",
"details": {
"creation_date": null,
"creator": "Robert Irwin",
"is_cites": false,
"is_fragile": false,
"materials": [],
"notes": null,
"title": "All That Jazz"
},
"height": "10.5",
"images": [],
"internal_reference": null,
"public_reference": null,
"subtype": "painting_unframed",
"type": "art",
"unit_of_measurement": "in",
"value": "15000.00",
"value_currency": "USD",
"weight": "3.5",
"weight_unit": "lb",
"width": "10"
}
],
"packing_materials": [
"strongbox"
],
"unit_of_measurement": "in",
"weight": "3.5",
"weight_unit": "lb",
"width": "14.0"
}
],
"public_reference": null,
"quote_type": "select",
"schedule": {
"delivery_end": null,
"delivery_start": null,
"delivery_window_modifier": "",
"pickup_end": null,
"pickup_start": null,
"pickup_window_modifier": ""
},
"services": [
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Consolidated Trucking",
"sub_subtype": "road_groupage",
"subtype": "consolidated",
"type": "transport"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Strongbox",
"sub_subtype": "strongbox",
"subtype": "packing_materials",
"type": "packing"
},
{
"amount": "1.00",
"amount_currency": "USD",
"included_services": [],
"is_requested": false,
"is_required": true,
"name": "Debris Disposal",
"sub_subtype": "debris_disposal",
"subtype": "debris_disposal",
"type": "handling"
}
],
"shipping_notes": null,
"shortcode": "DEMO-273213",
"status": "pending",
"total": "3.00",
"total_currency": "USD",
"tracking": [],
"updated_at": "2021-07-23T04:40:07.449907",
"url": "https://connect.arta.io/shipments/147e99cd-ea34-4304-a29f-4f222693fbd7/dheCgcePyj3XsT7tyddTxsL"
}Shipment fulfillment
Once a shipment is confirmed, our team coordinates with our carrier network to have the objects collected, packed, and shipped.
Each shipment will transition between the following statuses as it is being fulfilled:
- Pending — A quote has been booked and is awaiting confirmation by an ARTA logistics specialist
- Confirmed — The request details are confirmed and the shipment is in progress
- Collected — The shipment has been collected from its origin location
- In Transit — The shipment is on its way to its destination
- Completed — The shipment has been delivered to its destination and all services have been fulfilled
You can periodically check back for status changes on shipments belonging to your organization by making a request to the shipment detail endpoint. This will always have the latest information available for the shipment. Alternatively, you can configure your integration to make use of ARTA's notification webhooks and emails.
curl https://api.arta.io/shipments/3dcbf2d1-979c-40ca-bdce-a52343254821
-H "Content-Type: application/json"
-H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"As they become available, tracking details and collection & delivery dates are added to the shipment. You can find any tracking details in the shipment response's tracking attribute. You can find relevant collection and delivery details in the shipment response's schedule attribute.
The ARTA team monitors each shipment until they’re delivered and all the services have been completed.