ARTA Public API
2021-01-01

The ARTA Public API provides quote generation, transport booking, and tracking capabilities. Additionally the API enables ARTA partner organizations to configure email and webhook notifications for their accounts.

This is the documentation for version 2021-01-01 of the API. Last update on Oct 3, 2022.

Base URL
https://api.arta.io

Authentication

The ARTA API accepts server-to-server communications authenticated by API keys. Your API keys are self-managed and unique to your organization.

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


$ curl \ 

 -X GET https://api.arta.io/shipments \ 

 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"

List API Keys

GET /api_keys

Retrieve a paginated collection of API Keys belonging to your Organization

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Query parameters

  • page_size integer

    Results per page (max 50)

    Default value is 20.

  • page integer

    Page number of the results to fetch.

    Default value is 1.

Responses

GET /api_keys
curl \
 -X GET https://api.arta.io/api_keys \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "items": [
    {
      "id": 42,
      "created_at": "2020-10-15T19:50:02.914779",
      "is_testing": true,
      "token": "******************eQ0Rqp",
      "updated_at": "2020-10-15T19:50:02.914779"
    },
    {
      "id": 41,
      "created_at": "2020-08-07T03:49:45.000000",
      "is_testing": false,
      "token": "******************VBiYj6",
      "updated_at": "2020-08-07T03:49:45.000000"
    }
  ],
  "metadata": {
    "page": 1,
    "page_size": 20,
    "total_count": 2
  }
}

Create an API Key

POST /api_keys

You can create mulitple API keys for your organization. All API keys operate on either Live or Test modes.

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Body

  • api_key object
    • is_testing boolean

      Whether this API Key should operate in Live or Test mode.

      Default value is false.

Responses

POST /api_keys
curl \
 -X POST https://api.arta.io/api_keys \
 -H "Content-Type: application/json" \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y" \
 -d '{"api_key":{"is_testing":true}}'
Request example
# Headers
Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y

# Payload
{
  "api_key": {
    "is_testing": true
  }
}
Response example (201)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "id": 42,
  "created_at": "2020-10-15T19:50:02.914779",
  "is_testing": true,
  "token": "a8dG3tcspo9dinqePjcQ0Rqp",
  "updated_at": "2020-10-15T19:50:02.914779"
}
Response example (400)
{
  "errors": {
    "detail": "string"
  }
}

Get an API Key

GET /api_keys/{api_key_id}

Get an API Key

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

Responses

GET /api_keys/{api_key_id}
curl \
 -X GET https://api.arta.io/api_keys/{api_key_id} \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "id": 42,
  "created_at": "2020-10-15T19:50:02.914779",
  "is_testing": true,
  "token": "a8dG3tcspo9dinqePjcQ0Rqp",
  "updated_at": "2020-10-15T19:50:02.914779"
}
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

Delete an API Key

DELETE /api_keys/{api_key_id}

Delete an API Key belonging to your Organization

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

Responses

DELETE /api_keys/{api_key_id}
curl \
 -X DELETE https://api.arta.io/api_keys/{api_key_id} \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

List Attachments

GET /attachments

Retrieve a paginated collection of Attachments belonging to your Organization

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Query parameters

  • page_size integer

    Results per page (max 50)

    Default value is 20.

  • page integer

    Page number of the results to fetch.

    Default value is 1.

Responses

GET /attachments
curl \
 -X GET https://api.arta.io/attachments \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "items": [
    {
      "created_at": "2021-10-27T16:48:38.657228",
      "request_id": "506d79b6-1e5e-4e8c-a266-74658fdaf4ee",
      "shipment_id": "string",
      "id": 1942,
      "upload_id": 4791,
      "updated_at": "2021-10-27T16:48:38.657228"
    }
  ],
  "metadata": {
    "page": 1,
    "page_size": 20,
    "total_count": 1
  }
}

Create an Attachment

POST /attachments

The attachment resource connects uploads on ARTA to shipment or request resources. Attached uploads are visible in the ARTA Dashobard under the "Documents" tab on the shipment and request detail pages.

Each upload may be attached to many requests or shipments. Each request or shipment may have many associated uploads.

To create an attachment via the API you can must send an authenticated request to the POST /attachments endpoint with a body that includes one of two different payload schema.

To attach an upload to a shipment, the attachment payload must include upload_id and shipment_id attributes. This payload must not include a request_id attribute. For example:

{
    "attachment": {
        "shipment_id": "506d79b6-1e5e-4e8c-a266-74658fdaf4ee",
        "upload_id": 5285
    }
}

To attach an upload to a request, the attachment payload must include upload_id and request_id attributes. This payload must not include a shipment_id attribute. For example:

{
    "attachment": {
        "request_id": "506d79b6-1e5e-4e8c-a266-74658fdaf4ee",
        "upload_id": 5285
    }
}

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Body

  • attachment object Required
    • upload_id integer Required

      The integer ID of the upload resource being attached

    • The string ID of the request resource being associated to an upload. Do not include a request_id in the attachment parameters if you are associating a shipment

    • The string ID of the shipment resource being associated to an upload. Do not include a shipment_id in the attachment parameters if you are associating a shipment

Responses

  • 201 object

    response

    • request_id string | null

      The string ID of the request resource associated to an upload via this attachment. Null if this attachment associate a shipment

    • shipment_id string | null

      The string ID of the shipment resource associated to an upload via this attachment. Null if this attachment associate a request

    • id integer
    • upload_id integer Required

      The integer ID of the Upload resource associated with either a shipment or request via this attachment

  • 400 object

    Bad Request

POST /attachments
curl \
 -X POST https://api.arta.io/attachments \
 -H "Content-Type: application/json" \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y" \
 -d '{"attachment":{"upload_id":4791,"request_id":"506d79b6-1e5e-4e8c-a266-74658fdaf4ee"}}'
Request example
# Headers
Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y

# Payload
{
  "attachment": {
    "upload_id": 4791,
    "request_id": "506d79b6-1e5e-4e8c-a266-74658fdaf4ee"
  }
}
Response example (201)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "created_at": "2021-10-27T16:48:38.657228",
  "request_id": "506d79b6-1e5e-4e8c-a266-74658fdaf4ee",
  "shipment_id": null,
  "id": 1942,
  "upload_id": 4791,
  "updated_at": "2021-10-27T16:48:38.657228"
}
Response example (400)
{
  "errors": {
    "detail": "string"
  }
}

Get an Attachment

GET /attachments/{attachment_id}

Retrieve an existing Attachment

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

Responses

GET /attachments/{attachment_id}
curl \
 -X GET https://api.arta.io/attachments/{attachment_id} \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "created_at": "2021-10-27T16:48:38.657228",
  "request_id": "506d79b6-1e5e-4e8c-a266-74658fdaf4ee",
  "shipment_id": "string",
  "id": 1942,
  "upload_id": 4791,
  "updated_at": "2021-10-27T16:48:38.657228"
}
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

Delete an Attachment

DELETE /attachments/{attachment_id}

Delete an Attachment

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

Responses

DELETE /attachments/{attachment_id}
curl \
 -X DELETE https://api.arta.io/attachments/{attachment_id} \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

List Email Rules

GET /email_rules

Retrieve a paginated collection of Email Rules belonging to your Organization

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Query parameters

  • page_size integer

    Results per page (max 50)

    Default value is 20.

  • page integer

    Page number of the results to fetch.

    Default value is 1.

Responses

GET /email_rules
curl \
 -X GET https://api.arta.io/email_rules \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "items": [
    {
      "email_notification_id": "complete",
      "id": 7,
      "created_at": "2020-10-14T15:29:06.263371",
      "recipients": [
        "destination"
      ],
      "updated_at": "2020-10-14T15:29:06.263371"
    }
  ],
  "metadata": {
    "page": 1,
    "page_size": 20,
    "total_count": 1
  }
}

Create an Email Rule

POST /email_rules

response

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Body

Responses

POST /email_rules
curl \
 -X POST https://api.arta.io/email_rules \
 -H "Content-Type: application/json" \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y" \
 -d '{"email_rule":{"email_notification_id":"booking","recipients":["destination","origin"]}}'
Request example
# Headers
Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y

# Payload
{
  "email_rule": {
    "email_notification_id": "booking",
    "recipients": [
      "destination",
      "origin"
    ]
  }
}
Response example (201)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "email_notification_id": "complete",
  "id": 7,
  "created_at": "2020-10-14T15:29:06.263371",
  "recipients": [
    "destination"
  ],
  "updated_at": "2020-10-14T15:29:06.263371"
}
Response example (400)
{
  "errors": {
    "detail": "string"
  }
}

Get an Email Rule

GET /email_rules/{email_rule_id}

Retrieve an existing Email Rule request

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

Responses

GET /email_rules/{email_rule_id}
curl \
 -X GET https://api.arta.io/email_rules/{email_rule_id} \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "email_notification_id": "complete",
  "id": 7,
  "created_at": "2020-10-14T15:29:06.263371",
  "recipients": [
    "destination"
  ],
  "updated_at": "2020-10-14T15:29:06.263371"
}
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

Delete an Email Rule

DELETE /email_rules/{email_rule_id}

Delete an Email Rule

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

Responses

DELETE /email_rules/{email_rule_id}
curl \
 -X DELETE https://api.arta.io/email_rules/{email_rule_id} \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

Update an Email Rule

PATCH /email_rules/{email_rule_id}

Update an existing Email Rule request

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

Body

Responses

PATCH /email_rules/{email_rule_id}
curl \
 -X PATCH https://api.arta.io/email_rules/{email_rule_id} \
 -H "Content-Type: application/json" \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y" \
 -d '{"email_rule":{"recipients":["destination","origin"]}}'
Request example
# Headers
Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y

# Payload
{
  "email_rule": {
    "recipients": [
      "destination",
      "origin"
    ]
  }
}
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "email_notification_id": "complete",
  "id": 7,
  "created_at": "2020-10-14T15:29:06.263371",
  "recipients": [
    "destination"
  ],
  "updated_at": "2020-10-14T15:29:06.263371"
}
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

List Email Subscriptions

GET /email_subscriptions

Retrieve a paginated collection of Email Subscriptions belonging to your Organization

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Query parameters

  • page_size integer

    Results per page (max 50)

    Default value is 20.

  • page integer

    Page number of the results to fetch.

    Default value is 1.

Responses

GET /email_subscriptions
curl \
 -X GET https://api.arta.io/email_subscriptions \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "items": [
    {
      "email_address": "notifications@shiparta.com",
      "email_notification_ids": [
        "booking",
        "complete",
        "scheduling"
      ],
      "id": 6,
      "created_at": "2020-10-14T15:25:48.298369",
      "name": "ARTA Notifications",
      "updated_at": "2020-10-14T15:25:48.298369"
    }
  ],
  "metadata": {
    "page": 1,
    "page_size": 20,
    "total_count": 1
  }
}

Create an Email Subscription

POST /email_subscriptions

response

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Body

    • The email_address for this Email Subscription.

    • The list of Email Notification IDs for this Email Subscription.

    • name string

      The name for this Email Subscription. This name will be used in conjunction with the email address field to build the recipient when delivering email notifications.

Responses

POST /email_subscriptions
curl \
 -X POST https://api.arta.io/email_subscriptions \
 -H "Content-Type: application/json" \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y" \
 -d '{"email_subscription":{"email_address":"hello@shiparta.com","email_notification_ids":["booking","scheduling"],"name":"Arta"}}'
Request example
# Headers
Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y

# Payload
{
  "email_subscription": {
    "email_address": "hello@shiparta.com",
    "email_notification_ids": [
      "booking",
      "scheduling"
    ],
    "name": "Arta"
  }
}
Response example (201)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "email_address": "notifications@shiparta.com",
  "email_notification_ids": [
    "booking",
    "complete",
    "scheduling"
  ],
  "id": 6,
  "created_at": "2020-10-14T15:25:48.298369",
  "name": "ARTA Notifications",
  "updated_at": "2020-10-14T15:25:48.298369"
}
Response example (400)
{
  "errors": {
    "detail": "string"
  }
}

Get an Email Subscription

GET /email_subscriptions/{email_subscription_id}

Retrieve an existing Email Subscription request

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

Responses

GET /email_subscriptions/{email_subscription_id}
curl \
 -X GET https://api.arta.io/email_subscriptions/{email_subscription_id} \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "email_address": "notifications@shiparta.com",
  "email_notification_ids": [
    "booking",
    "complete",
    "scheduling"
  ],
  "id": 6,
  "created_at": "2020-10-14T15:25:48.298369",
  "name": "ARTA Notifications",
  "updated_at": "2020-10-14T15:25:48.298369"
}
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

Delete an Email Subscription

DELETE /email_subscriptions/{email_subscription_id}

Delete an Email Subscription

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

Responses

DELETE /email_subscriptions/{email_subscription_id}
curl \
 -X DELETE https://api.arta.io/email_subscriptions/{email_subscription_id} \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

Update an Email Subscription

PATCH /email_subscriptions/{email_subscription_id}

Update an existing Email Subscription request

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

Body

Responses

PATCH /email_subscriptions/{email_subscription_id}
curl \
 -X PATCH https://api.arta.io/email_subscriptions/{email_subscription_id} \
 -H "Content-Type: application/json" \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y" \
 -d '{"email_subscription":{"recipients":["destination","origin"]}}'
Request example
# Headers
Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y

# Payload
{
  "email_subscription": {
    "recipients": [
      "destination",
      "origin"
    ]
  }
}
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "email_address": "notifications@shiparta.com",
  "email_notification_ids": [
    "booking",
    "complete",
    "scheduling"
  ],
  "id": 6,
  "created_at": "2020-10-14T15:25:48.298369",
  "name": "ARTA Notifications",
  "updated_at": "2020-10-14T15:25:48.298369"
}
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

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_size integer

    Results per page (max 50)

    Default value is 20.

  • page integer

    Page number of the results to fetch.

    Default value is 1.

Responses

  • 200 object

    A collection of Hosted Sessions

    • items array[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
      • 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
      • 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

    • metadata object
GET /hosted_sessions
curl \
 -X GET https://api.arta.io/hosted_sessions \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "items": [
    {
      "additional_services": [],
      "cancel_url": "http://example.com/cancel",
      "created_at": "2021-06-23T16:39:10.530122",
      "destination": null,
      "id": 42,
      "insurance": null,
      "internal_reference": null,
      "objects": [
        {
          "current_packing": [],
          "depth": "2",
          "details": {
            "creation_date": null,
            "creator": "Robert Irwin",
            "is_cites": false,
            "is_fragile": false,
            "materials": [],
            "notes": "notes",
            "title": "It's just jazz"
          },
          "height": "24",
          "images": [],
          "internal_reference": null,
          "public_reference": null,
          "subtype": "painting_unframed",
          "type": "art",
          "unit_of_measurement": "in",
          "value": "100.00",
          "value_currency": "USD",
          "weight": "1",
          "weight_unit": "lb",
          "width": "36"
        }
      ],
      "origin": {
        "city": "brooklyn",
        "country": "US",
        "postal_code": "11249",
        "region": "NY"
      },
      "private_token": "335318bc-f855-4a57-8203-2061930eab1f",
      "public_reference": null,
      "shipping_notes": null,
      "shortcode": "DEMO-B2M7JC",
      "status": "new",
      "success_url": "http://example.com/success",
      "updated_at": "2021-06-23T16:39:10.530122",
      "url": "https://book.arta.io/b/42/335318bc-f855-4a57-8203-2061930eab1f"
    }
  ],
  "metadata": {
    "page": 1,
    "page_size": 20,
    "total_count": 1
  }
}

Create a Hosted Session

POST /hosted_sessions

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

This endpoint expects a subset of the fields required for generating quote requests via the ARTA API. 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.

Use the private URL in the hosted session response to direct your users to the ARTA Booking web page to configure and book their own shipment.

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Body

    • additional_services array[string]

      The id of a service.

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

    • The destination location for the shipment quote request

      • access_restrictions array[string]

        A list of access restricition IDs describing physical properties for the location. Options are defined in the Location Access Restrictions metadata endpoint

      • The first line of the location's street address

        Maximum length is 255.

      • address_line_2 string | null

        The second line of the location's street address

      • address_line_3 string | null

        The third line of the location's street address

      • city string

        The name of the city for the location

        Maximum length is 255.

      • region string

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

        Maximum length is 255.

      • postal_code string Required

        The postal code for the location

        Maximum length is 255.

      • country string Required

        The ISO 3166-1 alpha-2 country code of the location

        Maximum length is 255.

      • title string

        The name for the location

        Maximum length is 255.

      • contacts array[object]

        The contact details for the location

    • The ID of the requested ARTA insurance type. Options are defined in the Insurances metadata endpoint

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

    • objects array[object] Required
      • 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.

      • current_packing array[string]

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

      • depth string Required

        The depth of the object

      • details object
        • materials array[string] Deprecated

          A list of IDs describing the types of materials used

        • 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

        • is_fragile boolean

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

          Default value is false.

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

      • height string Required

        The height of the object

      • images array[string(uri)]

        A list image urls of the object

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

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

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

      • width string Required

        The width of the object

      • unit_of_measurement string Required

        Values are in or cm.

      • weight string

        The weight of the object

      • weight_unit string Required

        The unit of the object

        Values are lb or kg.

      • value string Required

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

      • value_currency string Required

        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.

    • origin object Required

      The originating location for the shipment quote request

      • access_restrictions array[string]

        A list of access restricition ids describing physical properties of the location. Options are defined in the Location Access Restrictions metadata endpoint

      • The first line of the location's street address

        Maximum length is 255.

      • address_line_2 string | null

        The second line of the location's street address

      • address_line_3 string | null

        The third line of the location's street address

      • city string

        The name of the city for the location

        Maximum length is 255.

      • region string

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

        Maximum length is 255.

      • postal_code string Required

        The postal code for the location

        Maximum length is 255.

      • country string Required

        The ISO 3166-1 alpha-2 country code of the location

        Maximum length is 255.

      • title string

        The name for the location

        Maximum length is 255.

      • contacts array[object]

        The contact details for the location

    • preferred_quote_types array[string] | null

      Optionally instruct the ARTA API to return a subset of quote types for the requests generated through this hosted session. For example if you would prefer to only return Select quotes, you can set this field to ["select"] The list valid quote type IDs are available at the /metadata/quotes endpoint.

    • A client defined name for the request. The value provided for the public_reference field may appear in notification emails and shipment detail pages

      Maximum length is 255.

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

    • The URL the user will be redirected to after a ARTA Booking session is completed

Responses

  • 201 object

    response

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

    Bad Request

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":["stairs_only"],"address_line_1":"11 W 53rd St","address_line_2":"string","address_line_3":"string","city":"New York","region":"NY","postal_code":"10019","country":"US","title":"Warehouse","contacts":[{"name":"Mary Quinn Sullivan","email_address":"mary@example.com","phone_number":"(333) 333-3333"}]},"insurance":"arta_transit_insurance","internal_reference":"Purchase Order: 2801","objects":[{"internal_reference":"Accession ID: 823","current_packing":["no_packing"],"depth":"3","details":{"materials":["canvas"],"creation_date":"1980","creator":"Bob Smithson","notes":"Artist signature in the lower left corner","title":"Black Rectangle","is_fragile":false,"is_cites":false},"height":"32","images":["http://example.com/image.jpg"],"public_reference":"Round Smithson work","subtype":"painting_unframed","width":"15","unit_of_measurement":"in","weight":"3.0","weight_unit":"lb","value":"2500","value_currency":"USD"}],"origin":{"access_restrictions":["no_packing"],"address_line_1":"87 Richardson St","address_line_2":"string","address_line_3":"string","city":"Brooklyn","region":"NY","postal_code":"11249","country":"string","title":"Gallery","contacts":[{"name":"Rachel Egistrar","email_address":"registrar@example.com","phone_number":"(212) 234-5678"}]},"preferred_quote_types":["parcel"],"public_reference":"Order #1437","shipping_notes":"New customer","success_url":"http://example.com/cancelled"}}'
Request example
# Headers
Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y

# Payload
{
  "hosted_session": {
    "additional_services": [
      "signature_delivery"
    ],
    "cancel_url": "http://example.com/cancelled",
    "destination": {
      "access_restrictions": [
        "stairs_only"
      ],
      "address_line_1": "11 W 53rd St",
      "address_line_2": "string",
      "address_line_3": "string",
      "city": "New York",
      "region": "NY",
      "postal_code": "10019",
      "country": "US",
      "title": "Warehouse",
      "contacts": [
        {
          "name": "Mary Quinn Sullivan",
          "email_address": "mary@example.com",
          "phone_number": "(333) 333-3333"
        }
      ]
    },
    "insurance": "arta_transit_insurance",
    "internal_reference": "Purchase Order: 2801",
    "objects": [
      {
        "internal_reference": "Accession ID: 823",
        "current_packing": [
          "no_packing"
        ],
        "depth": "3",
        "details": {
          "materials": [
            "canvas"
          ],
          "creation_date": "1980",
          "creator": "Bob Smithson",
          "notes": "Artist signature in the lower left corner",
          "title": "Black Rectangle",
          "is_fragile": false,
          "is_cites": false
        },
        "height": "32",
        "images": [
          "http://example.com/image.jpg"
        ],
        "public_reference": "Round Smithson work",
        "subtype": "painting_unframed",
        "width": "15",
        "unit_of_measurement": "in",
        "weight": "3.0",
        "weight_unit": "lb",
        "value": "2500",
        "value_currency": "USD"
      }
    ],
    "origin": {
      "access_restrictions": [
        "no_packing"
      ],
      "address_line_1": "87 Richardson St",
      "address_line_2": "string",
      "address_line_3": "string",
      "city": "Brooklyn",
      "region": "NY",
      "postal_code": "11249",
      "country": "string",
      "title": "Gallery",
      "contacts": [
        {
          "name": "Rachel Egistrar",
          "email_address": "registrar@example.com",
          "phone_number": "(212) 234-5678"
        }
      ]
    },
    "preferred_quote_types": [
      "parcel"
    ],
    "public_reference": "Order #1437",
    "shipping_notes": "New customer",
    "success_url": "http://example.com/cancelled"
  }
}
Response example (201)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "additional_services": [
    "signature_delivery"
  ],
  "cancel_url": "http://example.com/cancel",
  "created_at": "2021-01-21T17:22:08.818747",
  "destination": null,
  "id": 42,
  "insurance": null,
  "internal_reference": null,
  "objects": [
    {
      "current_packing": [],
      "depth": "2",
      "details": {
        "creation_date": null,
        "creator": "Robert Irwin",
        "is_cites": false,
        "is_fragile": false,
        "materials": [],
        "notes": "notes",
        "title": "It's just jazz"
      },
      "height": "24",
      "images": [],
      "internal_reference": null,
      "public_reference": null,
      "subtype": "painting_unframed",
      "type": "art",
      "unit_of_measurement": "in",
      "value": "100.00",
      "value_currency": "USD",
      "weight": "1",
      "weight_unit": "lb",
      "width": "36"
    }
  ],
  "origin": {
    "access_restrictions": [],
    "address_line_1": "11 W 53rd St",
    "address_line_2": null,
    "address_line_3": null,
    "city": "New York",
    "contacts": [
      {
        "email_address": "mary@example.com",
        "name": "Mary Quinn Sullivan",
        "phone_number": "(333) 333-3333"
      }
    ],
    "country": "US",
    "postal_code": "10019",
    "region": "NY",
    "title": "Warehouse"
  },
  "payment_process": "invoicing",
  "preferred_quote_types": [],
  "private_token": "6f76b6e1-ce25-43a9-b4ea-2ceaac24ec7e",
  "public_reference": null,
  "shipping_notes": null,
  "shortcode": "DEMO-B49SVZ",
  "status": "new",
  "success_url": "http://example.com/success",
  "updated_at": "2021-01-21T17:22:10.129653",
  "url": "https://book.arta.io/b/42/6f76b6e1-ce25-43a9-b4ea-2ceaac24ec7e"
}
Response example (400)
{
  "errors": {
    "detail": "string"
  }
}

Get a Hosted Session

GET /hosted_sessions/{hosted_session_id}

Retrieve an existing hosted session resource

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

Responses

  • 200 object

    Successful Hosted Session response

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

  • 404 object

    Resource Not Found

GET /hosted_sessions/{hosted_session_id}
curl \
 -X GET https://api.arta.io/hosted_sessions/{hosted_session_id} \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "additional_services": [
    "signature_delivery"
  ],
  "cancel_url": "http://example.com/cancel",
  "created_at": "2021-01-21T17:22:08.818747",
  "destination": null,
  "id": 42,
  "insurance": null,
  "internal_reference": null,
  "objects": [
    {
      "current_packing": [],
      "depth": "2",
      "details": {
        "creation_date": null,
        "creator": "Robert Irwin",
        "is_cites": false,
        "is_fragile": false,
        "materials": [],
        "notes": "notes",
        "title": "It's just jazz"
      },
      "height": "24",
      "images": [],
      "internal_reference": null,
      "public_reference": null,
      "subtype": "painting_unframed",
      "type": "art",
      "unit_of_measurement": "in",
      "value": "100.00",
      "value_currency": "USD",
      "weight": "1",
      "weight_unit": "lb",
      "width": "36"
    }
  ],
  "origin": {
    "access_restrictions": [],
    "address_line_1": "11 W 53rd St",
    "address_line_2": null,
    "address_line_3": null,
    "city": "New York",
    "contacts": [
      {
        "email_address": "mary@example.com",
        "name": "Mary Quinn Sullivan",
        "phone_number": "(333) 333-3333"
      }
    ],
    "country": "US",
    "postal_code": "10019",
    "region": "NY",
    "title": "Warehouse"
  },
  "payment_process": "invoicing",
  "preferred_quote_types": [],
  "private_token": "6f76b6e1-ce25-43a9-b4ea-2ceaac24ec7e",
  "public_reference": null,
  "shipping_notes": null,
  "shortcode": "DEMO-B49SVZ",
  "status": "new",
  "success_url": "http://example.com/success",
  "updated_at": "2021-01-21T17:22:10.129653",
  "url": "https://book.arta.io/b/42/6f76b6e1-ce25-43a9-b4ea-2ceaac24ec7e"
}
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

Cancel a Hosted Session

PATCH /hosted_sessions/{hosted_session_id}/cancel

Cancel an existing hosted session resource

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

Responses

  • 200 object

    Successfully cancelled Hosted Session response

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

  • 404 object

    Resource Not Found

PATCH /hosted_sessions/{hosted_session_id}/cancel
curl \
 -X PATCH https://api.arta.io/hosted_sessions/{hosted_session_id}/cancel \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "additional_services": [
    "signature_delivery"
  ],
  "cancel_url": "http://example.com/cancel",
  "created_at": "2021-01-21T17:22:08.818747",
  "destination": null,
  "id": 42,
  "insurance": null,
  "internal_reference": null,
  "objects": [
    {
      "current_packing": [],
      "depth": "2",
      "details": {
        "creation_date": null,
        "creator": "Robert Irwin",
        "is_cites": false,
        "is_fragile": false,
        "materials": [],
        "notes": "notes",
        "title": "It's just jazz"
      },
      "height": "24",
      "images": [],
      "internal_reference": null,
      "public_reference": null,
      "subtype": "painting_unframed",
      "type": "art",
      "unit_of_measurement": "in",
      "value": "100.00",
      "value_currency": "USD",
      "weight": "1",
      "weight_unit": "lb",
      "width": "36"
    }
  ],
  "origin": {
    "access_restrictions": [],
    "address_line_1": "11 W 53rd St",
    "address_line_2": null,
    "address_line_3": null,
    "city": "New York",
    "contacts": [
      {
        "email_address": "mary@example.com",
        "name": "Mary Quinn Sullivan",
        "phone_number": "(333) 333-3333"
      }
    ],
    "country": "US",
    "postal_code": "10019",
    "region": "NY",
    "title": "Warehouse"
  },
  "payment_process": "invoicing",
  "preferred_quote_types": [],
  "private_token": "6f76b6e1-ce25-43a9-b4ea-2ceaac24ec7e",
  "public_reference": null,
  "shipping_notes": null,
  "shortcode": "DEMO-B49SVZ",
  "status": "new",
  "success_url": "http://example.com/success",
  "updated_at": "2021-01-21T17:22:10.129653",
  "url": "https://book.arta.io/b/42/6f76b6e1-ce25-43a9-b4ea-2ceaac24ec7e"
}
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

List invoice payment records

GET /invoice_payments

Retrieve a paginated collection of Invoice Payments belonging to your Organization

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Query parameters

  • page_size integer

    Results per page (max 50)

    Default value is 20.

  • page integer

    Page number of the results to fetch.

    Default value is 1.

Responses

GET /invoice_payments
curl \
 -X GET https://api.arta.io/invoice_payments \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "items": [
    {
      "amount": "502.25",
      "amount_currency": "USD",
      "created_at": "2021-02-19T19:09:57.971464",
      "id": 1,
      "invoice_id": 11,
      "payment_id": 1,
      "shipment_id": "45360593-6c6c-44ab-8a17-0fd198fff058",
      "updated_at": "2021-02-19T19:09:57.971464"
    }
  ],
  "metadata": {
    "page": 1,
    "page_size": 20,
    "total_count": 1
  }
}

Get an Invoice Payment record

GET /invoice_payments/{invoice_payment_id}

Retrieve an existing Invoice Payment record

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

Responses

GET /invoice_payments/{invoice_payment_id}
curl \
 -X GET https://api.arta.io/invoice_payments/{invoice_payment_id} \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "amount": "502.25",
  "amount_currency": "USD",
  "created_at": "2021-02-19T19:09:57.971464",
  "id": 1,
  "invoice_id": 11,
  "payment_id": 1,
  "shipment_id": "45360593-6c6c-44ab-8a17-0fd198fff058",
  "updated_at": "2021-02-19T19:09:57.971464"
}
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

List invoice records

GET /invoices

Retrieve a paginated collection of Invoices belonging to your Organization

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Query parameters

  • page_size integer

    Results per page (max 50)

    Default value is 20.

  • page integer

    Page number of the results to fetch.

    Default value is 1.

Responses

GET /invoices
curl \
 -X GET https://api.arta.io/invoices \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "items": [
    {
      "amount_owed": "276.91",
      "amount_owed_currency": "USD",
      "amount_paid": "276.91",
      "amount_paid_currency": "USD",
      "created_at": "2021-03-10T20:15:34.096258",
      "invoice_url": null,
      "id": 2216,
      "issued_on": "2021-03-10",
      "shipment_id": "53d6bdec-1eae-46e2-97c2-3e56b1a1095d",
      "status": "closed",
      "updated_at": "2021-03-10T20:16:10.202836"
    }
  ],
  "metadata": {
    "page": 1,
    "page_size": 20,
    "total_count": 1
  }
}

Get an Invoice record

GET /invoices/{invoice_id}

Retrieve an existing Invoice record

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

Responses

GET /invoices/{invoice_id}
curl \
 -X GET https://api.arta.io/invoices/{invoice_id} \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "amount_owed": "276.91",
  "amount_owed_currency": "USD",
  "amount_paid": "276.91",
  "amount_paid_currency": "USD",
  "created_at": "2021-03-10T20:15:34.096258",
  "invoice_url": null,
  "id": 2216,
  "issued_on": "2021-03-10",
  "shipment_id": "53d6bdec-1eae-46e2-97c2-3e56b1a1095d",
  "status": "closed",
  "updated_at": "2021-03-10T20:16:10.202836"
}
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

List Log records

GET /logs

Retrieve a paginated collection of Log records belonging to your Organization

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Query parameters

  • page_size integer

    Results per page (max 50)

    Default value is 20.

  • page integer

    Page number of the results to fetch.

    Default value is 1.

Responses

GET /logs
curl \
 -X GET https://api.arta.io/logs \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "items": [
    {
      "api_key_id": 1,
      "arta_version": "2020-10-22",
      "end_at": "2020-10-23T20:34:28.816433",
      "id": 320,
      "created_at": "2020-10-23T20:34:29.066599",
      "method": "POST",
      "path": "/requests",
      "request_id": "FkC5WHWtbZuuUtcAArFx",
      "start_at": "2020-10-23T20:34:16.928374",
      "status": 200,
      "updated_at": "2020-10-23T20:34:29.066599"
    }
  ],
  "metadata": {
    "page": 1,
    "page_size": 20,
    "total_count": 1
  }
}

Get a Log record

GET /logs/{log_id}

Retrieve an existing Log record

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

  • log_id integer Required

    log_id parameter

Responses

GET /logs/{log_id}
curl \
 -X GET https://api.arta.io/logs/{log_id} \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "api_key_id": 1,
  "arta_version": "2020-10-22",
  "end_at": "2020-10-23T20:34:28.816433",
  "id": 320,
  "created_at": "2020-10-23T20:34:29.066599",
  "method": "POST",
  "path": "/requests",
  "query_params": "{}",
  "request_body": "",
  "request_id": "FkC5WHWtbZuuUtcAArFx",
  "response_body": "",
  "start_at": "2020-10-23T20:34:16.928374",
  "status": 200,
  "updated_at": "2020-10-23T20:34:29.066599"
}
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

API Versions

GET /metadata/api_versions

Retrieve the list of versions for ARTA's API.

A version may be passed along in API calls as an arta-version request header to target a specific API version.

Additionally, you may set a default API version on your Organization to fallback to a particular version.

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Responses

  • 200 array[object]

    A collection of API Versions

    • A long form description

    • authentication array[string]

      The list of authentication schema supported by this API version

    • id string

      The ID representing the resource

    • status string

      Indicates whether the API version is active, beta, or deprecated

GET /metadata/api_versions
curl \
 -X GET https://api.arta.io/metadata/api_versions \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
[
  {
    "description": "A key-authenticated API Version released on October 22, 2020.",
    "authentication": [
      "api_key"
    ],
    "id": "2020-10-22",
    "status": "active"
  }
]

Currencies

GET /metadata/currencies

Retrieve the list of currencies supported by ARTA's API

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Responses

  • 200 array[object]

    A collection of currencies

    • symbol string

      The symbol used to denote that a number is a monetary value in a particular currency

    • id string

      The ID representing the resource

    • name string

      A brief label for the currency

GET /metadata/currencies
curl \
 -X GET https://api.arta.io/metadata/currencies \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
[
  {
    "symbol": "$",
    "id": "USD",
    "name": "US Dollar"
  }
]

Email Notifications

GET /metadata/email_notifications

ARTA's email notifications are optional and configurable. You can use email rules and email subscriptions to dictate whether ARTA delivers them on your behalf to either internal or external recipients.

The Email Notifications metadata endpoint lists the current notification types and their properties.

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Responses

GET /metadata/email_notifications
curl \
 -X GET https://api.arta.io/metadata/email_notifications \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
[
  {
    "description": "Delivered when a shipment is confirmed.",
    "optional_recipients": [
      "destination"
    ],
    "id": "booking",
    "name": "Booking Confirmation"
  }
]

Insurance

GET /metadata/insurances

The list of insurance types supported by ARTA's API.

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Responses

GET /metadata/insurances
curl \
 -X GET https://api.arta.io/metadata/insurances \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
[
  {
    "description": "ARTA full risk coverage transit insurance.",
    "id": "arta_transit_insurance",
    "name": "ARTA Full Risk"
  }
]

Location Access Restrictions Deprecated

GET /metadata/location_access_restrictions

Retrieve the list of valid Location Access Restriction objects for origin and destination locations.

The "Create a Quote Request" endpoint accepts a list of Location Access Restriction IDs for each location.

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Responses

GET /metadata/location_access_restrictions
curl \
 -X GET https://api.arta.io/metadata/location_access_restrictions \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
[
  {
    "description": "The location can only be accessed by elevator",
    "id": "elevator_only",
    "name": "Only Elevator"
  }
]

Object Materials Deprecated

GET /metadata/object_materials

Retrieve the list of valid object materials

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Responses

GET /metadata/object_materials
curl \
 -X GET https://api.arta.io/metadata/object_materials \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
[
  {
    "description": "a strong, coarse unbleached cloth made from hemp, flax, cotton, or a similar yarn",
    "id": "canvas",
    "name": "Canvas"
  }
]

Object Types

GET /metadata/objects

The list of object types supported by ARTA's API.

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Responses

GET /metadata/objects
curl \
 -X GET https://api.arta.io/metadata/objects \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
[
  {
    "description": "Works of art various media including paintings, sculpture, or works on paper.",
    "id": "art",
    "name": "Works of art",
    "subtypes": [
      {
        "description": "A painting that is framed behind a glass face.",
        "id": "painting_framed_glass",
        "name": "Painting (framed with glass)"
      }
    ]
  }
]

Package Statuses

GET /metadata/package_statuses

The list of possible statuses for a package in a shipment on ARTA.

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Responses

GET /metadata/package_statuses
curl \
 -X GET https://api.arta.io/metadata/package_statuses \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
[
  {
    "description": "Item has shipped from originating and is en route to its destination",
    "id": "transit",
    "name": "Transit"
  }
]

Packing Types

GET /metadata/packings

The list of packing types supported by ARTA's API.

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Responses

GET /metadata/packings
curl \
 -X GET https://api.arta.io/metadata/packings \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
[
  {
    "description": "Object is packed in plastic or bubble only",
    "id": "soft_wrap",
    "name": "Soft Wrap",
    "subtypes": [
      {
        "description": "Wraped in dartek film.",
        "id": "dartek_only",
        "name": "Dartek only"
      }
    ]
  }
]

Parcel Transport Services

GET /metadata/parcel_transport_services

The list of parcel transport services and their descriptions. The id and name fields are present in ARTA Parcel quote request and shipment service responses. The description field provides additional context about the differences between each transport service.

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Responses

GET /metadata/parcel_transport_services
curl \
 -X GET https://api.arta.io/metadata/parcel_transport_services \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
[
  {
    "description": "Delivers the following business day once shipped. Available in the contiguous US and Puerto Rico.",
    "id": "next_day_air",
    "name": "Next Day Air"
  }
]

Payment Process types

GET /metadata/payment_process_types

The list of shipment payment process types supported by ARTA's API.

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Responses

GET /metadata/payment_process_types
curl \
 -X GET https://api.arta.io/metadata/payment_process_types \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
[
  {
    "description": "The total is paid to ARTA through an ARTA Checkout payment.",
    "id": "checkout",
    "name": "Checkout"
  }
]

Quote Types

GET /metadata/quotes

The list of Quote types provided by ARTA.

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Responses

GET /metadata/quotes
curl \
 -X GET https://api.arta.io/metadata/quotes \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
[
  {
    "description": "Specialized climate-controlled transportation operated by trained technicians from wall-to-wall",
    "id": "premium",
    "name": "ARTA Premium"
  }
]

Quote Request Statuses

GET /metadata/request_statuses

The list of statuses for a quote request resources.

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Responses

GET /metadata/request_statuses
curl \
 -X GET https://api.arta.io/metadata/request_statuses \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
[
  {
    "description": "Eligible shipment quotes have been added to the request",
    "id": "quoted",
    "name": "Quoted"
  }
]

Services

GET /metadata/services

The list of shipment services supported by ARTA's API.

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Responses

GET /metadata/services
curl \
 -X GET https://api.arta.io/metadata/services \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
[
  {
    "description": "All handling for items at location and in transit.",
    "id": "handling",
    "name": "Handling Services",
    "subtypes": [
      {
        "description": "All installation services.",
        "id": "installation",
        "name": "Installation",
        "sub_subtypes": [
          {
            "description": "Object assembly at the destination",
            "id": "assembly",
            "is_requestable": true,
            "name": "Assembly"
          }
        ]
      }
    ]
  }
]

Shipment Statuses

GET /metadata/shipment_statuses

The list of statuses for a shipment on ARTA.

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Responses

GET /metadata/shipment_statuses
curl \
 -X GET https://api.arta.io/metadata/shipment_statuses \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
[
  {
    "description": "A quote has been booked and is awaiting confirmation by an ARTA logistics specialist",
    "id": "pending",
    "name": "Pending"
  }
]

Get an Organization

GET /organization

Retrieve the Organization associated with the API Key in the Authorization header

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Responses

GET /organization
curl \
 -X GET https://api.arta.io/organization \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "api_version": "2020-10-22",
  "id": 42,
  "created_at": "2020-10-15T19:50:02.914779",
  "name": "ARTA",
  "updated_at": "2020-10-15T19:50:02.914779"
}
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

Update an Organization

PATCH /organization

Update the Organization associated with the API Key in the Authorization header

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Body

  • webhook object
    • The fallback API Version to be used as a default when API calls associated with this Organization do not include an Arta-Version header

    • name string

      The name for this Organization.

Responses

PATCH /organization
curl \
 -X PATCH https://api.arta.io/organization \
 -H "Content-Type: application/json" \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y" \
 -d '{"webhook":{"api_version":"2020-10-22","name":"Arta"}}'
Request example
# Headers
Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y

# Payload
{
  "webhook": {
    "api_version": "2020-10-22",
    "name": "Arta"
  }
}
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "api_version": "2020-10-22",
  "id": 42,
  "created_at": "2020-10-15T19:50:02.914779",
  "name": "ARTA",
  "updated_at": "2020-10-15T19:50:02.914779"
}
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

List payment records

GET /payments

Retrieve a paginated collection of Payments belonging to your Organization

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Query parameters

  • page_size integer

    Results per page (max 50)

    Default value is 20.

  • page integer

    Page number of the results to fetch.

    Default value is 1.

Responses

GET /payments
curl \
 -X GET https://api.arta.io/payments \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "items": [
    {
      "amount": "502.25",
      "amount_currency": "USD",
      "context": "hosted_checkout",
      "created_at": "2021-02-19T19:09:57.954437",
      "id": 1,
      "paid_on": "2021-02-19",
      "updated_at": "2021-02-19T19:09:57.954437"
    }
  ],
  "metadata": {
    "page": 1,
    "page_size": 20,
    "total_count": 1
  }
}

Get an Payment record

GET /payments/{payment_id}

Retrieve an existing Payment record

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

Responses

GET /payments/{payment_id}
curl \
 -X GET https://api.arta.io/payments/{payment_id} \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "amount": "502.25",
  "amount_currency": "USD",
  "context": "hosted_checkout",
  "created_at": "2021-02-19T19:09:57.954437",
  "id": 1,
  "paid_on": "2021-02-19",
  "updated_at": "2021-02-19T19:09:57.954437"
}
Response example (404)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

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

List Request records

GET /requests

Retrieve a paginated collection of Quote request records belonging to your Organization

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Query parameters

  • page_size integer

    Results per page (max 50)

    Default value is 20.

  • page integer

    Page number of the results to fetch.

    Default value is 1.

Responses

  • 200 object

    A collection of Quote Request records

    • items array[object]
      • bookable object

        Communicates whether the quotes generated for this request may be booked into shipments

        • missing array[string]

          A list of fields required for the request to be bookable

        • ready boolean

          Returns true if the quotes in this request may be booked

          Default value is true.

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

      • A minimal representation of the destination address for the request

      • hosted_session_id integer | null

        The ID of the HostedSession through which this request was created

      • id string

        The ID for this request

      • insurance string | null

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

        Values are null or arta_transit_insurance.

      • internal_reference string | null

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

      • log_request_id string | null

        An identifier for the API call that created this resource

      • The count of objects in this request

      • origin object

        A minimal representation of the origin address for the request

        • city string | null

          The origin address city

        • country string

          The origin address country in 2-digit ISO 3166-1 alpha-2 format

        • postal_code string | null

          The origin address postal code

        • region string | null

          The origin address region

      • 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

      • quote_types array[string]

        The IDs of the quote types generated for this request

        Values are parcel, premium, select, or self_ship.

      • A brief string identifier for this shipment

      • status string

        The status for this shipment

        Values are quoted, in_progress, closed, disqualified, expired, cancelled, or pending.

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

    • metadata object
GET /requests
curl \
 -X GET https://api.arta.io/requests \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y"
Response example (200)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "items": [
    {
      "bookable": {
        "missing": [],
        "ready": true
      },
      "created_at": "2021-01-21T21:00:29.568665",
      "destination": {
        "city": "New York",
        "country": "US",
        "postal_code": "11249",
        "region": "NY"
      },
      "hosted_session_id": 724,
      "id": "6b12c76a-5217-4cd6-82d8-7aa5265ebaad",
      "insurance": null,
      "internal_reference": null,
      "object_count": 1,
      "origin": {
        "city": "New York",
        "country": "US",
        "postal_code": "10019",
        "region": "NY"
      },
      "public_reference": null,
      "quote_types": [
        "parcel",
        "select",
        "premium"
      ],
      "shortcode": "DEMO-R29NAW",
      "status": "closed",
      "updated_at": "2021-01-21T21:00:58.484566"
    }
  ],
  "metadata": {
    "page": 1,
    "page_size": 20,
    "total_count": 1
  }
}

Create a Quote Request

POST /requests

The first step to booking a shipment on ARTA is to create a quote request. This quote request provides ARTA with all the necessary transport details for us to price your eventual shipment.

ARTA will return eligible quotes for your shipment across ARTA's Premium, Selecct, and Parcel quote types. If any quote types are ineligible given your logistic details, those will be noted in the disqualifications response.

You must minimally include objects, origin, and destination details in your API call for ARTA to successfully price the transport.

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

  • Optionally set a timeout boundary in milliseconds for creating quote requests.

    While ARTA takes great care to return quotes quickly, several external services consumed during the process of creating quotes have varying response times. The Arta-Quote-Timeout header is particularly useful if your integration requires requests to return within a given time frame. When the timeout is reached, the ARTA API will stop any tasks in progress and return the quotes that have already been completed. If building quotes for a particular quote type is incomplete at timeout, the API will return a disqualification message for that quote type with a client_timeout_reached reason_code.

Body

  • request object Required
    • additional_services array[string]

      The id of a service.

    • currency string

      The currency that the quote should be returned in. Formatted as 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.

    • destination object Required

      The destination location for the shipment quote request

      • access_restrictions array[string]

        A list of access restricition IDs describing physical properties for the location. Options are defined in the Location Access Restrictions metadata endpoint

      • The first line of the location's street address

        Maximum length is 255.

      • The second line of the location's street address

        Maximum length is 255.

      • The third line of the location's street address

        Maximum length is 255.

      • city string

        The name of the city for the location

        Maximum length is 255.

      • region string

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

        Maximum length is 255.

      • postal_code string Required

        The postal code for the location

        Maximum length is 255.

      • country string Required

        The ISO 3166-1 alpha-2 country code of the location

        Maximum length is 255.

      • title string

        The name for the location

        Maximum length is 255.

      • contacts array[object]

        The contact details for the location

    • The ID of the requested ARTA insurance type. Options are defined in the Insurances metadata endpoint

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

    • objects array[object] Required
      • 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.

      • current_packing array[string]

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

      • depth string Required

        The depth of the object

      • details object
        • materials array[string] Deprecated

          A list of IDs describing the types of materials used

        • 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

        • is_fragile boolean

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

          Default value is false.

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

      • height string Required

        The height of the object

      • images array[string(uri)]

        A list image urls of the object

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

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

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

      • width string Required

        The width of the object

      • unit_of_measurement string Required

        Values are in or cm.

      • weight string

        The weight of the object

      • weight_unit string Required

        The unit of the object

        Values are lb or kg.

      • value string Required

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

      • value_currency string Required

        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.

    • origin object Required

      The originating location for the shipment quote request

      • access_restrictions array[string]

        A list of access restricition ids describing physical properties of the location. Options are defined in the Location Access Restrictions metadata endpoint

      • The first line of the location's street address

        Maximum length is 255.

      • The second line of the location's street address

        Maximum length is 255.

      • The third line of the location's street address

        Maximum length is 255.

      • city string

        The name of the city for the location

        Maximum length is 255.

      • region string

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

        Maximum length is 255.

      • postal_code string Required

        The postal code for the location

        Maximum length is 255.

      • country string Required

        The ISO 3166-1 alpha-2 country code of the location

        Maximum length is 255.

      • title string

        The name for the location

        Maximum length is 255.

      • contacts array[object]

        The contact details for the location

    • Optionally instruct the ARTA API to return a subset of quote types for this request. For example if you would prefer to only return Select quotes for a particular request, you can set this field to ["select"] You can find all available quote type IDs at the /metadata/quotes endpoint.

    • A client defined name for the request. The value provided for the public_reference field may appear in notification emails and shipment detail pages

      Maximum length is 255.

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

Responses

  • 201 object

    response

    • additional_services array[string]

      The id of a service.

    • bookable object
      • ready boolean

        Returns true if the quotes in this request may be booked

      • missing array[string]

        A list of fields required for the request to be bookable

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

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

    • disqualifications array[object]

      The disqualifcation reason

    • hosted_session_id integer | null

      The ID of the HostedSession through which this shipment was created

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

    • The request ID for the API call that created the resource. This request ID maps to the Log resource's "request_id" field

    • The count of objects included in the initial request payload

    • objects array[object]
      • current_packing array[string]

        A list of packing subtype IDs describing how the item is currently packed. Options are defined in the Packing Types metadata endpoint

      • depth string

        The depth of the object

      • details object
        • creation_date string | null

          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. Options are defined in the Object Materials metadata endpoint

        • notes string

          Any notes about the object

        • title string

          The object title

      • height string

        The height of the object

      • images array[string(uri)]

        A list image urls of the object

      • internal_reference string | null

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

        Maximum length is 255.

      • public_reference string | null

        A user defined name of the object

        Maximum length is 255.

      • subtype string

        The object subtype id

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

      • width string

        The width of the object

      • weight string

        The height of the object

      • Values are in or cm.

      • value string

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

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

    • origin object
    • The primary method by which payment to ARTA will be handled for any shipment booked from this request

      Maximum length is 255. Values are checkout or invoicing.

    • An optional field presenting the list of quote types the caller instructed ARTA to return as part of the quote request

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

    • quote_types array[string]

      The id of a quote type

    • quotes array[object]

      The list of quotes returned for the request

      • id integer
        • amount string

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

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

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

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

      • included_services array[object]
      • optional_services array[object]
      • status string
      • total string

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

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

    • 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

      Values are quoted, in_progress, cancelled, closed, disqualified, expired, or pending.

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

  • 400 object

    Bad Request

POST /requests
curl \
 -X POST https://api.arta.io/requests \
 -H "Content-Type: application/json" \
 -H "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y" \
 -H "Arta-Quote-Timeout: 6000" \
 -d '{"request":{"additional_services":["origin_condition_check"],"currency":"USD","destination":{"access_restrictions":["stairs_only"],"address_line_1":"11 W 53rd St","address_line_2":"string","address_line_3":"string","city":"New York","region":"NY","postal_code":"10019","country":"US","title":"Gallery","contacts":[{"name":"Mary Quinn Sullivan","email_address":"mary@example.com","phone_number":"(333) 333-3333"}]},"insurance":"arta_transit_insurance","internal_reference":"Purchase Order: 2801","objects":[{"internal_reference":"Accession ID: 823","current_packing":["no_packing"],"depth":"3","details":{"materials":["canvas"],"creation_date":"1980","creator":"Bob Smithson","notes":"Artist signature in the lower left corner","title":"Black Rectangle","is_fragile":false,"is_cites":false},"height":"32","images":["http://example.com/image.jpg"],"public_reference":"Round Smithson work","subtype":"painting_unframed","width":"15","unit_of_measurement":"in","weight":"3.0","weight_unit":"lb","value":"2500","value_currency":"USD"}],"origin":{"access_restrictions":["non_paved"],"address_line_1":"87 Richardson St","address_line_2":"string","address_line_3":"string","city":"Brooklyn","region":"NY","postal_code":"11249","country":"US","title":"Warehouse","contacts":[{"name":"Rachel Egistrar","email_address":"registrar@example.com","phone_number":"(212) 123-4567"}]},"preferred_quote_types":["parcel"],"public_reference":"Order #1437","shipping_notes":"New customer"}}'
Request example
# Headers
Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y
Arta-Quote-Timeout: 6000

# Payload
{
  "request": {
    "additional_services": [
      "origin_condition_check"
    ],
    "currency": "USD",
    "destination": {
      "access_restrictions": [
        "stairs_only"
      ],
      "address_line_1": "11 W 53rd St",
      "address_line_2": "string",
      "address_line_3": "string",
      "city": "New York",
      "region": "NY",
      "postal_code": "10019",
      "country": "US",
      "title": "Gallery",
      "contacts": [
        {
          "name": "Mary Quinn Sullivan",
          "email_address": "mary@example.com",
          "phone_number": "(333) 333-3333"
        }
      ]
    },
    "insurance": "arta_transit_insurance",
    "internal_reference": "Purchase Order: 2801",
    "objects": [
      {
        "internal_reference": "Accession ID: 823",
        "current_packing": [
          "no_packing"
        ],
        "depth": "3",
        "details": {
          "materials": [
            "canvas"
          ],
          "creation_date": "1980",
          "creator": "Bob Smithson",
          "notes": "Artist signature in the lower left corner",
          "title": "Black Rectangle",
          "is_fragile": false,
          "is_cites": false
        },
        "height": "32",
        "images": [
          "http://example.com/image.jpg"
        ],
        "public_reference": "Round Smithson work",
        "subtype": "painting_unframed",
        "width": "15",
        "unit_of_measurement": "in",
        "weight": "3.0",
        "weight_unit": "lb",
        "value": "2500",
        "value_currency": "USD"
      }
    ],
    "origin": {
      "access_restrictions": [
        "non_paved"
      ],
      "address_line_1": "87 Richardson St",
      "address_line_2": "string",
      "address_line_3": "string",
      "city": "Brooklyn",
      "region": "NY",
      "postal_code": "11249",
      "country": "US",
      "title": "Warehouse",
      "contacts": [
        {
          "name": "Rachel Egistrar",
          "email_address": "registrar@example.com",
          "phone_number": "(212) 123-4567"
        }
      ]
    },
    "preferred_quote_types": [
      "parcel"
    ],
    "public_reference": "Order #1437",
    "shipping_notes": "New customer"
  }
}
Response example (201)
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "additional_services": [],
  "bookable": {
    "missing": [],
    "ready": true
  },
  "created_at": "2021-01-21T17:22:08.818747",
  "currency": "USD",
  "destination": {
    "access_restrictions": [],
    "address_line_1": "87 Richardson St",
    "address_line_2": null,
    "address_line_3": null,
    "city": "New York",
    "contacts": [
      {
        "email_address": "al@example.com",
        "name": "Alfred Barr",
        "phone_number": "(222) 222-2222"
      }
    ],
    "country": "US",
    "postal_code": "11249",
    "region": "NY",
    "title": "Home"
  },
  "disqualifications": [],
  "hosted_session_id": 723,
  "id": "9d8892bc-f4c6-4b45-88e2-0ccd28eb73cc",
  "insurance": null,
  "internal_reference": null,
  "log_request_id": "FpL53jSpPbCUXRAAKPRS",
  "object_count": 1,
  "objects": [
    {
      "current_packing": [],
      "depth": "2",
      "details": {
        "creation_date": null,
        "creator": "Robert Irwin",
        "is_cites": false,
        "is_fragile": false,
        "materials": [],
        "title": "All That Jazz"
      },
      "height": "10.5",
      "images": [],
      "internal_reference": null,
      "public_reference": null,
      "subtype": "painting_unframed",
      "type": "art",
      "unit_of_measurement": "in",
      "value": "15000",
      "value_currency": "USD",
      "weight": "3.5",
      "weight_unit": "lb",
      "width": "10"
    }
  ],
  "origin": {
    "access_restrictions": [],
    "address_line_1": "11 W 53rd St",
    "address_line_2": null,
    "address_line_3": null,
    "city": "New York",
    "contacts": [
      {
        "email_address": "mary@example.com",
        "name": "Mary Quinn Sullivan",
        "phone_number": "(333) 333-3333"
      }
    ],
    "country": "US",
    "postal_code": "10019",
    "region": "NY",
    "title": "Warehouse"
  },
  "payment_process": "invoicing",
  "preferred_quote_types": [],
  "public_reference": null,
  "quote_types": [
    "premium",
    "select",
    "parcel"
  ],
  "quotes": [
    {
      "id": 61,
      "included_services": [
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "Specialized Shuttle",
          "sub_subtype": "specialized_shuttle",
          "subtype": "specialized",
          "type": "transport"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "Shadowbox",
          "sub_subtype": "shadow_box",
          "subtype": "packing_materials",
          "type": "packing"
        }
      ],
      "included_insurance_policy": null,
      "optional_services": [
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [
            {
              "name": "Soft Packed Disposal",
              "sub_subtype": "soft_packed_disposal",
              "subtype": "debris_disposal",
              "type": "handling"
            }
          ],
          "name": "Debris Disposal",
          "sub_subtype": "debris_disposal",
          "subtype": "debris_disposal",
          "type": "handling"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "name": "Assembly",
          "sub_subtype": "assembly",
          "subtype": "installation",
          "type": "handling"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "name": "Placement",
          "sub_subtype": "placement",
          "subtype": "installation",
          "type": "handling"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "name": "Installation",
          "sub_subtype": "installation",
          "subtype": "installation",
          "type": "handling"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "name": "Condition Check (destination)",
          "sub_subtype": "destination_condition_check",
          "subtype": "condition",
          "type": "handling"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "name": "Condition Check (origin)",
          "sub_subtype": "origin_condition_check",
          "subtype": "condition",
          "type": "handling"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "name": "Condition Report (destination)",
          "sub_subtype": "destination_full_condition_report",
          "subtype": "condition",
          "type": "handling"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "name": "Condition Report (origin)",
          "sub_subtype": "origin_full_condition_report",
          "subtype": "condition",
          "type": "handling"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [
            {
              "name": "Unpacking Soft Materials (destination)",
              "sub_subtype": "destination_unpacking_soft",
              "subtype": "unpacking",
              "type": "handling"
            }
          ],
          "name": "Unpacking (destination)",
          "sub_subtype": "destination_unpacking",
          "subtype": "unpacking",
          "type": "handling"
        }
      ],
      "quote_type": "premium",
      "status": "published",
      "total": "2",
      "total_currency": "USD"
    },
    {
      "id": 62,
      "included_services": [
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [
            {
              "name": "Soft Packed Disposal",
              "sub_subtype": "soft_packed_disposal",
              "subtype": "debris_disposal",
              "type": "handling"
            }
          ],
          "is_requested": false,
          "is_required": true,
          "name": "Debris Disposal",
          "sub_subtype": "debris_disposal",
          "subtype": "debris_disposal",
          "type": "handling"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "Fuel Surcharge",
          "sub_subtype": "fuel_surcharge",
          "subtype": "fees",
          "type": "taxes_duties_fees"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "Strongbox",
          "sub_subtype": "strongbox",
          "subtype": "packing_materials",
          "type": "packing"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "Consolidated Trucking",
          "sub_subtype": "road_groupage",
          "subtype": "consolidated",
          "type": "transport"
        }
      ],
      "included_insurance_policy": null,
      "optional_services": [
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [
            {
              "name": "Unpacking Soft Materials (destination)",
              "sub_subtype": "destination_unpacking_soft",
              "subtype": "unpacking",
              "type": "handling"
            }
          ],
          "name": "Unpacking (destination)",
          "sub_subtype": "destination_unpacking",
          "subtype": "unpacking",
          "type": "handling"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "name": "Condition Check (destination)",
          "sub_subtype": "destination_condition_check",
          "subtype": "condition",
          "type": "handling"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "name": "Condition Check (origin)",
          "sub_subtype": "origin_condition_check",
          "subtype": "condition",
          "type": "handling"
        }
      ],
      "quote_type": "select",
      "status": "published",
      "total": "4",
      "total_currency": "USD"
    },
    {
      "id": 63,
      "included_services": [
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "Fuel Surcharge",
          "sub_subtype": "fuel_surcharge",
          "subtype": "fees",
          "type": "taxes_duties_fees"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "Collection",
          "sub_subtype": "collection",
          "subtype": "collection",
          "type": "location"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "Ply Box",
          "sub_subtype": "ply_box",
          "subtype": "packing_materials",
          "type": "packing"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "UPS Ground",
          "sub_subtype": "parcel",
          "subtype": "parcel",
          "type": "transport"
        }
      ],
      "included_insurance_policy": null,
      "optional_services": [],
      "quote_type": "parcel",
      "status": "published",
      "total": "4",
      "total_currency": "USD"
    },
    {
      "id": 64,
      "included_services": [
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "Fuel Surcharge",
          "sub_subtype": "fuel_surcharge",
          "subtype": "fees",
          "type": "taxes_duties_fees"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "Collection",
          "sub_subtype": "collection",
          "subtype": "collection",
          "type": "location"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "Ply Box",
          "sub_subtype": "ply_box",
          "subtype": "packing_materials",
          "type": "packing"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "UPS Second Day Air",
          "sub_subtype": "parcel",
          "subtype": "parcel",
          "type": "transport"
        }
      ],
      "included_insurance_policy": null,
      "optional_services": [],
      "quote_type": "parcel",
      "status": "published",
      "total": "4",
      "total_currency": "USD"
    },
    {
      "id": 65,
      "included_services": [
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "Fuel Surcharge",
          "sub_subtype": "fuel_surcharge",
          "subtype": "fees",
          "type": "taxes_duties_fees"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "Collection",
          "sub_subtype": "collection",
          "subtype": "collection",
          "type": "location"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "Ply Box",
          "sub_subtype": "ply_box",
          "subtype": "packing_materials",
          "type": "packing"
        },
        {
          "amount": "1",
          "amount_currency": "USD",
          "included_services": [],
          "is_requested": false,
          "is_required": true,
          "name": "UPS Next Day Air",
          "sub_subtype": "parcel",
          "subtype": "parcel",
          "type": "transport"
        }
      ],
      "included_insurance_policy": null,
      "optional_services": [],
      "quote_type": "parcel",
      "status": "published",
      "total": "4",
      "total_currency": "USD"
    }
  ],
  "shipping_notes": null,
  "shortcode": "DEMO-R29NAW",
  "status": "quoted",
  "updated_at": "2021-01-21T17:22:10.129653"
}
Response example (400)
{
  "errors": {
    "detail": "string"
  }
}

Get a Quote Request

GET /requests/{request_id}

Retrieve an existing Shipment Quote Request record by its ID

Headers

  • Authorization string Required

    Authorize your API calls with an ARTA API token

Path parameters

Responses

  • 200 object

    Successful Request get response

    • additional_services array[string]

      The id of a service.

    • bookable object
      • ready boolean

        Returns true if the quotes in this request may be booked

      • missing array[string]

        A list of fields required for the request to be bookable

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

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

    • disqualifications array[object]

      The disqualifcation reason

      • quote_types array[string]

        The id of a quote type

      • reason string

        A brief explanation of the disqualification