Locations API

A location is a reusable record for a physical place — typically a pickup or delivery address. The integration API surface for locations covers searching and listing locations, and reading each location’s contacts and time windows (recurring opening hours).

Where this fits in your operation

Locations are the address book your orders run against:

• Before promising a delivery slot in your webshop or customer portal, read the destination’s time windows to only offer slots when the location is open.
• Resolve a locationId by internal number or name before calling location-scoped APIs (e.g. cargo carrier balances).
• Audit which delivery addresses exist in Zendera against your master data with the paginated listing.

Interactive API Explorer

Searching and listing locations

Search for one location by name or internal number

GET /v2/locations/search?name=Acme%20warehouse

Or:

GET /v2/locations/search?internalLocationNumber=LOC-warehouse-1

Query parameters

Response

{
  "id": 999,
  "name": "Acme warehouse",
  "instructions": "Ring bell at side gate",
  "address": "Industrigata 5, 0155 Oslo, NO",
  "opens": "08:00",
  "closes": "18:00",
  "openingHoursIsDefault": false
}

Search for multiple locations

POST /v2/locations/search-multiple

Request body

{
  "searchTerm": "Acme",
  "groupIds": [],
  "page": 1,
  "perPage": 50
}

Response

{
  "locations": [ { "id": 999, "name": "Acme warehouse", "...": "..." } ],
  "page": 1,
  "perPage": 50,
  "total": 17,
  "totalPages": 1
}

List locations with pagination and sorting

POST /v2/locations/paginated

Request body

{
  "searchTerm": "",
  "groupIds": [],
  "sortBy": "SORTABLE_FIELD_NAME",
  "sortDirection": "ASC",
  "page": 1,
  "perPage": 100
}

The response is the same shape as search-multiple. Use this endpoint for full-list traversal.

Location contacts

A contact is a person attached to a location — typically a recipient or warehouse contact who should be notified about deliveries, or whose name/phone should be visible to drivers.

List contacts at a location

GET /v2/locations/{locationId}/contacts

Response

{
  "contacts": [
    {
      "contactId": 501,
      "firstName": "Anna",
      "lastName": "Hansen",
      "sendNotifications": true,
      "visibleToDrivers": true
    }
  ]
}

Location time windows

Time windows are recurring opening hours for a location, expressed as iCalendar RRule sets — exactly the same format used in recurring orders. Each time window has an RRule and a duration; together they describe when the location is open.

These windows directly affect imported orders: when an order import doesn’t pin a fixed window with earliest/latest, Zendera derives the stop’s time window from the location — these RRule windows first, then the location’s default opening hours. See time windows on the import page for the full precedence.

For example, “Open weekdays 08:00–16:00” is one time window with an rruleset of “every weekday at 08:00” and durationSeconds: 28800.

List a location’s time windows

GET /v2/locations/{locationId}/time-windows

Response

{
  "timeWindows": [
    {
      "locationTimeWindowId": 7001,
      "rruleset": "DTSTART:20260101T080000Z\nRRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR",
      "durationSeconds": 28800
    }
  ]
}

Managing locations (v1)

For address-book maintenance beyond what import side-effects give you, the v1 endpoints manage the location records themselves. Unlike the v2 reads above, these use snake_case JSON.

GET    /v1/locations?filters=is_depot=true&loads=Address&page=1&limit=100
POST   /v1/locations
GET    /v1/locations/{locationID}?loads=Address,LocationContacts
PATCH  /v1/locations/{locationID}
DELETE /v1/locations/{locationID}

• List/get — filters expressions (location_id, address_id, is_active, is_depot) and loads (Address, ParkingAtAddress, LocationContacts, Groups, LocationSkills, LocationVehicleConstraints, LocationImages, LocationExternalNumbers), plus page/limit.
• Create — requires location_name and one of address (inline object) or address_id. internal_location_number must be unique in your organization when provided. Other writable fields include opening hours (has_opening_times, location_opens, location_closes — see time windows on the import page for how they affect orders), parking and instruction fields, is_depot, use_etol / estimated_minutes_on_location, and external_location_numbers (with resolve_conflicts to acknowledge and merge conflicting numbers atomically).
• Update — PATCH with any subset of the same fields.
• Delete is soft — sets is_active=false, clears internal_location_number, and frees the external-number mappings for reuse; the record stays for history.

Common gotchas

• Locations are usually created via order import. Referencing a new externalId and address on import creates the location as a side effect — most integrations never create locations directly.
• v2 reads are camelCase; v1 management is snake_case. Don’t mix the conventions across the two endpoint families.
• Deleting frees the numbers, not the record. A deactivated location’s internal and external numbers become reusable on other locations.
• Time windows use iCalendar RRules. If your code doesn’t already speak RRule, use a battle-tested library — don’t try to hand-roll the strings.

What’s next

• To set custom field values on a location (gate codes, dock numbers, …), see Custom Field Values; the schema side is under Custom Field Definitions.
• For importing orders that reference these locations, see Importing and recurring orders.