Address book

https://v2.cartage.ai/p/v2/addressBook reads (GET) and creates (POST) address book entries.

An entry is the facility record behind a shipment stop. A shipment cannot move to procuring until every stop has an addressBookId. Create the entry here, or reuse the one a 409 names, then send its id on the stop in POST /p/v2/shipment.

Authentication, the create envelope, error format and shared objects are in Shared rules.

GET /p/v2/addressBook

Read one entry by id.

Parameter	Required	Description
orgId	Yes	Your organization ID
id	Yes	Entry id, for example a stop's addressBookId

curl "https://v2.cartage.ai/p/v2/addressBook?orgId=<yourOrgId>&id=<addressBookId>" \
  -H "X-API-Key: <yourApiKey>"

Returns the entry (see Schema).

POST /p/v2/addressBook

Create one entry.

Required fields

No single field is required. The entry must carry one of these:

Option	Send	Smallest valid addressBook
A	address1 and zipCode	{ "address1": "100 Seller St", "zipCode": "78701" }
B	address1, city and state	{ "address1": "100 Seller St", "city": "Austin", "state": "TX" }
C	placeId	{ "placeId": "ChIJ…" }

Everything else is optional. Send name when you can: it is how the entry appears on a stop.

When you send address1, the entry comes back with a placeId we looked up for you.

One entry per place

Your organization can hold one entry per place. A place is a Google placeId plus a unit:

• placeId: the one we look up from address1, or the one you send when there's no address1. Nothing else is compared, so "Harbor DC" and "HARBOR DISTRIBUTION" at the same address are the same place.
• Unit: address2, or a unit written into address1 after Suite, Unit, # and similar. Those words are ignored, so Suite 200 and STE. 200 are the same unit. Each suite in a building is its own entry, so send the suite in address2.

When the place already has an entry, POST returns 409 and creates nothing. Use existingAddressBookId, for example as the stop's addressBookId.

{
    "error": "An address book already exists at this place: adb_123. Nothing was created. Use existingAddressBookId.",
    "code": "ADDRESS_BOOK_PLACE_EXISTS",
    "operation": "create",
    "placeId": "ChIJ…",
    "unit": "",
    "existingAddressBookId": "adb_123",
    "existingAddressBookIds": "adb_123",
    "matchCount": 1
}

existingAddressBookId is the oldest entry at the place. matchCount is above 1 only when your organization already had duplicates before this check existed. existingAddressBookIds lists them oldest first, as one comma-separated string.

If we can't resolve the address to a place and you didn't send a placeId, the entry is created without this check.

Example

curl -X POST "https://v2.cartage.ai/p/v2/addressBook" \
  -H "X-API-Key: <yourApiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "<yourOrgId>",
    "addressBook": {
      "name": "Seller Warehouse",
      "address1": "100 Seller St",
      "city": "Austin",
      "state": "TX",
      "zipCode": "78701",
      "contactEmail": "dock@seller.com",
      "locationType": "warehouse",
      "isAppointmentRequired": false
    }
  }'

{
    "status": "CREATED",
    "addressBook": { "id": "adb_123", "name": "Seller Warehouse", "placeId": "ChIJ…", "…": "…" }
}

Errors

Status	Code	Meaning and fix
400	—	Missing orgId or id on GET. On POST, a wrong type, an unknown enum value, or a field not in the Schema. issues[] names each one.
401	—	Missing or invalid API key
404	ADDRESS_BOOK_NOT_FOUND	No entry with that id in your organization
409	ADDRESS_BOOK_PLACE_EXISTS	An entry already exists at this place and unit. Use existingAddressBookId. See One entry per place.
409	ADDRESS_BOOK_PLACE_BUSY	Another write to the same place was still running. retryable is true, so send the same request again in a few seconds.
422	ADDRESS_BOOK_RESOLVABLE_ADDRESS	Neither address1 nor placeId was sent. Send one.
422	ADDRESS_BOOK_DELIVERABLE_ADDRESS	address1 was sent without a zipCode, and without both city and state. Add them.

On a 422 the top-level code is REQUIRED_FIELDS_MISSING; the codes above are on each issues[] entry.

Schema

All fields are optional except as described under Required fields. id, orgId, createdAt, updatedAt and activityLog are returned on every entry and cannot be sent.

Field	Type	Description
Address fields	—	Every Address field in Shared rules except addressBookId: name, street, city, state, zip, country, placeId, coordinates, timezone, business hours, contact, phone, unLocode, rampCode
locationType	enum	warehouse | distribution | retail | residential | commercial | customer | port | railyard | crossDock | manufacturing | airport | other
isAppointmentRequired	boolean	Whether the facility needs an appointment. Leave out only if unknown.
specialInstructions	string	Standing handling instructions: check-in, dock notes, after-hours rules
dockType	enum	rearLoad | sideLoad | groundLevel | elevated | other
numberOfDocks	number	Dock count
hasLiftGate / hasForklift	boolean	Equipment on site
maxTrailerLength	number	Longest trailer the site takes
notes	string	Free-form notes
fileIds	string[]	Attached files