Sign in

v1

latestOpenAPI 3.0.02026-07-1397337495.2 KB
shipments

Parse shipping info

The shipment-recognition API makes it easy for you to extract shipping data from unstructured text, including people's names, addresses, package weights and dimensions, insurance and delivery requirements, and more.

Data often enters your system as unstructured text (for example: emails, SMS messages, support tickets, or other documents). ShipEngine's shipment-recognition API helps you extract meaningful, structured data from this unstructured text. The parsed shipment data is returned in the same structure that's used for other ShipEngine APIs, so you can easily use the parsed data to create a shipping label.

Note: Shipment recognition is currently supported for the United States, Canada, Australia, New Zealand, the United Kingdom, and Ireland.

put/v1/shipments/recognize

Request body

textstring required

The unstructured text that contains shipping-related entities

Example request

{
  "text": "I have a 4oz package that's 5x10x14in, and I need to ship it to Margie McMiller at 3800 North Lamar suite 200 in austin, tx 78652. Please send it via USPS first class and require an adult signature. It also needs to be insured for $400.\n",
  "shipment": {
    "shipment_id": "se-28529731",
    "carrier_id": "se-28529731",
    "service_code": "usps_first_class_mail",
    "shipping_rule_id": "se-28529731",
    "items": [
      {
        "asin": "B00005N5PF"
      }
    ],
    "ship_date": "2018-09-23T00:00:00.000Z",
    "created_at": "2018-09-23T15:00:00.000Z",
    "modified_at": "2018-09-23T15:00:00.000Z",
    "ship_to": {
      "name": "John Doe",
      "phone": "+1 204-253-9411 ext. 123",
      "email": "example@example.com",
      "company_name": "The Home Depot",
      "address_line1": "1999 Bishop Grandin Blvd.",
      "address_line2": "Unit 408",
      "address_line3": "Building #7",
      "city_locality": "Winnipeg",
      "state_province": "Manitoba",
      "postal_code": "78756-3717",
      "country_code": "CA",
      "geolocation": [
        {
          "type": "what3words",
          "value": "cats.with.thumbs"
        }
      ]
    },
    "ship_from": {
      "name": "John Doe",
      "phone": "+1 204-253-9411 ext. 123",
      "email": "example@example.com",
      "company_name": "The Home Depot",
      "address_line1": "1999 Bishop Grandin Blvd.",
      "address_line2": "Unit 408",
      "address_line3": "Building #7",
      "city_locality": "Winnipeg",
      "state_province": "Manitoba",
      "postal_code": "78756-3717",
      "country_code": "CA"
    },
    "warehouse_id": "se-28529731",
    "return_to": {
      "name": "John Doe",
      "phone": "+1 204-253-9411 ext. 123",
      "email": "example@example.com",
      "company_name": "The Home Depot",
      "address_line1": "1999 Bishop Grandin Blvd.",
      "address_line2": "Unit 408",
      "address_line3": "Building #7",
      "city_locality": "Winnipeg",
      "state_province": "Manitoba",
      "postal_code": "78756-3717",
      "country_code": "CA"
    },
    "customs": {
      "importer_of_record": {
        "name": "John Doe",
        "phone": "+1 204-253-9411 ext. 123",
        "email": "example@example.com",
        "company_name": "The Home Depot",
        "address_line1": "1999 Bishop Grandin Blvd.",
        "address_line2": "Unit 408",
        "address_line3": "Building #7",
        "city_locality": "Winnipeg",
        "state_province": "Manitoba",
        "postal_code": "78756-3717",
        "country_code": "CA"
      },
      "customs_items": [
        {
          "customs_item_id": "se-28529731",
          "country_of_origin": "CA"
        }
      ]
    },
    "advanced_options": {
      "bill_to_country_code": "CA",
      "invoice_number": "IOC56888"
    },
    "tags": [
      {
        "tag_id": 8712,
        "name": "Fragile",
        "color": "#FF0000"
      }
    ],
    "packages": [
      {
        "shipment_package_id": "se-28529731",
        "package_id": "se-28529731",
        "package_code": "small_flat_rate_box",
        "tracking_number": "1Z932R800392060079",
        "content_description": "Hand knitted wool socks",
        "products": [
          {
            "country_of_origin": "CA",
            "vat_rate": 0.2
          }
        ]
      }
    ],
    "comparison_rate_type": "retail",
    "zone": 6
  }
}

Response

Returns the parsed shipment, as well as a confidence score and a list of all the shipping entities that were recognized in the text.

scorenumber double required

A confidence score between zero and one that indicates how certain the API is that it understood the text.

Example response

{
  "shipment": {
    "shipment_id": "se-28529731",
    "carrier_id": "se-28529731",
    "service_code": "usps_first_class_mail",
    "shipping_rule_id": "se-28529731",
    "items": [
      {
        "asin": "B00005N5PF"
      }
    ],
    "ship_date": "2018-09-23T00:00:00.000Z",
    "created_at": "2018-09-23T15:00:00.000Z",
    "modified_at": "2018-09-23T15:00:00.000Z",
    "ship_to": {
      "name": "John Doe",
      "phone": "+1 204-253-9411 ext. 123",
      "email": "example@example.com",
      "company_name": "The Home Depot",
      "address_line1": "1999 Bishop Grandin Blvd.",
      "address_line2": "Unit 408",
      "address_line3": "Building #7",
      "city_locality": "Winnipeg",
      "state_province": "Manitoba",
      "postal_code": "78756-3717",
      "country_code": "CA",
      "geolocation": [
        {
          "type": "what3words",
          "value": "cats.with.thumbs"
        }
      ]
    },
    "ship_from": {
      "name": "John Doe",
      "phone": "+1 204-253-9411 ext. 123",
      "email": "example@example.com",
      "company_name": "The Home Depot",
      "address_line1": "1999 Bishop Grandin Blvd.",
      "address_line2": "Unit 408",
      "address_line3": "Building #7",
      "city_locality": "Winnipeg",
      "state_province": "Manitoba",
      "postal_code": "78756-3717",
      "country_code": "CA"
    },
    "warehouse_id": "se-28529731",
    "return_to": {
      "name": "John Doe",
      "phone": "+1 204-253-9411 ext. 123",
      "email": "example@example.com",
      "company_name": "The Home Depot",
      "address_line1": "1999 Bishop Grandin Blvd.",
      "address_line2": "Unit 408",
      "address_line3": "Building #7",
      "city_locality": "Winnipeg",
      "state_province": "Manitoba",
      "postal_code": "78756-3717",
      "country_code": "CA"
    },
    "customs": {
      "importer_of_record": {
        "name": "John Doe",
        "phone": "+1 204-253-9411 ext. 123",
        "email": "example@example.com",
        "company_name": "The Home Depot",
        "address_line1": "1999 Bishop Grandin Blvd.",
        "address_line2": "Unit 408",
        "address_line3": "Building #7",
        "city_locality": "Winnipeg",
        "state_province": "Manitoba",
        "postal_code": "78756-3717",
        "country_code": "CA"
      },
      "customs_items": [
        {
          "customs_item_id": "se-28529731",
          "country_of_origin": "CA"
        }
      ]
    },
    "advanced_options": {
      "bill_to_country_code": "CA",
      "invoice_number": "IOC56888"
    },
    "tags": [
      {
        "tag_id": 8712,
        "name": "Fragile",
        "color": "#FF0000"
      }
    ],
    "packages": [
      {
        "shipment_package_id": "se-28529731",
        "package_id": "se-28529731",
        "package_code": "small_flat_rate_box",
        "tracking_number": "1Z932R800392060079",
        "content_description": "Hand knitted wool socks",
        "products": [
          {
            "country_of_origin": "CA",
            "vat_rate": 0.2
          }
        ]
      }
    ],
    "comparison_rate_type": "retail",
    "zone": 6
  }
}