Properties API

Properties represent physical service locations belonging to a customer. Each property has an address, geographic coordinates, zone assignment, and bin configuration. All endpoints require a valid JWT token in the Authorization header.

List Properties for a Customer

Retrieve all properties belonging to a specific customer.

curl "https://api.nextroute.app/api/customers/cus_abc123/properties" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200):

{
  "data": [
    {
      "id": "prop_xyz789",
      "tenant_id": "ten_001",
      "customer_id": "cus_abc123",
      "address": "123 Main St, Austin, TX 78701",
      "lat": 30.2672,
      "lng": -97.7431,
      "service_plan_id": "plan_weekly",
      "service_plan_name": "Weekly Standard",
      "service_zone_id": "zone_central",
      "service_zone_name": "Central Austin",
      "bin_count": 2,
      "bin_size": "96gal",
      "bin_location": "Left side of garage",
      "trash_day": "Monday",
      "trash_pickup_time": "morning",
      "notes": "Gate code: 1234",
      "is_active": 1,
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}

Create a Property

Add a new property to a customer. The address is automatically geocoded and matched to a service zone.

curl -X POST "https://api.nextroute.app/api/customers/cus_abc123/properties" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "456 Oak Ave, Austin, TX 78702",
    "service_plan_id": "plan_weekly",
    "bin_count": 1,
    "bin_size": "64gal",
    "bin_location": "Front of house",
    "trash_day": "Tuesday",
    "notes": "Ring doorbell on arrival"
  }'

Request Body:

Response (201):

Returns the created property object.

Automatic Behaviors

When creating a property, several things happen automatically:

1. Geocoding — if lat and lng are not provided, the address is geocoded using Mapbox to get coordinates
2. Zone matching — if service_zone_id is not provided and coordinates are available, the property is matched to a service zone based on geographic boundaries
3. Trash day — if the tenant uses "uniform" trash day mode and no trash_day is specified, the tenant's default trash day is applied
4. Route template sync — if both a zone and service plan are set, the property is automatically added to the matching route template as a new stop

Update a Property

Update one or more fields on an existing property.

curl -X PUT "https://api.nextroute.app/api/properties/prop_xyz789" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bin_count": 3,
    "bin_location": "Behind fence",
    "notes": "New gate code: 5678"
  }'

Updatable Fields:

Response (200):

Returns the updated property object.

Re-geocoding on Address Change

If you update the address without providing lat and lng, the new address is automatically geocoded. The old coordinates are replaced with the new ones.

Route Template Re-sync

If you update service_zone_id or service_plan_id, the property's route template assignment is automatically re-synced. This may move the stop from one template to another.

Delete (Deactivate) a Property

Deactivates a property and removes its stops from route templates. This is a soft delete — the property record is preserved for historical data.

curl -X DELETE "https://api.nextroute.app/api/properties/prop_xyz789" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200):

{
  "success": true
}

When a property is deactivated:

1. The property's is_active flag is set to 0
2. All route template stops referencing this property are also deactivated

Trash Day Modes

Properties support two trash day modes, configured at the tenant level:

When a new property is created in "uniform" mode and no trash_day is provided, the tenant default is automatically applied.

Zone Matching

When coordinates are available and no zone is specified, NextRoute automatically matches the property to a service zone using geographic boundaries. The matching logic:

1. Checks all active service zones for the tenant
2. Tests if the property's coordinates fall within each zone's boundary polygon
3. Falls back to ZIP code matching if polygon matching fails
4. Assigns the first matching zone

This means that in most cases, you only need to provide the address and NextRoute handles zone assignment automatically.

Related Pages

• Customers API — parent customer management
• Customers & Properties — conceptual overview
• Service Zones — zone configuration and boundaries
• Route Templates API — how properties link to routes