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:

Responses

  • 201 application/json

    response

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

      The id of a service.

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

    • destination object | null
      Hide destination attributes Show destination attributes
    • 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.

    • origin object
      Hide origin attributes Show origin attributes
    • The primary method by which payment to Arta will be handled for any shipment booked through this hosted session

      Values are checkout or invoicing.

    • A private access token for this resource. It 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

    • A brief and unique string identifier for the request resource

    • status string
    • The URL the user will be redirected to after a Arta Booking session is completed

    • url string | null

      The Arta Booking web URL for this Hosted Session

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

  • 400 application/json

    Bad Request

    Hide response attribute Show response attribute object

    Basic Error

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":{"origin":{"city":"Brooklyn","title":"Gallery","region":"NY","country":"string","contacts":[{"name":"Rachel Egistrar","phone_number":"(212) 234-5678","email_address":"registrar@example.com"}],"postal_code":"11249","address_line_1":"87 Richardson St","address_line_2":"string","address_line_3":"string"},"objects":[{"depth":"3","value":"2500","width":"15","height":"32","weight":"3.0","details":{"notes":"Artist signature in the lower left corner","title":"Black Rectangle","creator":"Bob Smithson","creation_date":"1980"},"subtype":"painting_unframed","weight_unit":"lb","value_currency":"USD","current_packing":["no_packing"],"public_reference":"Round Smithson work","internal_reference":"Accession ID: 823","unit_of_measurement":"in"}],"insurance":"arta_transit_insurance","cancel_url":"http://example.com/cancelled","success_url":"http://example.com/success","shipping_notes":"New customer","public_reference":"Order #1437","internal_reference":"Purchase Order: 2801","additional_services":["signature_delivery"]}}'
{
  "hosted_session": {
    "origin": {
      "city": "Brooklyn",
      "title": "Gallery",
      "region": "NY",
      "country": "string",
      "contacts": [
        {
          "name": "Rachel Egistrar",
          "phone_number": "(212) 234-5678",
          "email_address": "registrar@example.com"
        }
      ],
      "postal_code": "11249",
      "address_line_1": "87 Richardson St",
      "address_line_2": "string",
      "address_line_3": "string"
    },
    "objects": [
      {
        "depth": "3",
        "value": "2500",
        "width": "15",
        "height": "32",
        "weight": "3.0",
        "details": {
          "notes": "Artist signature in the lower left corner",
          "title": "Black Rectangle",
          "creator": "Bob Smithson",
          "creation_date": "1980"
        },
        "subtype": "painting_unframed",
        "weight_unit": "lb",
        "value_currency": "USD",
        "current_packing": [
          "no_packing"
        ],
        "public_reference": "Round Smithson work",
        "internal_reference": "Accession ID: 823",
        "unit_of_measurement": "in"
      }
    ],
    "insurance": "arta_transit_insurance",
    "cancel_url": "http://example.com/cancelled",
    "success_url": "http://example.com/success",
    "shipping_notes": "New customer",
    "public_reference": "Order #1437",
    "internal_reference": "Purchase Order: 2801",
    "additional_services": [
      "signature_delivery"
    ]
  }
}
{
  "hosted_session": {
    "request_id": "2a12d676-0f23-4a9b-b322-eff460510417"
  }
}
Response examples (201)
{
  "id": 42,
  "url": "https://book.arta.io/b/42/6f76b6e1-ce25-43a9-b4ea-2ceaac24ec7e",
  "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": [
    {
      "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)
{
  "errors": {
    "detail": "string"
  }
}