ShipEngine logo
Documentation Powered by ReDoc

ShipEngine API (1.1.201912052312)

Download OpenAPI specification:Download

ShipEngine Sales & Support: sales@shipengine.com URL: https://www.shipengine.com/contact/ Terms of Service

ShipEngine's easy-to-use REST API lets you manage all of your shipping needs without worrying about the complexities of different carrier APIs and protocols. We handle all the heavy lifting so you can focus on providing a first-class shipping experience for your customers at the best possible prices.

Each of ShipEngine's features can be used by itself or in conjunction with each other to build powerful shipping functionality into your application or service.

ShipEngine's documentation is designed to help you start shipping as quickly as possible. With easy-to-follow tutorials, detailed reference docs, and ready-made recipes for common use cases, you'll see real results in no time at all.

Getting Started

If you're new to REST APIs then be sure to read our introduction to REST to understand the basics. Learn how to authenticate yourself to ShipEngine, and then use our sandbox environment to kick the tires and get familiar with our API. If you run into any problems, then be sure to check the error handling guide for tips.

Here are some step-by-step tutorials to get you started:

Shipping Labels for Every Major Carrier

ShipEngine makes it easy to create shipping labels for any carrier and download them in a variety of file formats. You can even customize labels with your own messages and images.

Real-Time Package Tracking

With ShipEngine you can get the current status of a package or subscribe to real-time tracking updates via webhooks. You can also create custimized tracking pages with your own branding so your customers will always know where their package is.

Compare Shipping Costs Across Carriers

Make sure you ship as cost-effectively as possible by comparing rates across carriers using the ShipEngine Rates API. Or if you don't know the full shipment details yet, then you can get rate estimates with limited address info.

Worldwide Address Validation

ShipEngine supports address validation for virtually every country on Earth, including the United States, Canada, Great Britain, Australia, Germany, France, Norway, Spain, Sweden, Israel, Italy, and over 160 others.

Authentication

api_key

To authenticate yourself to ShipEngine, you need to include an API-Key header in each API call. If you don't include a key when making an API request, or if you use an incorrect or expired key, then ShipEngine will respond with a 401 Unauthorized error.

Learn more about API keys in our authentication guide.

Security scheme type: API Key
Header parameter name: API-Key

Addresses

No matter your shipping volume, failed deliveries and address change surcharges cut into your bottom line and damage perception with customers. Our address validation services ensure your packages make it to the right place the first time. Learn how to leverage our address validation services here.

ShipEngine supports address validation for virtually every country on Earth, including the United States, Canada, Great Britain, Australia, Germany, France, Norway, Spain, Sweden, Israel, Italy, and over 160 others.

Address validation ensures accurate addresses and can lead to reduced shipping costs by preventing address correction surcharges. ShipEngine cross references multiple databases to validate addresses and identify potential deliverability issues.

Parse an address

The address-recognition API makes it easy for you to extract address data from unstructured text, including the recipient name, line 1, line 2, city, postal code, and more.

Data often enters your system as unstructured text (for example: emails, SMS messages, support tickets, or other documents). ShipEngine's address-recognition API helps you extract meaningful, structured data from this unstructured text. The parsed address data is returned in the same structure that's used for other ShipEngine APIs, such as address validation, rate quotes, and shipping labels.

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

Authorizations:
api_key
Request Body schema: application/json

The only required field is text, which is the text to be parsed. You can optionally also provide an address containing already-known values. For example, you may already know the recipient's name, city, and country, and only want to parse the street address into separate lines.

text
required
string non-empty

The unstructured text that contains address-related entities

address
object

You can optionally provide any already-known address values. For example, you may already know the recipient's name, city, and country, and only want to parse the street address into separate lines.

Responses

200

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

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

put /v1/addresses/recognize
https://api.shipengine.com/v1/addresses/recognize

Request samples

Content type
application/json
Example
Text only

This is the simplest way to call the address-recognition API. Just pass the text to be parsed and nothing else.

Copy
 Expand all Collapse all
{
  • "text": "Margie McMiller at 3800 North Lamar suite 200 in austin, tx. The zip code there is 78652."
}

Response samples

Content type
application/json
Example
text_only

This response shows that the address-recognition API was able to recognize all the address entities in the text. Notice that the country_code is not populated and the address_residential_indicator is "unknown", since neither of these fields was included in the text.

Copy
 Expand all Collapse all
{
  • "score": 0.9122137426845613,
  • "address":
    {
    },
  • "entities":
    [
    ]
}

Validate An Address

Address validation ensures accurate addresses and can lead to reduced shipping costs by preventing address correction surcharges. ShipEngine cross references multiple databases to validate addresses and identify potential deliverability issues.

Authorizations:
api_key
Request Body schema: application/json
Array
name
string non-empty Nullable

The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.

phone
string non-empty Nullable

The phone number of a contact person at this address. The format of this phone number varies depending on the country.

company_name
string non-empty

If this is a business address, then the company name should be specified here.

address_line1
required
string non-empty

The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.

address_line2
string non-empty Nullable

The second line of the street address. For some addresses, this line may not be needed.

address_line3
string non-empty Nullable

The third line of the street address. For some addresses, this line may not be needed.

city_locality
required
string non-empty

The name of the city or locality

state_province
required
string non-empty

The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.

postal_code
string non-empty

postal code

country_code
required
string 2 characters

The two-letter ISO 3166-1 country code

address_residential_indicator
string
Default: "unknown"
Enum: "unknown" "yes" "no"

Indicates whether this is a residential address.

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post /v1/addresses/validate
https://api.shipengine.com/v1/addresses/validate

Request samples

Content type
application/json

A call that returns a status of verified.

Copy
 Expand all Collapse all
[
  • {
    }
]

Response samples

Content type
application/json
Example
All Known Fields

A response for a verified status call.

Copy
 Expand all Collapse all
[
  • {
    }
]

Batches

batches

List Batches

List Batches associated with your Shipengine account

Authorizations:
api_key
query Parameters
status
string (batch_status)
Enum: "open" "queued" "processing" "completed" "completed_with_errors" "archived" "notifying" "invalid"

The possible batch status values

page
integer <int32> >= 1
Default: 1
Example: page=2

Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.

page_size
integer <int32> >= 1
Default: 25
Example: page_size=50

The number of results to return per response.

sort_dir
string
Default: "desc"
Enum: "asc" "desc"

Controls the sort order of the query.

sort_by
string (batches_sort_by)
Enum: "ship_date" "processed_at"

The possible batches sort by values

Responses

200

The request was a success.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get /v1/batches
https://api.shipengine.com/v1/batches

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{