shipments

Parse shipping info

Changed on Oct 22, 2026

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

Base URL: https://api.shipengine.com
URL: https://api.shipengine.com/v1/shipments/recognize
Auth: API key in header API-Key

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": [
      {
        "sales_order_id": "8c1f2a5e-3b7d-4e9a-a6c2-1d4f5e6a7b8c",
        "sales_order_item_id": "2e7b9c4d-6a1f-4c3e-8b5d-9f0a1b2c3d4e",
        "asin": "B00005N5PF",
        "item_id": "1402291169813"
      }
    ],
    "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",
      "address_residential_indicator": "no",
      "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",
      "address_residential_indicator": "no",
      "geolocation": [
        {
          "type": "what3words",
          "value": "cats.with.thumbs"
        }
      ]
    },
    "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",
      "address_residential_indicator": "no",
      "geolocation": [
        {
          "type": "what3words",
          "value": "cats.with.thumbs"
        }
      ]
    },
    "customs": {
      "terms_of_trade_code": "ddp",
      "contents": "gift",
      "non_delivery": "return_to_sender"
    },
    "advanced_options": {
      "bill_to_country_code": "CA",
      "freight_class": "77.5",
      "collect_on_delivery": {
        "payment_amount": {
          "currency": "USD"
        }
      },
      "movement_indicator": "c2c",
      "license_number": "514785",
      "invoice_number": "IOC56888",
      "certificate_number": "784515",
      "fragile": true,
      "delivery_as_addressed": true,
      "return_after_first_attempt": true,
      "netstamps_options": {
        "row": 1,
        "column": 1
      },
      "suppress_carrier_generated_documents": [
        "commercial_invoice"
      ],
      "transparency_codes": [
        {
          "order_item_id": "12345678901234",
          "codes": [
            "AZ:XXXXXXXXXXXX"
          ]
        }
      ]
    },
    "tags": [
      {
        "tag_id": 8712,
        "name": "Fragile",
        "color": "#FF0000"
      }
    ],
    "packages": [
      {
        "shipment_package_id": "se-28529731",
        "package_id": "se-28529731",
        "package_code": "small_flat_rate_box",
        "insured_value": {
          "currency": "USD"
        },
        "content_description": "Hand knitted wool socks",
        "products": [
          {
            "value": {
              "currency": "USD"
            },
            "harmonized_tariff_code": "3926.1",
            "country_of_origin": "CA",
            "vat_rate": 0.2,
            "manufacturer_product_id": "012345678905",
            "manufacturer_ns_product_id": "MY-SKU-12345",
            "cpsc_certificates": [
              {
                "certifier_id": "CERT-12345",
                "certificate_version_id": "v1.0"
              }
            ],
            "cpsc_disclaim": {
              "disclaim_code": "B",
              "intended_use_code": "130.006"
            }
          }
        ]
      }
    ],
    "batch_ids": [
      "se-9581628",
      "se-1935182"
    ],
    "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": [
      {
        "sales_order_id": "8c1f2a5e-3b7d-4e9a-a6c2-1d4f5e6a7b8c",
        "sales_order_item_id": "2e7b9c4d-6a1f-4c3e-8b5d-9f0a1b2c3d4e",
        "asin": "B00005N5PF",
        "item_id": "1402291169813"
      }
    ],
    "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",
      "address_residential_indicator": "no",
      "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",
      "address_residential_indicator": "no",
      "geolocation": [
        {
          "type": "what3words",
          "value": "cats.with.thumbs"
        }
      ]
    },
    "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",
      "address_residential_indicator": "no",
      "geolocation": [
        {
          "type": "what3words",
          "value": "cats.with.thumbs"
        }
      ]
    },
    "customs": {
      "terms_of_trade_code": "ddp",
      "contents": "gift",
      "non_delivery": "return_to_sender"
    },
    "advanced_options": {
      "bill_to_country_code": "CA",
      "freight_class": "77.5",
      "collect_on_delivery": {
        "payment_amount": {
          "currency": "USD"
        }
      },
      "movement_indicator": "c2c",
      "license_number": "514785",
      "invoice_number": "IOC56888",
      "certificate_number": "784515",
      "fragile": true,
      "delivery_as_addressed": true,
      "return_after_first_attempt": true,
      "netstamps_options": {
        "row": 1,
        "column": 1
      },
      "suppress_carrier_generated_documents": [
        "commercial_invoice"
      ],
      "transparency_codes": [
        {
          "order_item_id": "12345678901234",
          "codes": [
            "AZ:XXXXXXXXXXXX"
          ]
        }
      ]
    },
    "tags": [
      {
        "tag_id": 8712,
        "name": "Fragile",
        "color": "#FF0000"
      }
    ],
    "packages": [
      {
        "shipment_package_id": "se-28529731",
        "package_id": "se-28529731",
        "package_code": "small_flat_rate_box",
        "insured_value": {
          "currency": "USD"
        },
        "content_description": "Hand knitted wool socks",
        "products": [
          {
            "value": {
              "currency": "USD"
            },
            "harmonized_tariff_code": "3926.1",
            "country_of_origin": "CA",
            "vat_rate": 0.2,
            "manufacturer_product_id": "012345678905",
            "manufacturer_ns_product_id": "MY-SKU-12345",
            "cpsc_certificates": [
              {
                "certifier_id": "CERT-12345",
                "certificate_version_id": "v1.0"
              }
            ],
            "cpsc_disclaim": {
              "disclaim_code": "B",
              "intended_use_code": "130.006"
            }
          }
        ]
      }
    ],
    "batch_ids": [
      "se-9581628",
      "se-1935182"
    ],
    "comparison_rate_type": "retail",
    "zone": 6
  }
}

Changes

Oct 22, 2026e998dffc42be Revision changes
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
- info
  added the new optional request property ////
- info
  added the optional property //// to the response with the status
Oct 9, 2026020f57d6f5b8 Revision changes
- breaking
  added the new required request property /////
- breaking
  added the new required request property /////
- breaking
  added the new required request property /////
- breaking
  added the new required request property /////
- breaking
  added the new required request property /////
- breaking
  added the new required request property ////
- breaking
  added the new required request property ////
- breaking
  added the new required request property ////
- breaking
  added the new required request property ////
- breaking
  added the new required request property ////
- breaking
  added the new required request property ////
- breaking
  request property ///// was restricted to a list of enum values
- breaking
  request property ////// was restricted to a list of enum values
- breaking
  request property //////// was restricted to a list of enum values
- breaking
  request property // was restricted to a list of enum values
- breaking
  request property //// was restricted to a list of enum values
- breaking
  the /// request property's minLength was increased from 0 to 1
- breaking
  the ////// request property's minLength was increased from 0 to 1
- breaking
  the ////// request property's minLength was increased from 0 to 1
- breaking
  the ////// request property's minLength was increased from 0 to 1
- breaking
  added the pattern ^se(-[a-z0-9]+)+$ to the request property ///
- breaking
  the ////// request property type changed from no type to string
- breaking
  the ///// request property type changed from no type to string
- breaking
  the ////// request property type changed from no type to string
- breaking
  the /// request property type changed from no type to string
- breaking
  the //////// request property type changed from no type to string
- breaking
  the //// request property type changed from no type to object
- breaking
  the //// request property type changed from no type to object
- breaking
  the /// request property type changed from no type to object
- breaking
  the // request property type changed from no type to string
- breaking
  the /// request property type changed from no type to object
- breaking
  the ////// request property type changed from no type to string
- breaking
  the ////// request property type changed from no type to string
- breaking
  the ////// request property type changed from no type to string
- breaking
  the /// request property type changed from no type to object
- breaking
  the /// request property type changed from no type to object
- breaking
  the //// request property type changed from no type to string
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the ////// response's property type changed from no type to string for status
- breaking
  the ///// response's property type changed from no type to string for status
- breaking
  the ////// response's property type changed from no type to string for status
- breaking
  the /// response's property type changed from no type to string for status
- breaking
  the //////// response's property type changed from no type to string for status
- breaking
  the //// response's property type changed from no type to object for status
- breaking
  the //// response's property type changed from no type to object for status
- breaking
  the /// response's property type changed from no type to object for status
- breaking
  the // response's property type changed from no type to string for status
- breaking
  the /// response's property type changed from no type to object for status
- breaking
  the ////// response's property type changed from no type to string for status
- breaking
  the ////// response's property type changed from no type to string for status
- breaking
  the ////// response's property type changed from no type to string for status
- breaking
  the /// response's property type changed from no type to object for status
- breaking
  the /// response's property type changed from no type to object for status
- breaking
  the //// response's property type changed from no type to string for status
- warning
  removed from the ///// request property allOf list
- warning
  removed from the ////// request property allOf list
- warning
  removed from the //// request property allOf list
- warning
  removed from the //// request property allOf list
- warning
  removed from the // request property allOf list
- warning
  removed from the /// request property allOf list
- warning
  removed from the ////// request property allOf list
- warning
  removed from the ////// request property allOf list
- warning
  removed from the ////// request property allOf list
- warning
  removed from the /// request property allOf list
- warning
  removed from the /// request property allOf list
- warning
  removed from the /// request property allOf list
- warning
  removed from the /// request property allOf list
- warning
  removed from the ////// request property allOf list
- warning
  removed from the //////// request property allOf list
- warning
  removed from the //// request property allOf list
- warning
  the /// request property's maxLength was set to 25
- warning
  added the new amazon_ca enum value to the // response property for the response status
- warning
  added the new amazon_us enum value to the // response property for the response status
- warning
  added the new any enum value to the ///// response property for the response status
- warning
  added the new brightpearl enum value to the // response property for the response status
- warning
  added the new cash enum value to the ///// response property for the response status
- warning
  added the new cash_equivalent enum value to the ///// response property for the response status
- warning
  added the new channel_advisor enum value to the // response property for the response status
- warning
  added the new cratejoy enum value to the // response property for the response status
- warning
  added the new ebay enum value to the // response property for the response status
- warning
  added the new etsy enum value to the // response property for the response status
- warning
  added the new gram enum value to the ////// response property for the response status
- warning
  added the new gram enum value to the //////// response property for the response status
- warning
  added the new gram enum value to the //// response property for the response status
- warning
  added the new groupon_goods enum value to the // response property for the response status
- warning
  added the new jane enum value to the // response property for the response status
- warning
  added the new kilogram enum value to the ////// response property for the response status
- warning
  added the new kilogram enum value to the //////// response property for the response status
- warning
  added the new kilogram enum value to the //// response property for the response status
- warning
  added the new magento enum value to the // response property for the response status
- warning
  added the new none enum value to the ///// response property for the response status
- warning
  added the new ounce enum value to the ////// response property for the response status
- warning
  added the new ounce enum value to the //////// response property for the response status
- warning
  added the new ounce enum value to the //// response property for the response status
- warning
  added the new paypal enum value to the // response property for the response status
- warning
  added the new pound enum value to the ////// response property for the response status
- warning
  added the new pound enum value to the //////// response property for the response status
- warning
  added the new pound enum value to the //// response property for the response status
- warning
  added the new seller_active enum value to the // response property for the response status
- warning
  added the new shopify enum value to the // response property for the response status
- warning
  added the new squarespace enum value to the // response property for the response status
- warning
  added the new stitch_labs enum value to the // response property for the response status
- warning
  added the new three_dcart enum value to the // response property for the response status
- warning
  added the new tophatter enum value to the // response property for the response status
- warning
  added the new volusion enum value to the // response property for the response status
- warning
  added the new walmart enum value to the // response property for the response status
- warning
  added the new woo_commerce enum value to the // response property for the response status
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new amazon_ca enum value to the request property //
- info
  added the new amazon_us enum value to the request property //
- info
  added the new any enum value to the request property /////
- info
  added the new brightpearl enum value to the request property //
- info
  added the new cash enum value to the request property /////
- info
  added the new cash_equivalent enum value to the request property /////
- info
  added the new channel_advisor enum value to the request property //
- info
  added the new cratejoy enum value to the request property //
- info
  added the new ebay enum value to the request property //
- info
  added the new etsy enum value to the request property //
- info
  added the new gram enum value to the request property //////
- info
  added the new gram enum value to the request property ////////
- info
  added the new gram enum value to the request property ////
- info
  added the new groupon_goods enum value to the request property //
- info
  added the new jane enum value to the request property //
- info
  added the new kilogram enum value to the request property //////
- info
  added the new kilogram enum value to the request property ////////
- info
  added the new kilogram enum value to the request property ////
- info
  added the new magento enum value to the request property //
- info
  added the new none enum value to the request property /////
- info
  added the new ounce enum value to the request property //////
- info
  added the new ounce enum value to the request property ////////
- info
  added the new ounce enum value to the request property ////
- info
  added the new paypal enum value to the request property //
- info
  added the new pound enum value to the request property //////
- info
  added the new pound enum value to the request property ////////
- info
  added the new pound enum value to the request property ////
- info
  added the new seller_active enum value to the request property //
- info
  added the new shopify enum value to the request property //
- info
  added the new squarespace enum value to the request property //
- info
  added the new stitch_labs enum value to the request property //
- info
  added the new three_dcart enum value to the request property //
- info
  added the new tophatter enum value to the request property //
- info
  added the new volusion enum value to the request property //
- info
  added the new walmart enum value to the request property //
- info
  added the new woo_commerce enum value to the request property //
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  removed from the ///// response property allOf list for the response status
- info
  removed from the ////// response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the //// response property allOf list for the response status
- info
  removed from the //// response property allOf list for the response status
- info
  removed from the // response property allOf list for the response status
- info
  removed from the /// response property allOf list for the response status
- info
  removed from the ////// response property allOf list for the response status
- info
  removed from the ////// response property allOf list for the response status
- info
  removed from the ////// response property allOf list for the response status
- info
  removed from the /// response property allOf list for the response status
- info
  removed from the /// response property allOf list for the response status
- info
  removed from the /// response property allOf list for the response status
- info
  removed from the /// response property allOf list for the response status
- info
  removed from the ////// response property allOf list for the response status
- info
  removed from the //////// response property allOf list for the response status
- info
  removed from the //// response property allOf list for the response status
- info
  the /// response's property pattern ^se(-[a-z0-9]+)+$ was added for the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property //// to the response with the status
- info
  added the required property //// to the response with the status
- info
  added the required property //// to the response with the status
- info
  added the required property //// to the response with the status
- info
  added the required property //// to the response with the status
- info
  added the required property //// to the response with the status

Operation history (9 revisions)