List Hosted Sessions

GET /hosted_sessions

Retrieve a paginated collection of hosted sessions belonging to your organization

Headers

  • Authorization string Required

    Authorize your API calls with an Arta API token

Query parameters

  • page integer

    Page number of the results to fetch.

    Default value is 1.

  • page_size integer

    Results per page (max 50)

    Default value is 20.

Responses

  • 200 application/json

    A paginated collection of hosted sessions

    Hide headers attributes Show headers attributes
    • content-type string
    • x-arta-request-id string

      A unique identifier for the Arta API call

    Hide response attributes Show response attributes object
    • items array[object]
      Hide items attributes Show items attributes object
      • additional_services array[string]

        Any desired services, such as unpacking, installation, etc. can be sent through in the request and will be treated as if that requested service is required. Requested services may disqualify certain segments of shipping services offered by Arta depending on location and object details.

      • can_user_confirm_object_dimensions boolean

        Determines whether your customer can verify and update object dimension information when completing an inbound booking session.

      • cancel_url string

        The URL the user will be redirected to after an Arta Booking session is cancelled

      • created_at string
      • destination object | null
        Hide destination attributes Show destination attributes object | null
        • access_restrictions array[string]

          Id of location restriction type

        • address_line_1 string

          First line of address

        • address_line_2 string | null

          Second line of address

        • address_line_3 string | null

          Third line of address

        • city string

          City

        • contacts array[object]

          An list of contacts at the location

          Hide contacts attributes Show contacts attributes object
          • email_address string
          • name string
          • phone_number string
        • country string

          The ISO 3166-1 alpha-2 country code of the current or last known location if available

          Minimum length is 2, maximum length is 2.

        • id string

          The location id

        • postal_code string

          The postal code

        • region string

          Political region name, for US states and Canada provinces, use 2 letter abbreviations

        • title string

          The title or name of the location

      • id integer(int64)
      • insurance string | null

        The id of an insurance type. If requesting Arta insurance, object values must be provided.

      • internal_reference string | null

        This field can be used to pass through any data about the request you may want returned unaltered for your own later usage

        Maximum length is 255.

      • objects array[object]

        A list of objects to be shipped

        Hide objects attributes Show objects attributes object
        • components array[object]

          A list of components in the object. Should be used only with a prepacked_box object subtype.

          When components are present, the object value must equal the sum of component values.

          Hide components attributes Show components attributes object
          • customs object
            Hide customs attributes Show customs attributes object
            • country_of_origin string

              The ISO 3166-1 alpha-2 country code where the object was made or manufactured

              Minimum length is 2, maximum length is 2.

            • hs_code string

              The Harmonized System code for the object. This is a 6-10 digit code used to classify traded products

            • medium string

              The medium of the object. This is a description of the material or materials used to create the object

            • temporary_admission boolean

              Select true if the goods are currently in the country under a temporary admission declaration

          • details object
            Hide details attributes Show details attributes object
            • creation_date string

              Details about the timing in which an object was created

            • creator string

              The creator of the object

            • notes string

              Any notes about the item

            • title string

              The object title

          • id string(uuid)

            The id of the component in UUID format

          • internal_reference string

            This field can be used to pass through any data that you may want returned unaltered for your own later usage

            Maximum length is 255.

          • public_reference string

            A client defined name for the object. The value provided for public_reference may be presented in notification emails and on shipment detail pages

            Maximum length is 255.

          • type string

            The object component type ID. Options are defined in the Object Component types metadata endpoint

            Format should match the following pattern: ^[0-9a-z_]{1,56}$.

          • value string

            Format should match the following pattern: ^(0|([1-9]+[0-9]*))(\.[0-9]{1,2})?$.

          • value_currency string

            ISO 4217 three-letter alphabetic currency code. Options are defined in the Currencies metadata endpoint

            Minimum length is 3, maximum length is 3. Format should match the following pattern: ^[A-Z]{3}$. Default value is USD.

        • current_packing array[string]

          A list of packing subtype IDs describing how the item is currently packed

        • customs object
          Hide customs attributes Show customs attributes object
          • country_of_origin string

            The ISO 3166-1 alpha-2 country code where the object was made or manufactured

            Minimum length is 2, maximum length is 2.

          • hs_code string

            The Harmonized System code for the object. This is a 6-10 digit code used to classify traded products

          • medium string

            The medium of the object. This is a description of the material or materials used to create the object

          • temporary_admission boolean

            Select true if the goods are currently in the country under a temporary admission declaration

        • depth string

          The depth of the object

        • details object
          Hide details attributes Show details attributes object
          • creation_date string

            Details about the timing in which an object was created

          • creator string

            The creator of the object

          • is_cites boolean

            Set to true if the object is governed by the Convention on International Trade in Endangered Species of Wild Fauna and Flora

            Default value is false.

          • is_fragile boolean

            Set this flag to true is the item is fragile. This may effect packing and handling costs

            Default value is false.

          • materials array[string] Deprecated

            A list of IDs describing the types of materials used

          • notes string

            Any notes about the item

          • title string

            The object title

        • height string

          The height of the object

        • id integer(int64)
        • images array[string(uri)]

          A list image urls of the object

        • internal_reference string

          This field can be used to pass through any data that you may want returned unaltered for your own later usage

          Maximum length is 255.

        • public_reference string

          A client defined name for the object. The value provided for public_reference may be presented in notification emails and on shipment detail pages

          Maximum length is 255.

        • subtype string

          The object subtype ID. Options are defined in the Object types metadata endpoint

          Format should match the following pattern: ^[0-9a-z_]{1,56}$.

        • type string

          The object type id

          Format should match the following pattern: ^[0-9a-z_]{1,56}$.

        • unit_of_measurement string

          Values are in or cm.

        • value string

          Format should match the following pattern: ^(0|([1-9]+[0-9]*))(\.[0-9]{1,2})?$.

        • value_currency string

          ISO 4217 three-letter alphabetic currency code. Options are defined in the Currencies metadata endpoint

          Minimum length is 3, maximum length is 3. Format should match the following pattern: ^[A-Z]{3}$. Default value is USD.

        • weight string

          The weight of the object

        • weight_unit string

          The unit of the object

          Values are lb or kg.

        • width string

          The width of the object

      • origin object
        Hide origin attributes Show origin attributes object
        • access_restrictions array[string] Deprecated

          Id of location restriction type

        • address_line_1 string

          First line of address

        • address_line_2 string | null

          Second line of address

        • address_line_3 string | null

          Third line of address

        • city string

          City

        • contacts array[object]

          A list of contacts at the location

          Hide contacts attributes Show contacts attributes object
          • email_address string
          • name string Required
          • phone_number string
        • country string Required

          The ISO 3166-1 alpha-2 country code of the current or last known location if available

          Minimum length is 2, maximum length is 2.

        • postal_code string

          The postal code

        • region string

          Political region name, for US states and Canada provinces, use 2 letter abbreviations

        • title string

          The title or name of the location

      • payment_process string

        The primary method by which payment to Arta will be handled for any shipment booked through this hosted session

        Values are checkout or invoicing.

      • preferred_parcel_transport_services array[string] | null

        Optionally instruct the Arta API to filter Parcel and Self Ship quotes for specific transport services. For example, if you would prefer to only return ground quotes, you can set this field to ["ground"] The list of valid transport service IDs is available at the /metadata/parcel_transport_services endpoint.

      • preferred_quote_types array[string]

        An optional field presenting the list of quote types the caller instructed Arta to return as part of the hosted session

      • private_token string

        A private access token for this resource. It is used to generate the private URL for the hosted session

      • public_reference string | null

        A client defined name for the resource. The value provided for the public_reference field may appear in notification emails and public web pages

        Maximum length is 255.

      • quoting_strategy string

        The quoting strategy used when creating quote requests for this booking session. Determines whether the API returns a single best-rate option per transport speed or multiple carrier options for comparison

        Maximum length is 255. Values are best_rate or compare_carriers. Default value is best_rate.

      • shipping_notes string | null

        This field can be used to pass through any notes to Arta that a customer might want to provide about the request

      • shortcode string

        A brief and unique string identifier for the request resource

      • status string
      • success_url string

        The URL the user will be redirected to after an Arta Booking session is completed

      • tags array[object]

        A list of tags associated with this hosted session

        Hide tags attributes Show tags attributes object
        • color string

          The hexadecimal color code for the tag, without the leading #.

          Minimum length is 6, maximum length is 6. Format should match the following pattern: ^[0-9A-F]{6}$.

        • created_at string(date-time)

          A NaiveDatetime-formatted timestamp describing when the resource was created with microsecond precision

        • created_by integer(int64) | null

          The user ID associated with the user who created the tag when applicable.

        • description string | null

          An optional, brief description for this tag.

          Maximum length is 255.

        • id string(uuid)

          The id of the tag in UUID format

        • is_active boolean

          Indicates whether or not the tag is active. Inactive tags may not be associated to new resources

        • name string

          The name for the tag. It may contain lower case letters, dashes, and alphanumeric characters only. The maximum character count is 50.

          Maximum length is 50. Format should match the following pattern: ^[a-z0-9-]{1,50}$.

        • updated_at string(date-time)

          A NaiveDatetime-formatted timestamp describing when the resource was last updated with microsecond precision

        • updated_by integer(int64) | null

          The user ID associated with the last user to edit the tag when applicable.

      • type string

        The type of the hosted session

      • updated_at string
      • url string | null

        The Arta Booking web URL for this Hosted Session

    • metadata object
      Hide metadata attributes Show metadata attributes object
      • page integer(int64)
      • page_size integer(int64)
      • total_count integer(int64)
GET /hosted_sessions
curl \
 --request GET 'https://api.arta.io/hosted_sessions' \
 --header "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response examples (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "items": [
    {
      "id": 42,
      "url": "https://book.arta.io/b/42/6f76b6e1-ce25-43a9-b4ea-2ceaac24ec7e",
      "tags": [],
      "type": "booking",
      "origin": {
        "city": "New York",
        "title": "Warehouse",
        "region": "NY",
        "country": "US",
        "contacts": [
          {
            "name": "Mary Quinn Sullivan",
            "phone_number": "(333) 333-3333",
            "email_address": "mary@example.com"
          }
        ],
        "postal_code": "10019",
        "address_line_1": "11 W 53rd St",
        "address_line_2": null,
        "address_line_3": null,
        "access_restrictions": []
      },
      "status": "new",
      "objects": [
        {
          "id": 12346,
          "type": "client_package",
          "depth": "2",
          "value": "15000",
          "width": "10",
          "height": "10.5",
          "images": [],
          "weight": "3.5",
          "details": {
            "notes": null,
            "title": null,
            "creator": null,
            "is_cites": false,
            "materials": [],
            "is_fragile": false,
            "creation_date": null
          },
          "subtype": "prepacked_box",
          "components": [
            {
              "id": "1f26b6e1-ce25-43a9-b4ea-2ceaac24ec3a",
              "type": "painting_framed",
              "value": "15000",
              "customs": {
                "medium": "oil on canvas",
                "hs_code": "123456",
                "country_of_origin": "US",
                "temporary_admission": true
              },
              "details": {
                "notes": "Artist signature in the lower left corner",
                "title": "Black Rectangle",
                "creator": "Bob Smithson",
                "creation_date": "1980"
              },
              "value_currency": "USD",
              "public_reference": "Round Smithson work",
              "internal_reference": "Accession ID: 823"
            }
          ],
          "weight_unit": "lb",
          "value_currency": "USD",
          "current_packing": [
            "cardboard_box"
          ],
          "public_reference": null,
          "internal_reference": null,
          "unit_of_measurement": "in"
        },
        {
          "id": 12345,
          "type": "art",
          "depth": "2",
          "value": "100.00",
          "width": "36",
          "height": "24",
          "images": [],
          "weight": "1",
          "customs": {
            "medium": "oil on canvas",
            "hs_code": "123456",
            "country_of_origin": "US",
            "temporary_admission": true
          },
          "details": {
            "notes": "notes",
            "title": "It's just jazz",
            "creator": "Robert Irwin",
            "is_cites": false,
            "materials": [],
            "is_fragile": false,
            "creation_date": null
          },
          "subtype": "painting_unframed",
          "components": [],
          "weight_unit": "lb",
          "value_currency": "USD",
          "current_packing": [],
          "public_reference": null,
          "internal_reference": null,
          "unit_of_measurement": "in"
        }
      ],
      "insurance": null,
      "shortcode": "DEMO-BA9SVZ",
      "cancel_url": "http://example.com/cancel",
      "created_at": "2021-01-21T17:22:08.818747",
      "updated_at": "2021-01-21T17:22:10.129653",
      "destination": null,
      "success_url": "http://example.com/success",
      "private_token": "6f76b6e1-ce25-43a9-b4ea-2ceaac24ec7e",
      "shipping_notes": null,
      "payment_process": "invoicing",
      "public_reference": null,
      "quoting_strategy": "best_rate",
      "internal_reference": null,
      "additional_services": [
        "signature_delivery"
      ],
      "preferred_quote_types": [],
      "can_user_confirm_object_dimensions": false
    }
  ],
  "metadata": {
    "page": 1,
    "page_size": 20,
    "total_count": 1
  }
}