Create a Self-Ship Collection

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://api-reference.arta.io/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "Arta API Reference MCP server": {
    "url": "https://api-reference.arta.io/mcp"
  }
}
Close
POST /self_ship_collections

Availability: Public Preview

This endpoint is currently in public preview and available only to approved accounts. Please contact Arta to request access for your organization.

Schedule a carrier pickup for a self-ship shipment with FedEx or DHL. Self-ship collections are available for pickup locations in the US and UK.

FedEx collections (service.carrier: "fedex") are scheduled as FedEx Ground or FedEx Express according to service.code. An optional package summary may be provided in service.package_details for express collections, and location.package_location tells the driver where to find the packages. FedEx collections cannot be cancelled through the API.

DHL collections (service.carrier: "dhl") are always scheduled with the DHL Express service, so service.code must be express. They require per-package dimensions and weight in service.package_details, and location.close_time must be at least 3 hours after collection_time. An international collection is subject to customs and requires service.declared_value and service.declared_value_currency; domestic collections may omit them. DHL collections can be cancelled with the cancel endpoint.

Headers

  • Authorization string Required

    Authorize your API calls with an Arta API token

application/json

Body object

The payload for scheduling a self-ship collection. The expected shape depends on service.carrier.

One of:
FedexSelfShipCollectionPayload object DhlSelfShipCollectionPayload object

Responses

  • 201 application/json

    The created self-ship collection

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

      A unique identifier for the Arta API call

    Hide response attributes Show response attributes object
    • closed_at string | null

      A NaiveDatetime-formatted timestamp describing when the collection was closed

    • collection_date string(date)

      The pickup date in ISO 8601 format (YYYY-MM-DD).

    • collection_time string

      The pickup time in ISO 8601 format (HH:MM:SS).

    • created_at string

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

    • id string(uuid)

      The ID of the self-ship collection in UUID format

    • location object

      The pickup location details

      Hide location attributes Show location attributes object
      • address_line_1 string

        Street address

      • address_line_2 string | null

        Additional address info

      • city string

        City

      • close_time string

        Location closing time in ISO 8601 format (HH:MM:SS)

      • contact object

        Contact at the pickup location

        Hide contact attributes Show contact attributes object
        • email_address string

          Contact email address

        • name string

          Contact name

        • phone_number string

          Contact phone number

      • country string

        Two-letter country code

      • package_location string

        Where packages are located at the pickup location: the front, rear, or side of the building, or none when not specified. Always none for DHL collections.

        Values are front, none, rear, or side.

      • postal_code string

        Postal code

      • region string

        State or province code

    • service object

      Carrier service details

      Hide service attributes Show service attributes object
      • carrier string

        Carrier identifier

        Values are fedex or dhl.

      • code string

        Service level code

        Values are express or ground.

      • declared_value string | null

        Declared value of the collected packages, as a decimal string. null when no declared value was provided.

      • declared_value_currency string

        ISO 4217 three-letter code for declared_value. An empty string when no declared value was provided.

      • package_details object | null

        The packages the collection was booked with, echoed back in the shape they were submitted. null for FedEx collections.

        Hide package_details attribute Show package_details attribute object | null
        • packages array[object]

          The packages included in the collection, one entry per package. Dimensions and weight are decimal strings, and every package shares the same unit_of_measurement and weight_unit.

          Hide packages attributes Show packages attributes object
          • depth string

            Package depth

          • height string

            Package height

          • unit_of_measurement string

            Unit for depth, height, and width

            Values are in or cm.

          • weight string

            Package weight

          • weight_unit string

            Unit for weight

            Values are lb or kg.

          • width string

            Package width

      • route string

        Route type

        Values are domestic or international.

    • shortcode string

      A human-readable identifier for the collection, formatted as the organization's shortcode followed by a hyphen and six alphanumeric characters

      Format should match the following pattern: ^[A-Z]+-[A-Z0-9]{6}$.

    • status string

      The current status of the collection

      Values are scheduled, closed, cancelled, or incomplete.

    • updated_at string

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

    The collection could not be scheduled: the pickup location is outside the supported countries, a carrier-specific requirement was not met, or the carrier rejected the collection.

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

      A unique identifier for the Arta API call

    Hide response attribute Show response attribute object
    • errors array[string] Required

      Human-readable error messages that apply to the request as a whole
  • 403 application/json

    Forbidden

  • 422 application/json

    The request body failed validation. Errors are keyed by the offending field path; invalid package measurement values are returned as a flat list.

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

      A unique identifier for the Arta API call

    One of:
    SelfShipCollectionFieldErrors object SelfShipCollectionErrorList object
POST /self_ship_collections 
curl \
 --request POST 'https://api.arta.io/self_ship_collections' \
 --header "Content-Type: application/json" \
 --header "Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y" \
 --data '{
  "self_ship_collection": {
    "collection_date": "2026-03-06",
    "collection_time": "10:00:00",
    "location": {
      "address_line_1": "123 Main St",
      "address_line_2": "string",
      "city": "New York",
      "close_time": "17:00:00",
      "contact": {
        "email_address": "john@example.com",
        "name": "John Doe",
        "phone_number": "+1-555-123-4567"
      },
      "country": "US",
      "package_location": "none",
      "postal_code": "10001",
      "region": "NY"
    },
    "service": {
      "carrier": "fedex",
      "code": "express",
      "package_details": {
        "package_count": 3,
        "total_weight": "15.5",
        "total_weight_unit": "lb"
      },
      "route": "domestic"
    }
  }
}'
Request examples 
# Headers
Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y

# Payload
{
  "self_ship_collection": {
    "collection_date": "2026-03-06",
    "collection_time": "10:00:00",
    "location": {
      "address_line_1": "123 Main St",
      "address_line_2": "string",
      "city": "New York",
      "close_time": "17:00:00",
      "contact": {
        "email_address": "john@example.com",
        "name": "John Doe",
        "phone_number": "+1-555-123-4567"
      },
      "country": "US",
      "package_location": "none",
      "postal_code": "10001",
      "region": "NY"
    },
    "service": {
      "carrier": "fedex",
      "code": "express",
      "package_details": {
        "package_count": 3,
        "total_weight": "15.5",
        "total_weight_unit": "lb"
      },
      "route": "domestic"
    }
  }
}
# Headers
Authorization: ARTA_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y

# Payload
{
  "self_ship_collection": {
    "collection_date": "2026-03-06",
    "collection_time": "10:00:00",
    "location": {
      "address_line_1": "123 Main St",
      "address_line_2": "string",
      "city": "New York",
      "close_time": "17:00:00",
      "contact": {
        "email_address": "john@example.com",
        "name": "John Doe",
        "phone_number": "+1-555-123-4567"
      },
      "country": "US",
      "postal_code": "10001",
      "region": "NY"
    },
    "service": {
      "carrier": "dhl",
      "code": "express",
      "declared_value": "500.00",
      "declared_value_currency": "USD",
      "package_details": {
        "packages": [
          {
            "depth": "12",
            "height": "8",
            "unit_of_measurement": "in",
            "weight": "5.5",
            "weight_unit": "lb",
            "width": "10"
          }
        ]
      },
      "route": "domestic"
    }
  }
}
Response examples (201) 
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "closed_at": null,
  "collection_date": "2026-03-06",
  "collection_time": "10:00:00",
  "created_at": "2026-03-01T12:00:00.000000",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "location": {
    "address_line_1": "123 Main St",
    "address_line_2": null,
    "city": "New York",
    "close_time": "17:00:00",
    "contact": {
      "email_address": "john@example.com",
      "name": "John Doe",
      "phone_number": "+1-555-123-4567"
    },
    "country": "US",
    "package_location": "none",
    "postal_code": "10001",
    "region": "NY"
  },
  "service": {
    "carrier": "dhl",
    "code": "express",
    "declared_value": "500.00",
    "declared_value_currency": "USD",
    "package_details": {
      "packages": [
        {
          "depth": "12",
          "height": "8",
          "unit_of_measurement": "in",
          "weight": "5.5",
          "weight_unit": "lb",
          "width": "10"
        }
      ]
    },
    "route": "international"
  },
  "shortcode": "ACME-S3GP24",
  "status": "scheduled",
  "updated_at": "2026-03-01T12:00:00.000000"
}
Response examples (400) 
{
  "errors": [
    "service.declared_value is required for international DHL collections",
    "service.declared_value_currency is required for international DHL collections"
  ]
}
Response examples (422) 
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "errors": {
    "location/close_time": [
      "must be at least 3 hours after collection_time"
    ]
  }
}
# Headers
content-type: application/json
x-arta-request-id: FkBjuxbwLLTx4RoAARkx

# Payload
{
  "errors": [
    "service.package_details.packages[0].weight must be a number"
  ]
}