Back to Top

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 May 10, 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 Required / string

    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 Required / string

    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.

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 Required / string

    Authorize your API calls with an ARTA API token

Path parameters
  • api_key_id Required / integer

    api_key_id parameter

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 Required / string

    Authorize your API calls with an ARTA API token

Path parameters
  • api_key_id Required / integer

    api_key_id parameter

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 Required / string

    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 Attachments

    • items array[object]
      • created_at string
      • 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 Required / integer

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

      • updated_at string
    • metadata object
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 Required / string

    Authorize your API calls with an ARTA API token

Body
  • attachment Required / object
    • upload_id Required / integer

      The integer ID of the upload resource being attached

    • request_id string

      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

    • shipment_id string

      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

    • created_at string
    • 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 Required / integer

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

    • updated_at string
  • • 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 Required / string

    Authorize your API calls with an ARTA API token

Path parameters
Responses
  • • 200 object

    Successful Attachment response

    • created_at string
    • 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 Required / integer

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

    • updated_at string
  • • 404 object

    Resource Not Found

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 Required / string

    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 Required / string

    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 Required / string

    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 Required / string

    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 Required / string

    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 Required / string

    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 Required / string

    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 Required / string

    Authorize your API calls with an ARTA API token

Body
  • email_subscription object
    • email_address string

      The email_address for this Email Subscription.

    • email_notification_ids array[string]

      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 Required / string

    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 Required / string

    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 Required / string

    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 Required / string

    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.

      • cancel_url string

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

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

      • origin object
      • private_token string

        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

      • shipping_notes string | null

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

      • shortcode string

        A brief and unique string identifier for the request resource

      • status string
      • success_url string

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

      • updated_at string
      • url string | null

        The ARTA Booking web URL for this Hosted Session

      • preferred_quote_types array[string]

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

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

    Authorize your API calls with an ARTA API token

Body
  • hosted_session object
    • additional_services array[string]

      The id of a service.

    • cancel_url string

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

    • destination object

      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

      • address_line_1 string

        The first line of the location's street address

      • 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

      • region string

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

      • postal_code Required / string

        The postal code for the location

      • country Required / string

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

      • title string

        The name for the location

      • contacts array[object]

        The contact details for the location

        • name Required / string

          The contact's name

        • email_address string

          The email address for this contact

        • phone_number string

          The phone_number for this contact

    • insurance string

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

    • internal_reference string

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

    • objects Required / array[object]
      • internal_reference string

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

      • current_packing array[string]

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

      • depth Required / string

        The depth of the object

      • details object
        • materials array[string]

          A list of IDs describing the types of materials used

        • creation_date string

          Details about the timing in which an object was created

        • creator string

          The creator of the object

        • notes string

          Any notes about the item

        • title string

          The object title

        • is_fragile boolean

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

        • 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

      • height Required / string

        The height of the object

      • images array[string(uri)]

        A list image urls of the object

      • public_reference string

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

      • subtype Required / string

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

      • width Required / string

        The width of the object

      • unit_of_measurement Required / string

        Values are in or cm.

      • weight string

        The weight of the object

      • weight_unit Required / string

        The unit of the object

        Values are lb or kg.

      • value Required / string
      • value_currency Required / string

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

        Default value is USD.

    • origin Required / object

      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

      • address_line_1 string

        The first line of the location's street address

      • 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

      • region string

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

      • postal_code Required / string

        The postal code for the location

      • country Required / string

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

      • title string

        The name for the location

      • contacts array[object]

        The contact details for the location

        • name Required / string

          The contact's name

        • email_address string

          The main email address for this contact

        • phone_number string

          The main phone_number for this contact

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

    • public_reference string

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

    • shipping_notes string

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

    • success_url string

      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.

    • cancel_url string

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

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

    • origin object
    • private_token string

      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

    • shipping_notes string | null

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

    • shortcode string

      A brief and unique string identifier for the request resource

    • status string
    • success_url string

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

    • updated_at string
    • url string | null

      The ARTA Booking web URL for this Hosted Session

    • preferred_quote_types array[string]

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

  • • 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_ref...}'
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"
  },
  "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 Required / string

    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.

    • cancel_url string

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

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

    • origin object
    • private_token string

      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

    • shipping_notes string | null

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

    • shortcode string

      A brief and unique string identifier for the request resource

    • status string
    • success_url string

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

    • updated_at string
    • url string | null

      The ARTA Booking web URL for this Hosted Session

    • preferred_quote_types array[string]

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

  • • 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"
  },
  "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 Required / string

    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.

    • cancel_url string

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

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

    • origin object
    • private_token string

      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

    • shipping_notes string | null

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

    • shortcode string

      A brief and unique string identifier for the request resource

    • status string
    • success_url string

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

    • updated_at string
    • url string | null

      The ARTA Booking web URL for this Hosted Session

    • preferred_quote_types array[string]

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

  • • 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"
  },
  "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 Required / string

    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 Required / string

    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 Required / string

    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 Required / string

    Authorize your API calls with an ARTA API token

Path parameters
  • invoice_id Required / integer

    invoice_id parameter

Responses