Welcome! Please note: this is a BETA release. All information is preliminary and subject to change.

Table of contents

Back to Top

About ARTA

Who is ARTA

ARTA delivers innovative technology and fulfillment solutions for global white glove logistics. ARTA provides a proprietary API and platform that streamlines the shipping of high-value, oversized, and fragile goods requiring extra services from point of sale to delivery. With a single solution, ARTA safely, easily and cost-effectively ships high-touch items to more customers in more locations to drive sales, enable opportunities for new categories and expand the global reach for businesses today. For more information, please visit us at shiparta.com

Contact Us

Phone: +1 646.828.7333

General Email: hello@shiparta.com

API Inquiries: api@shiparta.com

Web: https://shiparta.com

Back to Top

Overview

This document gives you an overview of the ARTA API and how it works. It describes the process of how to request and purchase quotes for shipping and related services. You can find more in-depth information about each call in their respective sections.

The ARTA API provides you with the ability to receive instant, guaranteed quotes for shipments and related services (e.g., packing, insurance, installation, etc.), across more than 60 countries. You can purchase desired quotes directly through the API and receive tracking updates on shipments.

Our API provides quotes for various ARTA service levels, from specialized white glove and fine art services to common parcel carriers and everything in between. Currently, the API only supports road and air shipments, however we have plans to expand support for other modes of transportation in the future.

Process Flow

The ARTA API starts with making a request. Shipping requests are made up of several parts including descriptions of the objects you want to ship, their current or requested packing requirements, and origin and destination details. You can also request additional services to add to your shipment, such as Inside Delivery, Installation, or ARTA Transit Insurance. While it’s possible to receive a quote with estimated costs without the full set of required object and address details, the quote cannot be purchased until all required details are provided.

A quote contains information costs for shipping and additional services. Some services are required in order to purchase so they will always be included in the price. Required services cannot be removed or excluded. Optional services may be returned with the quote either because they were requested or they are recommended by ARTA. Optional services can then be included or excluded from the final quote by calling the recalculation endpoint. Recalculating saves the quote with the services requested.

If a request is disqualified (see section on disqualifications), or if you wish to receive additional quotes from our team of experts, you can request Custom Quotes. Please note that it may take up to 72 hours to receive a custom quote, depending on the complexity of the shipment. If you need to make changes to a submitted Custom Quote request, simply cancel the request and create a new one. A request may be cancelled any time until it is purchased.

Once a quote is ready to be purchased, make a call to the purchase endpoint. Some additional information may be required and can be provided at this time. This includes any missing contact information for the origin and destination locations as well as any special instructions for given locations. Once a quote has been successfully purchased, the request is closed and can no longer be acted upon. From this point on, you will need to reference the job returned by the purchase call.

Once the request becomes a job, it can no longer be cancelled. You may ping the job to check for status updates, tracking information and dates until the job has been completed.

The API does not currently accept payment information via the API. API customers should collect payment from their buyers directly for the quote cost. Clients will then be invoiced by ARTA for all shipping and service costs.

API Technical Specifications

The technical specifications for the api are available in OpenAPI format or you can also use our html viewer.

API Updates

Most updates will be additive and should have little to no impact on the existing design of the input and output structures of the system. Any destructive or system defining changes will be alerted to you through all known available channels as soon as possible to give you enough time to make any adjustments to your systems or configs. These will be first reflected in test mode.

Back to Top

Authentication

At this time, the API is only accepting back-channel, server to server communications. We have future plans for different forms of authentication including integrations with user login and OpenID.

API Key Authentication

Obtaining Your API Key

Please contact ARTA directly regarding any setup, including obtaining API Keys. To get your set, please email us at api@shiparta.com.

Please keep your API Keys private and secure

Your key ties all activity to your account and any charges that its use may incur. For more information about what you're responsible for, please refer to your signed agreement.

How to use the API Key

Using your API is simple. Simply include your key in the Authorization header of every call made to the system. This is the only place that it is accepted.

Example Call

curl https://api.shiparta.com/request/basic_test_shipment/ -H "Authorization: ARTA_APIKey 1234567890abcdef"
  

In this example, you would replace ARTA_APIKey 1234567890abcdef with the actual token we provide you.

Back to Top

Metadata

Everything in our system that is used to describe something else has a type, represented by our metadata. Our metadata is often broken down into a hierarchy of type, subtype, etc. for easier customer understanding and display. However, only the lowest level is typically necessary when making calls.

All metadata IDs are based in lower snake case format (lower_snake_case) for easy readability and comprehension. Since metadata changes are relatively infrequent, it is recommended that you cache these responses.

Obtaining Metadata

To obtain our metadata, call the endpoint for the metadata you wish to obtain. These follow a format of /metadata/<type>/<subtype>/ depending on the levels available. For convenience, calls to the type will include all the data for the subtypes and sub-subtypes related to it.

All available metadata routes are listed in the openAPI schema.

Example Call

curl https://api.shiparta.com/metadata/location/types/ -H "Authorization: ARTA_APIKey 1234567890abcdef"
  

Example Response

[
    {
      "id": "residential",
      "name": "Residential",
      "description": "A location designed for people to live."
    },
    {
      "id": "commercial",
      "name": "Commercial",
      "description": "A location concerned with or engaged in commerce."
    },
    {
      "id": "airport",
      "name": "Airport",
      "description": "A complex of runways and buildings for the takeoff, landing, and maintenance of civil aircraft, with facilities for passengers and/or cargo."
    }
  ]

For more information regarding these responses, please view the metadata schemas

Back to Top

Making Requests

Almost everything starts with making a request. The request contains information about what you're requesting from ARTA. Currently, this includes Shipping with optional Packing services, Insurance, and additional Services. You can specify as little or as much information in the request about what you're shipping and where it's going. However, the less specific you are, the less accurate the quote will be. There is also a level of required information, particularly object and address information, before a quote is purchasable and can be fulfilled. The purchase_information returned in the response lets you know if the quotes given are available for purchase or what missing information would be required for booking. Once you've made a request, it is not editable. In order to change elements within a request, delete your previous request and make a new one. You can cancel a request that has not been purchased at any time.

Parts of a Request

A request can be broken up into several basic parts. Details for each can be found in the sections below.

Objects

Objects are descriptions of what is in the shipment. Each object should include:

You can also provide additional details to improve the accuracy of the quote provided. For example, providing the Materials of the object can help us accurately suggest packing options and transportation methods.

Object Images may be required for insurance purposes so we recommend providing these with the request to avoid shipping delays. Other details, such as Creation Year, Artist, etc can help with object identification. A customer_reference is also provided on each object.

Each object, no matter how similar, should have its own entry in the objects array.

Dimensions and Weight

For information about object weight, dimensions and acceptable units and formats, please see the dimensions section in the Appendix.

Packing

In order to ship objects, they need to be packed. Packing can vary greatly depending on what you are shipping, its value and transportation method. An object contains a field that allows you to provide the current packing of the object. This field needs to be an array of packing sub_type IDs obtained from the metadata routes.

If the item is not currently packed, or if you are unsure if the current packing is sufficient, we recommend leaving the current_packing field as an empty array. ARTA's proprietary packing system will automatically select the best possible packing type for you and even try and pack similar objects together where appropriate.

For more information about Objects, please view the full object schema

Locations

Locations describe a place. You have the option of providing a full address, a city, a region/province/state, a country, or even a postal code. The less specific the location, the less accurate the quote and without a full address, the quote is not eligible for purchase. Locations contain:

A note about Latitude and Longitude - Locations can be submitted using latitude and longitude points. If sent without an address, it will be reverse geocoded to obtain the address. This may seem more accurate, but not actually be idea. If the given address is on a side street of the actual location or if a suite/building/apartment number should be included, the reverse geocoded address will be less accurate. Since we cannot guarantee the validity of the address provided back from the geoencoder, providing a latitude and longitude is not the same as full real address and therefore may result in quotes that cannot be purchased.

For more information about Locations, please view the full location schema

Contacts

Contact information for a location is required for purchasing a quote. Contacts require:

For more information about Contacts, please view the full contact schema

Insurance

This section allows you to either request ARTA Transit Insurance or accept our standard liability of $50. The cost of ARTA Transit insurance will be based on the total value given of all the objects. ARTA Transit Insurance requires a Condition Report to be performed at the origin location. Shipments valuing more than $1M USD cannot be insured via the API. For shipments valuing more than $1M USD, please send this request as a custom quote request as this will require our specialists to review all aspects of the object and service requested.

Services

Request responses generate a number of optional and required services. To specify these services up front and have them included in the quote if available, you can use the additional_services field to request them. For more information on services, please see the services section in the chapter on quotes.

Currency

You can receive quotes in one of our supported currencies by using this field to specify the ISO 4217 three-letter currency code. For more information on how currency is handled by the system, please see the [Monetary Units and section alphabetic currency code. Supported currencies may fluctuate for reasons beyond our control, please check our metadata in the Appendix](../appendix.md#monetary-units-and-currency). for the most up to date list. If not supplied, the currency defaults to USD. For more information on how currency is handled by the system, please see the Monetary Units and section in the Appendix.

Customer Reference

Each request has a customer reference field that can store 255 character length string of any information you may want to provide that the system will return to you unaltered for your convenience. This can be handy for storing stringified data on the request itself.

Name

You may give the request a name. This field can be used to give this request a display name that will be visible on the management dashboard when accessing the platform and is transferred over to the Job on purchase. If a name is not provided, the system will automatically generate one for you.

Notes

The notes field should be used to store any information about the request that will be read by others.

Making a Request Call

To make a request simply make a POST call to the request endpoint with the body containing the request JSON.

Example Request Call

 curl https://api.shiparta.com/request/ -X POST -d @input.json -H "Content-Type: application/json" -H "Authorization: ARTA_APIKey 1234567890abcdef"
  

In this example, input.json is the following file:

{
      "objects": [
          {
              "width": 12.5,
              "height": 24.5,
              "depth": 2,
              "unit_of_measurement": "in",
              "weight": 20,
              "weight_unit": "lb",
              "value": "405000.00",
              "value_currency": "USD",
              "current_packing": [
                  "poly_cardboard"
              ],  
              "images": [
                  "https://example.com/image.png"
              ],
              "details": {
                  "year_created": "1925",
                  "creator": "An Artist",
                  "notes": "some notes here",
                  "title": "It's a painting"                
              },
              "type": "art",
              "sub_type": "painting_unframed"
          }
      ],
      "origin_locations": [
          {
              "address_line_1": "1000 5th Avenue",
              "city": "New York",
              "region": "NY",
              "postal_code": "10028",
              "country": "US",
              "title": "Metropolitan Museum of Art",
              "type": "commercial",
              "contacts": [
                  {
                      "name": "Jane Doe",
                      "primary_email": "jdoe@example.com",
                      "phone_numbers": [
                          {
                              "country_code": "+1",
                              "number": "2125551234",
                              "ext": "123"
                          }
                      ]
                  }
              ],
              "location_requirements": [
                  "no_elevator"
              ]
          }
      ],
      "destination_locations": [
          {
              "address_line_1": "100 34th Avenue",
              "city": "San Francisco",
              "region": "CA",
              "postal_code": "94121",
              "country": "US",
              "title": "Legion of Honor",
              "type": "commercial"            
          }
      ],
      "customer_reference": "{\"example\":\"using this fields to store some json\"}",
      "name": "Test Request",
      "insurance": "arta_transit_insurance",
      "additional_services": [        
          "installation"
      ],
      "notes": "This could be an example of a delivery note from a user in your system"
  } 

For more information regarding this request, please view the full request schema

Example Request Response

{
      "objects": [
          {
              "id": "1234567890abcdefg",
              "width": 12.5,
              "height": 24.5,
              "depth": 2,
              "unit_of_measurement": "in",
              "weight": 20,
              "weight_unit": "lb",
              "value": "405000.00",
              "value_currency": "USD",
              "current_packing": [
                  "poly_cardboard"
              ],  
              "images": [
                  "https://example.com/image.png"
              ],
              "details": {
                  "year_created": "1925",
                  "creator": "An Artist",
                  "notes": "some notes here",
                  "title": "It's a painting",
                  "is_oversized": false
              "is_fragile": true
              },
              "type": "art",
              "sub_type": "painting_unframed",

          }
      ],
      "origin_locations": [
          {
              "address_line_1": "1000 5th Avenue",
              "city": "New York",
              "region": "NY",
              "postal_code": "10028",
              "country": "US",
              "longitude": -73.96324400000003,
              "latitude": 40.7794366,
              "title": "Metropolitan Museum of Art",
              "type": "commercial",
              "contacts": [
                  {
                      "name": "Jane Doe",
                      "primary_email": "jdoe@example.com",
                      "phone_numbers": [
                          {
                              "country_code": "+1",
                              "number": "2125551234",
                              "ext": "123"
                          }
                      ]
                  }
              ],
              "location_requirements": [
                  "no_elevator"
              ],
              "id": "123abc"
          }
      ],
      "destination_locations": [
          {
              "address_line_1": "100 34th Avenue",
              "city": "San Francisco",
              "region": "CA",
              "postal_code": "94121",
              "country": "US",
              "longitude": -122.50084190000001,
              "latitude": 37.7844661,
              "title": "Legion of Honor",
              "type": "commercial",
              "contacts": [],
              "id": "cba321"
          }
      ],
      "name": "Test Request",
      "customer_reference": "{\"example\":\"using this fields to store some json\"}",
      "insurance": "arta_transit_insurance",
      "additional_services": [
          "installation"
      ],
      "notes": "This could be an example of a delivery note from a user in your system",
      "id": "ARTA_ID",
      "purchase_information": {
          "available": true,
          "missing": [],
          "required_contact_locations": ["cba321"]
      },
      "quotes": [
          {
              "id": "ARTA-QUOTE-ID",
              "quote_type": {
                  "id": "premium",
                  "name": "ARTA Premium",
                  "description": "Specialized climate-controlled transportation operated by trained technicians from wall-to-wall."
              },
              "total": "1040.00",
              "total_currency": "USD",
              "packing": [
                  "econo_crate"
              ],
              "name": "Requested Shipment",
              "description": "This test shipment was created for testing purposes only.",
              "state": "published",
              "caveats": [],
              "expiration_date": null,
              "estimated_start": {},
              "duration": {},
              "insurance": {
                  "id": "arta_transit_insurance",
                  "quoted_value": "405000.00",
                  "quoted_value_currency": "USD",
                  "is_included": true,
                  "amount": "75.00",
                  "amount_currency": "USD",
                  "name": "ARTA Transit Insurance",
                  "description": "ARTA full risk coverage transit insurance",
                  "required_services": [
	                "origin_full_condition_report"
                  ]  
              },
              "services": [
                  {
                      "type": "handling",
                      "subtype": "condition",
                      "sub_subtype": "origin_full_condition_report",
                      "is_included": true,
                      "is_required": true,
                      "amount": "50.00",
                      "amount_currency": "USD",
                      "name": "Condition Report (origin)",
                      "description": "Full inspection and written report at the origin location"
                  },
                  {
                      "type": "handling",
                      "subtype": "packing",
                      "sub_subtype": "crate_fabrication",
                      "name": "Crate Fabrication",
                      "description": "Crate fabrication including materials and labor",
                      "is_included": true,
                      "is_required": false,
                      "amount": "150.00",
                      "amount_currency": "USD",
                      "included_services": [
                          {
                              "type": "handling",
                              "subtype": "packing_materials",
                              "sub_subtype": "soft_packing",
                              "name": "Soft Packing",
                              "description": "Packaging materials including poly, bubble and cardboard"
                          },
                          {
                              "type": "handling",
                              "subtype": "packing_materials",
                              "sub_subtype": "crate",
                              "name": "Crate",
                              "description": "Wood structure that fully encloses object with 6 wood sides"
                          },
                          {
                              "type": "handling",
                              "subtype": "packing",
                              "sub_subtype": "packing_labor",
                              "name": "Packing Labor",
                              "description": "Labor for packing"
                          }
                      ]
                  },
                  {
                      "type": "handling",
                      "subtype": "condition",
                      "sub_subtype": "destination_full_condition_report",
                      "amount": "100.00",
                      "amount_currency": "USD",
                      "is_included": false,
                      "is_required": false,
                      "name": "Condition Report (destination)",
                      "description": "Full inspection and written report at the destination location"
                  },
                  {
                      "type": "handling",
                      "subtype": "installation",
                      "sub_subtype": "installation",
                      "name": "Installation",
                      "description": "Installation",
                      "is_included": true,
                      "is_required": false,
                      "amount": "65.00",
                      "amount_currency": "USD",
                      "included_services": [
                          {
                              "type": "handling",
                              "subtype": "unpacking",
                              "sub_subtype": "unpacking_soft",
                              "name": "Unpacking Labor",
                              "description": "Unpacking labor for soft packaged objects"
                          },
                          {
                              "type": "handling",
                              "subtype": "debris_disposal",
                              "sub_subtype": "debris_disposal",
                              "name": "Debris Disposal",
                              "description": "Removal and disposal of any debris"
                          }
                      ]
                  },
                  {
                      "type": "handling",
                      "subtype": "deinstallation",
                      "sub_subtype": "deinstallation",
                      "name": "Deinstallation",
                      "description": "Deinstallation",
                      "is_included": false,
                      "is_required": false,
                      "amount": "45.00",
                      "amount_currency": "USD"
                  },
                  {
                      "type": "transport",
                      "subtype": "specialized",
                      "sub_subtype": "specialized_shuttle",
                      "is_included": true,
                      "is_required": true,
                      "amount": "850.00",
                      "amount_currency": "USD",
                      "name": "Specialized Shuttle",
                      "description": "Climate controlled, dual driver, air ride shuttles operated by fine art trained technicians",
                      "included_services": [
                          {
                              "type": "location",
                              "subtype": "delivery",
                              "sub_subtype": "residential_delivery",
                              "name": "Residential Delivery",
                              "description": "Delivery to a residence"
                          },
                          {
                              "type": "location",
                              "subtype": "delivery",
                              "sub_subtype": "signature_delivery",
                              "name": "Signature Required",
                              "description": "A signature from the recipient is required at delivery"
                          },
                          {
                              "type": "location",
                              "subtype": "delivery",
                              "sub_subtype": "room_of_choice_delivery",
                              "name": "Room of Choice Delivery",
                              "description": "Delivery to the interior room of the recipient's choice"
                          },
                          {
                              "type": "handling",
                              "subtype": "handling",
                              "sub_subtype": "additional_stairs",
                              "name": "Additional Stairs",
                              "description": "Handling labor for additional stairs"
                          }
                      ]
                  }
              ]
          }
      ]
  }

For more information regarding this response, please view the full request response schema

Back to Top

Retrieving your Previous Requests

Once you have made a request, the response will contain the ARTA ID for your shipment. You can use the ARTA ID to retrieve your request response at any time. If you have purchased a quote, then the response body will contain the request, however the status will be a 303 with the redirect location header being to that of the job. Jobs share the ARTA ID of the originating request.

To retrieve your request, simply make a GET call containing the ARTA ID.

Example Request Retrieval Call

curl https://api.shiparta.com/request/ARTA_ID/ -H "Authorization: ARTA_APIKey 1234567890abcdef"
  

In this example, you would replace ARTA_ID with the id you received back in the request response

Back to Top

Cancelling a Request

To cancel a request, simply make a DELETE call to the request endpoint containing the ARTA ID

Example Cancel Request Call

curl https://api.shiparta.com/request/ARTA_ID/ -X DELETE -H "Authorization: ARTA_APIKey 1234567890abcdef"
  

In this example, you would replace ARTA_ID with the id you received back in the request response

Back to Top

Request Response

Once you have submitted a request to the system, the response contains the original request information as well as several other components generated by the system. These include:

If the system cannot quote a request, then the request becomes disqualified. A disqualification means that we could not automatically provide you with a quote and it needs to be quoted manually through the custom quoting process (see requesting custom quotes in the quote actions section).

For more information regarding this response, please view the full request response schema

Disqualifications

If a request becomes disqualified then the disqualifications field will be returned in the response. This field is an array listing all the known reasons why a request was disqualified. Each disqualification contains:

For more information regarding this response, please view the full request failed schema which includes disqualifications.

Purchase Information

The purchase information contains the three fields describing if the quotes can be purchased.

Quotes

Each quote given in the system represents a shipping job that you can purchase if available (see purchase information). Each quote contains:

Insurance

This field contains insurance information about a quote.

Quote Types

The quote type describes the level of service.

For additional information on each quote type, please call the metadata service. Not all responses return all quote types. Based on the object and locations only safe and viable options will be returned.

Caveats

The caveats field is an array of legal caveats outlining additional terms and conditions beyond the standard ARTA terms and conditions. By purchasing the quote, you and your users are agreeing to these terms.

Currency

If you have selected a different currency, all costs within the quote will be provided in that currency. The exchange rate is given at the request level and applies to all quotes in the response. When the total and amount fields are given in a currency other than what it was issued in, there will be two additional fields containing the original issued amount and currency.

Fees

This field contains any fees that were also applied to the quote total. The calculated_amount on the fee gives the cost that was added to the total. Subtracting all fees from the total will give you a subtotal from which the fee was based.

Services

Services are what makes up most of the quote. Services include Transportation, additional services requested, and those required. Not all services provided in the quote are included in the cost as some services are provided as optional services that a user can choose to include. Only services that are included or required are reflected in the quote total.

Each service in a quote contains a service type, subtype and sub_subtype that corresponds to those found in the metadata. This includes the human readable name and description of the service sub_subtype for convenience.

There are two Boolean fields on each service, the is_included and is_required fields. When the is_required field is true, the service is required and the cost is included in the quote total. Required services cannot be removed from a quote. When the is_included field is true, the cost of that service is included in the quote total and that this service will be part of the quote when purchased. If a service is included, but not required, it can be added or removed from the quote by using the recalculate quote action (see recalculating a quote for more information on adding and removing services from a quote).

Services also contain a required_by and a required_services field. These fields both contain an array of service sub_subtype ids of other services within the quote. The required_by field is a list of services that require this service if that service is included. The required_services field is a list of services that are required to support this service. If including this service, then the services in this list will also be included. The cost of these services for both of these fields is in addition to and not included in the given service cost.

Back to Top

Quote Actions

Once you have received A response from the system, you can then take the following actions:

Requesting Custom Quotes

If you received a disqualification, you can send a custom quote request to receive custom quotes by our team of experts. Receiving a custom quote can take up to 72 hours as we reach out to our network. During this time, the quote state will be listed as in_progress and will be updated once the custom quotes have been received. If any information required for quoting has not been provided, we will reach out to your team to obtain more information about the request, which may add to the additional time taken to get a custom quote. Custom quotes are delivered in the same format as quotes.

Making a Request for Custom Quotes Call

To send a request to be custom quoted, simply make a GET call to the custom request endpoint using the ARTA ID found in the request response.

Example Custom Quotes Call

curl https://api.shiparta.com/request/ARTA_ID/custom/ -H "Authorization: ARTA_APIKey 1234567890abcdef"
  

In this example, you would replace ARTA_ID with the id you received back in the request response

Recalculating a Quote

When you receive a quote, the cost will include transportation and any additional services requested. The quote will also include additional services that are required to carry out the job, even if those services were not requested.

In addition to requested and required services, we may also provide optional services and their costs; however, the cost of those suggested services will not be included in the quote total. If you would like to add one or more of the suggested services to your job, or would like to remove a service you had originally requested (assuming it is not required), you can use the recalculation endpoint to update the request. You will not be able to add an additional service that was not initially requested or suggested using the recalculate function. You cannot remove a service that is required.

Once you have recalculated your quote, you will receive an updated quote that will replace the previous quote in our system.

Making a Recalculation call

The recalculation call is a PATCH request to the recalculate endpoint using the ARTA ID and the quote's ID. The JSON body of the request contains 4 sections:

You only need to include what you want to adjust in this call. For example, if Installation was not requested but is available in the quote and becomes desired, simply calling the recalculate method with the installation service sub_subtype in the include_services field would then add that service (along with any additional required services) to that quote and not alter anything else about it.

Example Recalculation Call

curl https://api.shiparta.com/calculate/request/ARTA_ID/quote/ARTA-QUOTE-ID/ -X PATCH -d '{"include_services": ["deinstallation"]}' -H "Content-Type: application/json" -H "Authorization: ARTA_APIKey 1234567890abcdef"
  

In this example, you would replace ARTA_ID with the id you received back in the request response and ARTA-QUOTE-ID with the id of the quote you wish to adjust.

For more information regarding what's in the recalculation call, please view the full recalculate schema

Example Recalculation Response

{
      "objects": [
          {
              "id": "1234567890abcdefg",
              "width": 12.5,
              "height": 24.5,
              "depth": 2,
              "unit_of_measurement": "in",
              "weight": 20,
              "weight_unit": "lb",
              "value": "405000.00",
              "value_currency": "USD",
              "current_packing": [
                  "poly_cardboard"
              ],
              "requested_packing": [
                  "econo_crate"
              ],
              "images": [
                  "https://example.com/image.png"
              ],
              "details": {
                  "year_created": "1925",
                  "creator": "An Artist",
                  "notes": "some notes here",
                  "title": "It's a painting",
                  "is_oversized": false,
              	"is_fragile": true
              },
              "type": "art",
              "sub_type": "painting_unframed",
          }
      ],
      "origin_locations": [
          {
              "address_line_1": "1000 5th Avenue",
              "city": "New York",
              "region": "NY",
              "postal_code": "10028",
              "country": "US",
              "longitude": -73.96324400000003,
              "latitude": 40.7794366,
              "title": "Metropolitan Museum of Art",
              "type": "commercial",
              "contacts": [
                  {
                      "name": "Jane Doe",
                      "primary_email": "jdoe@example.com",
                      "phone_numbers": [
                          {
                              "country_code": "+1",
                              "number": "2125551234",
                              "ext": "123"
                          }
                      ]
                  }
              ],
              "location_requirements": [
                  "no_elevator"
              ],
              "id": "123abc"
          }
      ],
      "destination_locations": [
          {
              "address_line_1": "100 34th Avenue",
              "city": "San Francisco",
              "region": "CA",
              "postal_code": "94121",
              "country": "US",
              "longitude": -122.50084190000001,
              "latitude": 37.7844661,
              "title": "Legion of Honor",
              "type": "commercial",
              "contacts": [],
              "id": "cba321"
          }
      ],
      "name": "Test Request",
      "customer_reference": "{\"example\":\"using this fields to store some json\"}",
      "insurance": "arta_transit_insurance",
      "additional_services": [
          "installation"
      ],
      "notes": "This could be an example of a delivery note from a user in your system",
      "id": "ARTA_ID",
      "purchase_information": {
          "available": true,
          "missing": [],
          "required_contact_locations": ["cba321"]
      },
      "quotes": [
          {
              "id": "ARTA-QUOTE-ID",
              "quote_type": {
                  "id": "premium",
                  "name": "ARTA Premium",
                  "description": "Specialized climate-controlled transportation operated by trained technicians from wall-to-wall."
              },
              "total": "1085.00",
              "total_currency": "USD",
              "packing": [
                  "econo_crate"
              ],
              "name": "Requested Shipment",
              "description": "This test shipment was created for testing purposes only.",
              "state": "published",
              "caveats": [],
              "expiration_date": null,
              "estimated_start": {},
              "duration": {},
              "insurance": {
                  "id": "arta_transit_insurance",
                  "quoted_value": "405000.00",
                  "quoted_value_currency": "USD",
                  "is_included": true,
                  "amount": "75.00",
                  "amount_currency": "USD",
                  "name": "ARTA Transit Insurance",
                  "description": "ARTA full risk coverage transit insurance"
              },
              "services": [
                  {
                      "type": "handling",
                      "subtype": "condition",
                      "sub_subtype": "origin_full_condition_report",
                      "is_included": true,
                      "is_required": true,
                      "amount": "50.00",
                      "amount_currency": "USD",
                      "name": "Condition Report (origin)",
                      "description": "Full inspection and written report at the origin location"
                  },
                  {
                      "type": "handling",
                      "subtype": "packing",
                      "sub_subtype": "crate_fabrication",
                      "name": "Crate Fabrication",
                      "description": "Crate fabrication including materials and labor",
                      "is_included": true,
                      "is_required": false,
                      "amount": "150.00",
                      "amount_currency": "USD",
                      "included_services": [
                          {
                              "type": "handling",
                              "subtype": "packing_materials",
                              "sub_subtype": "soft_packing",
                              "name": "Soft Packing",
                              "description": "Packaging materials including poly, bubble and cardboard"
                          },
                          {
                              "type": "handling",
                              "subtype": "packing_materials",
                              "sub_subtype": "crate",
                              "name": "Crate",
                              "description": "Wood structure that fully encloses object with 6 wood sides"
                          },
                          {
                              "type": "handling",
                              "subtype": "packing",
                              "sub_subtype": "packing_labor",
                              "name": "Packing Labor",
                              "description": "Labor for packing"
                          }
                      ]
                  },
                  {
                      "type": "handling",
                      "subtype": "condition",
                      "sub_subtype": "destination_full_condition_report",
                      "amount": "100.00",
                      "amount_currency": "USD",
                      "is_included": false,
                      "is_required": false,
                      "name": "Condition Report (destination)",
                      "description": "Full inspection and written report at the destination location"
                  },
                  {
                      "type": "handling",
                      "subtype": "installation",
                      "sub_subtype": "installation",
                      "name": "Installation",
                      "description": "Installation",
                      "is_included": true,
                      "is_required": false,
                      "amount": "65.00",
                      "amount_currency": "USD",
                      "included_services": [
                          {
                              "type": "handling",
                              "subtype": "unpacking",
                              "sub_subtype": "unpacking_soft",
                              "name": "Unpacking Labor",
                              "description": "Unpacking labor for soft packaged objects"
                          },
                          {
                              "type": "handling",
                              "subtype": "debris_disposal",
                              "sub_subtype": "debris_disposal",
                              "name": "Debris Disposal",
                              "description": "Removal and disposal of any debris"
                          }
                      ]
                  },
                  {
                      "type": "handling",
                      "subtype": "deinstallation",
                      "sub_subtype": "deinstallation",
                      "name": "Deinstallation",
                      "description": "Deinstallation",
                      "is_included": true,
                      "is_required": false,
                      "amount": "45.00",
                      "amount_currency": "USD"
                  },
                  {
                      "type": "transport",
                      "subtype": "specialized",
                      "sub_subtype": "specialized_shuttle",
                      "is_included": true,
                      "is_required": true,
                      "amount": "850.00",
                      "amount_currency": "USD",
                      "name": "Specialized Shuttle",
                      "description": "Climate controlled, dual driver, air ride shuttles operated by fine art trained technicians",
                      "included_services": [
                          {
                              "type": "location",
                              "subtype": "delivery",
                              "sub_subtype": "residential_delivery",
                              "name": "Residential Delivery",
                              "description": "Delivery to a residence"
                          },
                          {
                              "type": "location",
                              "subtype": "delivery",
                              "sub_subtype": "signature_delivery",
                              "name": "Signature Required",
                              "description": "A signature from the recipient is required at delivery"
                          },
                          {
                              "type": "location",
                              "subtype": "delivery",
                              "sub_subtype": "room_of_choice_delivery",
                              "name": "Room of Choice Delivery",
                              "description": "Delivery to the interior room of the recipient's choice"
                          },
                          {
                              "type": "handling",
                              "subtype": "handling",
                              "sub_subtype": "additional_stairs",
                              "name": "Additional Stairs",
                              "description": "Handling labor for additional stairs"
                          }
                      ]
                  }
              ]
          }
      ]
  }

This response is based on the request example

Purchasing a Quote

Once you are ready to purchase a quote, you can make a call to purchase the quote and book the shipment with ARTA. Purchasing a quote does a number of things in the system, including converting the Request into a Job which is returned back to you in the response of the call. It also updates the status on any other quotes in the request, making them unavailable for purchase.

The purchase call includes a customer_reference field, that will be added to the job upon conversion. Like other customer_reference fields, this can be used by you to store any information about the Job that you would want passed back to you.

The purchase call contains an array for additional location information. If the location ID is given in the purchase information as requiring a contact, then the contact information for that location ID must be given at this time. Beyond contact, you can also include special_instructions that may not have been entered at the time of request for each location.

API customers must be on open-terms with us though your integration which means you will need to handle the collection of payment from your customer and ARTA will be billing you for the cost of the shipment. Making a Purchase call

Making a Purchase call

To make a purchase, send a POST call to the purchase endpoint. If successful, you will receive a Job back with the same ARTA ID.

Example Purchase Call

curl https://api.shiparta.com/purchase/request/ARTA_ID/quote/ARTA-QUOTE-ID/ -X POST -d @purchase.json -H "Content-Type: application/json" -H "Authorization: ARTA_APIKey 1234567890abcdef"
  

In this example, you would replace ARTA_ID with the id you received back in the request response and ARTA-QUOTE-ID with the id of the quote you wish to adjust. The purchase.json is the following file:

{
      "location_details": [
          {
            "location_id": "123abc",
            "special_instructions": "Ring top bell"
          },
          {
              "location_id": "cba321",
              "special_instructions": "Delivery entry though gate 3",
              "contacts": [
                  {
                      "name": "Fred Bloggs",
                      "primary_email": "fbloggs@example.com",
                      "phone_numbers": [
                          {
                              "country_code": "+1",
                              "number": "4155554321",
                              "ext": "321"
                          }
                      ]
                  }
              ]
          }
      ],
      "customer_reference": "This customer reference will be place onto the Job."
  }

For more information regarding what's in the purchase call, please view the full purchase schema

Example Purchase Response

A successful call returns the Job object created. For more information and an example, please see the Jobs section

Back to Top

Jobs

Once a request has been purchased, it is then turned into a Job. This includes information about the:

Parts of a Job

Request Information

The request information in the Job gives the request_type, any additional_services that were originally requested, the insurance that was requested, any notes that were given on the request as well as the original customer_reference field.

Dates

Once a Job has been paid for, estimated dates for collection and delivery are provided for convenience. The actual_start_time and actual_end_time fields contain actual dates once confirmed.

Tracking information

If any tracking information is available, then this will appear in the tracking_info field. For more about Tracking, please see the section on tracking.

Totals

The total field reflects the total cost of the job. As with all things monetary, if this also includes a currency other than USD, it includes the exchange_rate and the original issued amounts. The amount_paid field shows how much of the total has been paid in full and the invoice_amount field show how much of the total has been invoiced for payment.

Packages

Once a request becomes a Job, we know how the object(s) in the original request will be packed and attributes of each package. The original objects are listed within a package. A package may contain multiple objects if our system determines they can be packed together. Each package contains a required_packing flag which lets you know if the objects were sufficiently packed or whether ARTA recommends specific packing for those objects. The handle_with_care flag is set to true when one or more objects in the package is listed as fragile.

Retrieving a Job

To retrieve a Job, simply make a GET call containing the ARTA ID.

Example Job Retrieval Call

curl https://api.shiparta.com/job/ARTA_ID/ -H "Authorization: ARTA_APIKey 1234567890abcdef"
  

In this example, you would replace ARTA_ID with the id of the request/job you wish to receive.

Example Job Retrieval Response

{
      "id": "ARTA_ID",
      "url": "https://test.shiparta.com/shipments/shh/ARTA_ID/",
      "label_url": "",
      "total": "1085.00",
      "total_currency": "USD",
      "invoiced_amount": "1085.00",
      "invoiced_amount_currency": "USD",
      "quote": {
          "id": "ARTA-QUOTE-ID",
          "quote_type": {
              "id": "premium",
              "name": "ARTA Premium",
              "description": "Specialized climate-controlled transportation operated by trained technicians from wall-to-wall."
          },
          "total": "1085.00",
          "total_currency": "USD",
          "packing": [
              "econo_crate"
          ],
          "name": "Requested Shipment",
          "description": "This test shipment was created for testing purposes only.",
          "state": "accepted",
          "caveats": [],
          "expiration_date": null,
          "estimated_start": {},
          "duration": {},
          "insurance": {
              "id": "arta_transit_insurance",
              "quoted_value": "405000.00",
              "quoted_value_currency": "USD",
              "amount": "75.00",
              "amount_currency": "USD",
              "name": "ARTA Transit Insurance",
              "description": "ARTA full risk coverage transit insurance"
          },
          "services": [
              {
                  "type": "handling",
                  "subtype": "condition",
                  "sub_subtype": "origin_full_condition_report",
                  "amount": "50.00",
                  "amount_currency": "USD",
                  "name": "Condition Report (origin)",
                  "description": "Full inspection and written report at the origin location"
              },
              {
                  "type": "handling",
                  "subtype": "packing",
                  "sub_subtype": "crate_fabrication",
                  "name": "Crate Fabrication",
                  "description": "Crate fabrication including materials and labor",
                  "amount": "150.00",
                  "amount_currency": "USD",
                  "included_services": [
                      {
                          "type": "handling",
                          "subtype": "packing_materials",
                          "sub_subtype": "soft_packing",
                          "name": "Soft Packing",
                          "description": "Packaging materials including poly, bubble and cardboard"
                      },
                      {
                          "type": "handling",
                          "subtype": "packing_materials",
                          "sub_subtype": "crate",
                          "name": "Crate",
                          "description": "Wood structure that fully encloses object with 6 wood sides"
                      },
                      {
                          "type": "handling",
                          "subtype": "packing",
                          "sub_subtype": "packing_labor",
                          "name": "Packing Labor",
                          "description": "Labor for packing"
                      }
                  ]
              },
              {
                  "type": "handling",
                  "subtype": "installation",
                  "sub_subtype": "installation",
                  "name": "Installation",
                  "description": "Installation",
                  "amount": "65.00",
                  "amount_currency": "USD",
                  "included_services": [
                      {
                          "type": "handling",
                          "subtype": "unpacking",
                          "sub_subtype": "unpacking_soft",
                          "name": "Unpacking Labor",
                          "description": "Unpacking labor for soft packaged objects"
                      },
                      {
                          "type": "handling",
                          "subtype": "debris_disposal",
                          "sub_subtype": "debris_disposal",
                          "name": "Debris Disposal",
                          "description": "Removal and disposal of any debris"
                      }
                  ]
              },
              {
                  "type": "handling",
                  "subtype": "deinstallation",
                  "sub_subtype": "deinstallation",
                  "name": "Deinstallation",
                  "description": "Deinstallation",
                  "amount": "45.00",
                  "amount_currency": "USD"
              },
              {
                  "type": "transport",
                  "subtype": "specialized",
                  "sub_subtype": "specialized_shuttle",
                  "amount": "850.00",
                  "amount_currency": "USD",
                  "name": "Specialized Shuttle",
                  "description": "Climate controlled, dual driver, air ride shuttles operated by fine art trained technicians",
                  "included_services": [
                      {
                          "type": "location",
                          "subtype": "delivery",
                          "sub_subtype": "residential_delivery",
                          "name": "Residential Delivery",
                          "description": "Delivery to a residence"
                      },
                      {
                          "type": "location",
                          "subtype": "delivery",
                          "sub_subtype": "signature_delivery",
                          "name": "Signature Required",
                          "description": "A signature from the recipient is required at delivery"
                      },
                      {
                          "type": "location",
                          "subtype": "delivery",
                          "sub_subtype": "room_of_choice_delivery",
                          "name": "Room of Choice Delivery",
                          "description": "Delivery to the interior room of the recipient's choice"
                      },
                      {
                          "type": "handling",
                          "subtype": "handling",
                          "sub_subtype": "additional_stairs",
                          "name": "Additional Stairs",
                          "description": "Handling labor for additional stairs"
                      }
                  ]
              }
          ]
      },
      "status": "pending",
      "status_details": "Pending confirmation",
      "packages": [
          {
              "id": "",
              "width": 19.5,
              "height": 32.5,
              "depth": 12,
              "unit_of_measurement": "in",
              "weight": 30,
              "weight_unit": "lb",
              "required_packing": true,
              "handle_with_care": true,

              "packing_types": [
                  "econo_crate"
              ],
              "objects": [
                  {
                      "type": "art",
                      "depth": 2,
                      "value": "405000.00",
                      "width": 12.5,
                      "height": 24.5,
                      "images": [
                          "https://yourwebsite.com/image.png"
                      ],
                      "weight": 20,
                      "details": {
                          "notes": "some notes here",
                          "title": "It's a painting",
                          "creator": "An Artist",
                          "is_oversized": false,
                          "year_created": "1925"
                          "is_fragile": true
                      },
                      "sub_type": "painting_unframed",
                      "weight_unit": "lb",
                      "value_currency": "USD",
                      "current_packing": [
                          "poly_cardboard"
                      ],
                      "unit_of_measurement": "in"
                  }
              ]
          }
      ],
      "origin_locations": [
          {
              "id": "ORIGIN",
              "city": "New York",
              "type": "commercial",
              "title": "Metropolitan Museum of Art",
              "region": "NY",
              "country": "US",
              "special_instructions": "Ring top bell",
              "contacts": [
                  {
                      "name": "Jane Doe",
                      "phone_numbers": [
                          {
                              "ext": "123",
                              "number": "2125551234",
                              "country_code": "+1"
                          }
                      ],
                      "primary_email": "jdoe@example.com"
                  }
              ],
              "latitude": 40.7794366,
              "longitude": -73.96324400000003,
              "postal_code": "10028",
              "address_line_1": "1000 5th Avenue",
              "location_requirements": [
                  "no_elevator"
              ]
              
          }
      ],
      "destination_locations": [
          {
              "id": "cba321",
              "city": "San Francisco",
              "type": "commercial",
              "title": "Legion of Honor",
              "region": "CA",
              "country": "US",
              "contacts": [
                  {
                      "name": "Fred Bloggs",
                      "phone_numbers": [
                          {
                              "ext": "321",
                              "number": "4155554321",
                              "country_code": "+1"
                          }
                      ],
                      "primary_email": "fbloggs@example.com"
                  }
              ],
              "latitude": 37.7844661,
              "longitude": -122.50084190000001,
              "postal_code": "94121",
              "address_line_1": "100 34th Avenue",
              "special_instructions": "Delivery entry though gate 3"
          }
      ],
      "name": "Test Request",
      "request": {
          "request_type": "shipment",
          "customer_reference": "{\"example\":\"using this fields to store some json\"}",
          "insurance": "arta_transit_insurance",
          "additional_services": [
              "installation"
          ],
          "notes": "This could be an example of a delivery note from a user in your system"
      },
      "customer_reference": "This customer reference will be place onto the Job.",
      "estimated_start_time": {},
      "estimated_complete_time": {},
      "actual_start_time": "",
      "actual_complete_time": ""
  }

For more information regarding what's in the Job response, please view the full job schema

Cancelling a Job

Once a request has become a Job it cannot be cancelled.

Back to Top

Tracking Shipments

This section describes how to use the ARTA API to track parcel shipments. It can be used to track shipments that were not purchased via the API. This section covers using the ARTA API to obtain tracking information from most parcel carriers. Please note shipment carriers provide varying levels of tracking updates. For tracking information related to a Job generated by the system with an ARTA ID, it's more appropriate to call the Job endpoint to obtain the latest tracking information.

Process Flow and Calls

There are two ways to track a shipment, with the carrier name or without it. If you do not provide the carrier, the system will auto-detect the carrier from the tracking number. For some smaller carriers, this does not always work and it is therefore recommended that you use the carrier whenever possible. To use the carrier, you will need to know the tokenized name of the carrier the package was shipped with. This tokenized name, along with the tracking number, will then be used as part of the url scheme when making the tracking call. You will then receive back an array of the known tracking history of the shipment, ordered in time based descending order.

Obtaining Carrier Name Tokens

To obtain a list of the supported carriers and their tokens, make a GET request to the the metadata/carriers/ route.

Example Call

curl https://api.shiparta.com/metadata/carriers/ -H "Authorization: ARTA_APIKey 1234567890abcdef"
  

Example Response

[
      {
          "token": "fedex",
          "carrier_name": "FedEx"
      },
      {
          "token": "ups",
          "carrier_name": "UPS"
      }
  ]

For more information regarding this response, please view the full Carrier metadata schema

Making a Shipment Track Call

Shipment tracking calls are GET requests. You can use the auto-detect feature if the carrier is unknown, however, this works best for larger carrier companies as smaller carriers tracking number formats often overlap and therefore may return incorrect tracking information. It is then recommended that for smaller carriers, you provide the name in the token format provided by the metadata call above as well as the tracking number in order to obtain the proper tracking information from the desired carrier. The output they provide is the same.

The url scheme for an auto-detect track call is /tracking/<tracking_number>/

The url scheme for a carrier provided track call is: /tracking/<tokenized_carrier_name>/<tracking_number>/

Example calls

Without Carrier:

curl https://api.shiparta.com/tracking/1ZA9T4567890123450/ -H "Authorization: ARTA_APIKey 1234567890abcdef"
  

With Carrier:

curl https://api.shiparta.com/tracking/ups/1ZA9T4567890123450/ -H "Authorization: ARTA_APIKey 1234567890abcdef"
  

Example response

[
      {
          "carrier": "ups",
          "tracking_number": "1ZA9T4567890123450",
          "status": "TRANSIT",
          "status_details": "Your shipment has departed from the origin.",
          "status_date": "2019-04-24T19:42:30.716000Z",
          "city": "San Francisco",
          "state": "CA",
          "country": "US",
          "zip": "94103",
          "eta": "2019-04-28T21:47:30.695000Z",
          "substatus": null,
          "excepted": null
      },
      {
          "carrier": "ups",
          "tracking_number": "1ZA9T4567890123450",
          "status": "UNKNOWN",
          "status_details": "The carrier has received the electronic shipment information.",
          "status_date": "2019-04-23T17:37:30.716000Z",
          "city": "San Francisco",
          "state": "CA",
          "country": "US",
          "zip": "94103",
          "eta": "2019-04-28T21:47:30.695000Z",
          "substatus": null,
          "excepted": null
      }
  ]

For more information regarding this response, please view the full tracking response schema

Back to Top

Test Mode

In order to use the API in test mode, you need to use the test key provided to you by ARTA. You can use this key to make calls to the system and retrieve mocked data back. It should be noted that the data returned back in test mode (including all pricing, services, packing, disqualifications, number of quotes, type of quotes, etc.) is well structured and meaningful unto itself, but does not reflect those that the system may actually provide.

Test mode allows you to follow a full process workflow from start to finish. It allows you to have 1 stored request at a time. If you make a new request, the previous request will be replaced or make a delete call then the stored request will be cleared. There are also stubs available to you that allow you to see and interact with specific states of a request or job. The Extras stub that allows you to make purchase and recalculation calls, acting like a second stored request.

Since test mode is dictated by the test key, the urls are no different than that of the normal API. The metadata routes skip the test service and provide real data no matter what key you provide. It should be noted that only a few select service/packing/etc types can be used in test mode. If you try to use anything other than those, you will receive an error.

Using Your Test Key

Test keys and real keys look exactly the same. It is up to you to keep them separate and know what key is live and what key is for testing. There is no difference in using the test key. It should still be used in the header of every call.

Making Test Requests and Testing The Process Flow

The test service allows you to make an entire mock request, from start to finish. To begin this process, send a request JSON to the request endpoint. This will validate the structure and if invalid, return a 400. If the structure is valid it will then determine if it should be disqualified and if there is enough information to make purchasable. It will then return a response with an ID of BOOKABLE_REQUEST. For simplification purposes, the response only contains a single quote. You can then use this to retrieve the response using the GET request. You can then call the recalculate endpoint to recalculate the quote and the purchase endpoint to convert it into a Job. Once a Job, make a new request to replace the current.

Test Mode Limitations

Since the test mode uses data mocking to provide and interact with responses, it does come with a few limitations when compared to the actual API. All of the prices in test mode are static and may not reflect reality. Locations are not actually geolocated and when you provide an address it will not actually provide a real longitude and latitude; similarly, test mode doesn't handle these being sent into the system.

Currencies are ignored and responses are always given in USD (to see what a currency quote looks like, please refer to the INTERNATIONAL_FOREIGN_CURRENCY stub). Customs information and IDs are not generated for objects.

Test mode only supports the following in the request, anything else disqualifies the request:

Additional Services

Packing

Insurance

Object Limitations

Objects with any single dimension over 120in (302cm) or with a weight above 250lb (114kg) will be disqualified. If requesting insurance, then the combined object values cannot exceed a max value of $1M or the request will be disqualified.

Using the Test Stubs

Test stubs give you a real view of what the type of response actually looks like coming out of the system. To use the stubs simply use the stub name in place of the ARTA ID. While most stubs are static, the BOOKABLE_EXTRAS stub on the purchase and recalculate endpoints. Once this is converted to a Job, you need to call the delete method on the request in order to clear out the entry and reset the request. It should be noted that this is a special case for testing and is not the typical or expected behavior.

Request Stubs

The following are available request stubs:

Job Stubs

Using the BOOKABLE_EXTRAS Stub

Just like if you made your own request, you can use the BOOKABLE_EXTRAS stub on the purchase and recalculate endpoints. Once this is converted to a Job, you need to call the delete method on the Job in order to clear out the entry.

Test Tracking Calls

To test parcel tracking calls you can use the carrier as arta and the following stubs are available:

Back to Top

Appendix

Monetary Units and Currency

This section describes how monetary units (money), currency and exchange rates are represented within the system.

Representation

All monetary units in both inputs and outputs are represented as formatted strings. This is in effort to help avoid rounding or type conversion issues between different systems. Internally, we use a strict 100th place decimal system for storing and calculating all monetary units. Any partial units are rounded using a half up strategy. For example, 1.825 would be rounded to 1.83 whereas 1.824 would be rounded to 1.82.

Accompanying all monetary unit keys is a corrosponding currency the ISO 4217 three-letter alphabetic currency code that the corresponding unit is given in. For consistency, this field is always named the same as the monetary field appended with _currency. For example, a monetary field of amount will always be accompanied by a currency field of amount_currency This field can be use for display and/or conversion.

Currency Conversion Information

At time of quote request, one can provide a currency that you would like the quote to be in. Arta uses mid-market exchange rates based on USD to calculate totals. The rate will be provided back in the returning data at the top level. When checking out in a currency that is not USD, GBP or EUR an additional transaction fee may apply.

Dimensions

The system can handle dimensions in various formats.

Other units are not accepted at this time. The unit type field must always be included in the data. The system will return values in the same unit type that was given in the request. It is invalid to include the unit type within the dimension value field, for example these are all invalid {"height": "21 cm"}, {"width": "21\""}, {"depth": "3'4\""}.

Valid Input Formats

Dimension fields in the JSON data are accepted as both numerical or string types. Numerical type can be whole number or integers (1, 34, 987) as well as decimals or floating point numbers (1.25, 3.1765, 456.15). Strings can accept more complicated input. For example you can still present them using whole numbers ("124") or decimal numbers ("3.147"), but you can also use a fraction notation, for example "3 7/8" would represent 3 and seven eighths. (please note the required space between the whole number and the fraction) The system can also accept fractional unicode characters, for example "3 ½" and "3½" are both valid representations of 3 and one half. It should be noted that the system will do a conversion internally and may even round the units if it seems fit, but will not send fractions back except where provided in the original data if unmanipulated.

System Suggestions

This section is provided to you from the engineers at ARTA as suggestions for using the system. These can be opinionated suggestions, so please take them with a grain of salt.

Receiving Updates to Your Data

At this time, the system only sends out updates via email to the account that your API is tied to. Although we plan on adding notifications and webhooks soon, the system does not currently handle this. We suggest making the email address on your API account point to an inbox that can then be filtered and processed programmatically or setup a service to run periodically. In either case, you will need to pull the data manually from a GET request.

Providing Quote Estimations Up Front

Currently the system doesn't have a specific way to generate quote estimations. All quotes generated are done with the intent that they could be bookable. A way that we suggest doing this for users is to create a basic quote using a small, medium and large sized object to the closest large (relative) city and store them locally in your system. You can then use this most likely unpurchasable ballpark quote for all similar objects for all users in that area, letting them know that this is just an estimated price. This may save you from having to call the system unnecessarily for simple ballpark quotes.

For customers who may not live near a large city, it might be best to ask them for a postal code in order to get a ballpark on demand rather than providing this upfront. Or if you have this information already, obtain them asynchronously in the background.

Back to Top