Metadata Endpoints

The ARTA API provides endpoints that describe types and lists of options used within the core quote request and shipment APIs; these are grouped into the "metadata" namespace.

The metadata endpoints facilitate use cases such as:

  • discovering the valid options for key fields like object type or required to create a quote requests
  • fetching additional data and descriptions about the services included in a shipment
  • listing the currencies currently supported by the API
  • viewing the potential values for the shipment's status field

The data available in the metadata endpoints are expected to change relatively infrequently. As well, it is most likely that any changes will be additive—the introduction of new statuses, packing type options, email notification types, etc. As a result, it may be considered safe to periodically cache these responses in your systems to simplify your integration efforts.

API Reference

Metadata endpoints

Key endpoints and quote request fields

You can find the full list of metadata endpoints and their schema on the API reference site, but the following are critical for generating shipment quote requests and merit special attention:

  • Object types — returns the list of valid options for describing the type of object being shipped; these types correspond to both the request.objects.type (for example, art) and the request.objects.subtype (for example, painting_unframed) fields
  • Packing materials — returns the list of packing materials and container types supported in the ARTA API; you can use these in the request.objects.current_packing field to communicate whether and how each object is currently packed
  • Supported currencies — returns the list of currencies currently supported by the quote request API; this is used primarily in the request.currency field to indicate the currency in which you'd like to recieve quote and service fees; this is also used in the request.objects.value_currency along with request.objects.value to communicate the monetary value of an object in the quote request
  • Location access restrictions — returns the list of valid options for request.origin.access_restrictions and request.destination.access_restrictions; you should make use of these fields to indicate known limitations and features at a location that may impact collection or delivery efforts
  • Services — returns the list of requestable services ARTA offers in the course of generating a shipment quote request; you may request one of these services (for example, a condition report at the destination) by including the services' IDS in the request.additional_services field