Create a Hosted Session

POST /hosted_sessions

Create a hosted session resource to generate an Arta Booking url.

This endpoint expects one of two versions of the hosted_session schema:

  • You may send a hosted_session object with a subset of the fields required for generating quote requests via the Arta API. With this schema, you must minimally include valid objects and origin details in your API call. Additionally, you may provide a success_url and a cancel_url to determine where Arta will redirect the user after the session is complete

  • Alternatively, you may share an existing Quote Request by sending a hosted_session object with the corresponding request's request_id. This will create an Arta Booking session for the request

Use the private url in the successful hosted session response to direct your users to the Arta Booking web page so that they may configure and book their own shipment.

Headers

  • Authorization string Required

    Authorize your API calls with an Arta API token

application/json

Body object

One of:
BookingSession object ShareRequest object

Responses

  • 201 application/json

    the created hosted sessions

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

      The id of a service.

    • cancel_url string

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

    • created_at string
    • destination object | null

      Additional properties are allowed.

      Hide destination attributes Show destination attributes object | null
    • 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
      • current_packing array[string]

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

      • depth string

        The depth of the object

      • details object

        Additional properties are allowed.

        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}$.

      • 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

      Additional properties are allowed.

      Hide origin attributes Show origin attributes object
    • 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_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.

    • 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.

    • updated_at string
    • url string | null

      The Arta Booking web URL for this Hosted Session
  • 400 application/json

    Bad Request

    Hide headers attributes Show headers attributes
    Hide response attribute Show response attribute object
    • errors object

      Additional properties are allowed.

      Hide errors attribute Show errors attribute object
POST /hosted_sessions 
curl \
 -X POST https://api.arta.io/hosted_sessions \
 -H "Content-Type: application/json" \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y" \
 -d '{"hosted_session":{"additional_services":["signature_delivery"],"cancel_url":"http://example.com/cancelled","destination":{"access_restrictions":["string"],"address_line_1":"87 Richardson St","address_line_2":"string","address_line_3":"string","city":"Brooklyn","contacts":[{"email_address":"docs@arta.io","name":"Contact Name","phone_number":"646 828 7333"}],"country":"US","postal_code":"11211","region":"NY","title":"Gallery"},"insurance":"arta_transit_insurance","internal_reference":"Purchase Order: 2801","objects":[{"current_packing":["no_packing"],"depth":"3","details":{"creation_date":"1980","creator":"Bob Smithson","is_cites":false,"is_fragile":false,"materials":["canvas"],"notes":"Artist signature in the lower left corner","title":"Black Rectangle"},"height":"32","images":["http://example.com/image.jpg"],"internal_reference":"Accession ID: 823","public_reference":"Round Smithson work","subtype":"painting_unframed","unit_of_measurement":"in","value":"2500.00","value_currency":"USD","weight":"3.0","weight_unit":"lb","width":"15"}],"origin":{"access_restrictions":["string"],"address_line_1":"87 Richardson St","address_line_2":"string","address_line_3":"string","city":"Brooklyn","contacts":[{"email_address":"docs@arta.io","name":"Contact Name","phone_number":"646 828 7333"}],"country":"US","postal_code":"11211","region":"NY","title":"Gallery"},"preferred_quote_types":["parcel"],"public_reference":"Order #1437","shipping_notes":"New customer","success_url":"http://example.com/success","tags":["spring-jewelry-sale"]}}'
Request examples 
# Headers
Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y

# Payload
{
  "hosted_session": {
    "additional_services": [
      "signature_delivery"
    ],
    "cancel_url": "http://example.com/cancelled",
    "destination": {
      "access_restrictions": [
        "string"
      ],
      "address_line_1": "87 Richardson St",
      "address_line_2": "string",
      "address_line_3": "string",
      "city": "Brooklyn",
      "contacts": [
        {
          "email_address": "docs@arta.io",
          "name": "Contact Name",
          "phone_number": "646 828 7333"
        }
      ],
      "country": "US",
      "postal_code": "11211",
      "region": "NY",
      "title": "Gallery"
    },
    "insurance": "arta_transit_insurance",
    "internal_reference": "Purchase Order: 2801",
    "objects": [
      {
        "current_packing": [
          "no_packing"
        ],
        "depth": "3",
        "details": {
          "creation_date": "1980",
          "creator": "Bob Smithson",
          "is_cites": false,
          "is_fragile": false,
          "materials": [
            "canvas"
          ],
          "notes": "Artist signature in the lower left corner",
          "title": "Black Rectangle"
        },
        "height": "32",
        "images": [
          "http://example.com/image.jpg"
        ],
        "internal_reference": "Accession ID: 823",
        "public_reference": "Round Smithson work",
        "subtype": "painting_unframed",
        "unit_of_measurement": "in",
        "value": "2500.00",
        "value_currency": "USD",
        "weight": "3.0",
        "weight_unit": "lb",
        "width": "15"
      }
    ],
    "origin": {
      "access_restrictions": [
        "string"
      ],
      "address_line_1": "87 Richardson St",
      "address_line_2": "string",
      "address_line_3": "string",
      "city": "Brooklyn",
      "contacts": [
        {
          "email_address": "docs@arta.io",
          "name": "Contact Name",
          "phone_number": "646 828 7333"
        }
      ],
      "country": "US",
      "postal_code": "11211",
      "region": "NY",
      "title": "Gallery"
    },
    "preferred_quote_types": [
      "parcel"
    ],
    "public_reference": "Order #1437",
    "shipping_notes": "New customer",
    "success_url": "http://example.com/success",
    "tags": [
      "spring-jewelry-sale"
    ]
  }
}
# Headers
Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y

# Payload
{
  "hosted_session": {
    "request_id": "string"
  }
}
Response examples (201) 
{
  "id": 42,
  "url": "https://book.arta.io/b/42/6f76b6e1-ce25-43a9-b4ea-2ceaac24ec7e",
  "tags": [],
  "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": 12345,
      "type": "art",
      "depth": "2",
      "value": "100.00",
      "width": "36",
      "height": "24",
      "images": [],
      "weight": "1",
      "details": {
        "notes": "notes",
        "title": "It's just jazz",
        "creator": "Robert Irwin",
        "is_cites": false,
        "materials": [],
        "is_fragile": false,
        "creation_date": null
      },
      "subtype": "painting_unframed",
      "weight_unit": "lb",
      "value_currency": "USD",
      "current_packing": [],
      "public_reference": null,
      "internal_reference": null,
      "unit_of_measurement": "in"
    }
  ],
  "insurance": null,
  "shortcode": "DEMO-B49SVZ",
  "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,
  "internal_reference": null,
  "additional_services": [
    "signature_delivery"
  ],
  "preferred_quote_types": []
}
Response examples (400) 
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "errors": {
    "detail": "string"
  }
}