Address book
Contents 26 pages
Two collections, and they work differently because they are different: origins are places you maintain, destinations are places you have shipped to.
A Shopify store's key lists its Shopify locations and saved warehouse with GET /origins but cannot change them, and has no consignee book: those endpoints answer not_available_for_shopify. See Shopify stores.
Origins — where you ship from#
Your saved dock doors and warehouses. You create and edit these.
/api/v1/originsScope addresses:readcurl https://app.shipeasyco.com/api/v1/origins \
-H "Authorization: Bearer $SHIPEASY_API_KEY"{
"object": "list",
"data": [
{
"object": "origin",
"id": "cm2j1d3e5…",
"label": "Elk Grove — Dock A",
"company": "Acme Freight",
"address1": "1200 Devon Ave",
"address2": null,
"city": "Elk Grove Village",
"state": "IL",
"postal_code": "60007",
"contact_name": "Dock supervisor",
"phone": "+1-847-555-0100",
"email": "dock@acme.example",
"is_default": true,
"created_at": "2026-03-04T16:22:10.000Z",
"updated_at": "2026-07-19T11:02:44.000Z"
}
],
"has_more": false,
"next_cursor": null
}Default first, then alphabetical — the same order the web app's picker uses, so a picker built on this API matches the one in the browser. Origins are not paged; the whole list comes back.
Requires addresses:read.
Create one#
/api/v1/originsScope addresses:writecurl -X POST https://app.shipeasyco.com/api/v1/origins \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Dallas — Dock 2",
"company": "Acme Freight",
"address1": "4100 Commerce St",
"city": "Dallas",
"state": "TX",
"postal_code": "75201",
"contact_name": "Rita Chen",
"phone": "+1-214-555-0188",
"is_default": false
}'Returns 201 with the created origin.
| Field | ||
|---|---|---|
label |
required | How it appears in a picker. |
city, state, postal_code |
required | state is a two-letter code; the five-digit ZIP must be in it. |
address1, address2, company, contact_name, phone, email |
optional | Needed to book from this origin, so fill them in. |
is_default |
optional | Setting one default clears the previous one. Your first origin is the default whatever you send. |
The street details are optional here and required at booking. That is deliberate: you can seed a list of locations from a system that only knows city/state/ZIP, then complete them later, rather than being blocked at import.
Update and delete#
/api/v1/origins/{originId}Scope addresses:readcurl https://app.shipeasyco.com/api/v1/origins/cm2j1d3e5… \
-H "Authorization: Bearer $SHIPEASY_API_KEY"/api/v1/origins/{originId}Scope addresses:writecurl -X PATCH https://app.shipeasyco.com/api/v1/origins/cm2j1d3e5… \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "label": "Elk Grove — Dock A", "city": "Elk Grove Village",
"state": "IL", "postal_code": "60007", "phone": "+1-847-555-0199" }'/api/v1/origins/{originId}Scope addresses:writecurl -X DELETE https://app.shipeasyco.com/api/v1/origins/cm2j1d3e5… \
-H "Authorization: Bearer $SHIPEASY_API_KEY"PATCH takes the same body as create and replaces the record — send the whole
origin, not just the changed field. The exception is is_default: false does
not clear it; set true on another origin to move it. DELETE removes it;
shipments already booked from it are untouched, because a shipment keeps its
own copy of the address it shipped from. If you delete the default, your newest
remaining origin becomes the default.
Writes require addresses:write, and the key must have been minted by an
owner or admin — the same gate the web app applies, not a looser one.
Import many#
/api/v1/origins/importsScope addresses:writeThe web app's ship-from CSV upload, as JSON: send up to 200 locations in rows,
each as POST /origins takes one, with street, contact and phone filled in.
Run it with dry_run: true first: nothing is added, and the answer says what
would be.
curl -X POST https://app.shipeasyco.com/api/v1/origins/imports \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "dry_run": true, "rows": [
{ "label": "Montebello Warehouse", "address1": "1400 Greenwood Ave",
"city": "Montebello", "state": "CA", "postal_code": "90640",
"contact_name": "Ana Ruiz", "phone": "323-555-0118" } ] }'{
"object": "origin_import",
"dry_run": true,
"added": 1,
"rows": [
{ "index": 0, "label": "Montebello Warehouse", "result": "add", "problem": null }
]
}Each row is checked on its own, as the web app's upload checks them: good rows
are added, and a row with a bad field, or a name already in your book, comes
back as problem with the reason. A real run that adds nothing is refused with
validation_failed, one issue per row.
Destinations — where you ship to#
Your consignees. Some are recorded for you, some you save on purpose, and
curated_at tells the two apart:
curated_at |
What it means |
|---|---|
null |
Recorded automatically from a quote or booking in the web app. Later ones fill in details still empty and refresh residential; none replaces a detail. |
| a timestamp | Someone saved or edited it on purpose, in the web app or through this API. Quotes and bookings no longer change its details, only use_count and last_used_at. |
A consignee quoted or booked in the web app lands here without a call of its
own. Quotes and bookings made through this API do not: save a consignee with
POST /destinations.
/api/v1/destinationsScope addresses:readcurl "https://app.shipeasyco.com/api/v1/destinations?limit=50&q=northline" \
-H "Authorization: Bearer $SHIPEASY_API_KEY"{
"object": "list",
"data": [
{
"object": "destination",
"id": "cm2j4h6k8…",
"nickname": "Northline · Dallas dock",
"pinned": true,
"company": "Northline Supply",
"contact_name": "Rita Chen",
"address1": "4100 Commerce St",
"address2": null,
"city": "Dallas",
"state": "TX",
"postal_code": "75201",
"residential": false,
"phone": "+1-214-555-0188",
"email": "receiving@northline.example",
"notes": "Dock 4, call ahead",
"use_count": 12,
"last_used_at": "2026-08-12T14:05:01.000Z",
"curated_at": "2026-08-14T09:12:00.000Z",
"archived_at": null,
"created_at": "2026-07-02T18:40:12.000Z",
"updated_at": "2026-08-14T09:12:00.000Z"
}
],
"has_more": true,
"next_cursor": "…"
}Cursor-paged, newest first by creation, and requires addresses:read. With
updated_since it is a change feed instead: oldest first by updated_at, as on
every list.
Not ordered by use, despite last_used_at. A keyset cursor needs a field
that does not move, and last_used_at changes every time anyone quotes — paging
on it would show you the same consignee twice and skip another. use_count,
last_used_at and pinned are all fields you can read and sort yourself; none
of them is this list's order.
Archived consignees are omitted, here and on GET /destinations/{id}. The
change feed omits them too, so an archive does not reach you as a change. Send
archived=true to list only the archived ones instead; each has archived_at
set, and restore puts one back.
Search#
q is the web app's own search: it matches nickname, company or city
anywhere in the value, or postal_code from its first digit, ignoring case. It
takes 2 to 200 characters; anything else is 400 invalid_parameter, rather than
a "match" on the whole book.
The street, contact name, phone, email and notes are encrypted at rest, so search does not cover them. To find a consignee by street, page the list and filter on your side, or key your own records on the destination id.
Save one#
/api/v1/destinationsScope addresses:writecurl -X POST https://app.shipeasyco.com/api/v1/destinations \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"nickname": "Northline · Dallas dock",
"company": "Northline Supply",
"contact_name": "Rita Chen",
"address1": "4100 Commerce St",
"city": "Dallas",
"state": "TX",
"postal_code": "75201",
"phone": "+1-214-555-0188",
"notes": "Dock 4, call ahead"
}'| Field | ||
|---|---|---|
contact_name, address1, phone |
required | What a booking needs, so the entry can fill one without retyping. |
city, state, postal_code |
required | state is a two-letter code; the five-digit ZIP must be in it. |
nickname, company, address2, email, notes |
optional | |
residential |
optional | Delivery to a home. Defaults to false. |
These are the web app form's rules, and they are stricter than origins' on purpose. Saving marks the entry curated, and nothing fills in a curated entry later, so one saved without its street, contact and phone would stay that way.
201 when the consignee is new. 200 when the address is already in your
book. An address is its ZIP, street and suite. A match is not an error: the
existing entry takes the details you sent, and loses any optional one you left
out; it comes back if it was archived, and keeps its id, pinned, use_count
and history. This is how the web app's form saves.
pinned keeps the consignee at the front of the web app's picker. Send it to
pin or unpin; leave it out and the pin stays as it is, on PATCH too.
Read, replace and archive#
/api/v1/destinations/{destinationId}Scope addresses:readcurl https://app.shipeasyco.com/api/v1/destinations/cm2j4h6k8… \
-H "Authorization: Bearer $SHIPEASY_API_KEY"/api/v1/destinations/{destinationId}Scope addresses:writecurl -X PATCH https://app.shipeasyco.com/api/v1/destinations/cm2j4h6k8… \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "contact_name": "Rita Chen", "address1": "4100 Commerce St",
"city": "Dallas", "state": "TX", "postal_code": "75201",
"phone": "+1-214-555-0199" }'/api/v1/destinations/{destinationId}Scope addresses:writecurl -X DELETE https://app.shipeasyco.com/api/v1/destinations/cm2j4h6k8… \
-H "Authorization: Bearer $SHIPEASY_API_KEY"PATCH takes the same body as save and replaces the entry: send the whole
consignee. A field you leave out is cleared, and that clears its nickname and
notes too. notes is the address's note for the delivery driver: the web app
fills a booking's delivery instructions from it. A booking through this API
takes delivery_instructions itself; see Booking.
A PATCH can answer with a different id. Moving a consignee onto an
address another entry already holds tells us the two are the same place, so
they are merged, as in the web app. The response is the entry that remains,
with the two use_counts added together. That entry keeps the other one's
nickname if you send none, stays pinned if either was, and takes the later
last_used_at. The id in your path then answers 404. Read id from the
response, not from your request.
DELETE archives, the web app's "remove". The consignee leaves this list,
GET answers 404, and the web app's pickers stop offering it, but the record
is kept. The response says so:
{ "object": "deleted", "id": "cm2j4h6k8…", "deleted": true, "archived": true }To bring one back, save the same address again: you get 200 and the original
id. It also comes back by itself, with its id, when someone quotes or books to
that address in the web app. Shipments already booked are untouched, because a
shipment keeps its own copy of the address it shipped to.
Writes require addresses:write, and a key minted by an owner or admin,
the same gate as origins.
Restore an archived consignee#
/api/v1/destinations/{destinationId}/restoreScope addresses:writecurl -X POST https://app.shipeasyco.com/api/v1/destinations/cm2j4h6k8…/restore \
-H "Authorization: Bearer $SHIPEASY_API_KEY"Puts an archived consignee back in the book with its id, pinned, use_count
and history, and answers with it. An id that is not archived answers 404.