Properties API

A managed property is a durable, org-scoped record of one listing: its address, the jurisdiction TaxLens resolved for it, mapping confidence, and tax-driver defaults (property type, classification, star rating, tax postal code) plus optional default legal issuers for invoicing. When a booking passes property_id, TaxLens fills any omitted calculation and issuer fields from the property. Remapping a property affects future bookings only — persisted booking and invoice snapshots stay frozen. See the dashboard view in Properties and the getting-started walk-through in Add your first property.

POST /v1/properties geocodes the address, resolves the closest jurisdiction, and stores the mapping. The most useful fields:

curl -X POST https://api.taxlens.getdynamiq.ai/v1/properties \
  -H "X-API-Key: $TAXLENS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference": "PMS-HOTEL-42",
    "name": "Downtown Hotel",
    "address_line1": "350 5th Ave",
    "city": "New York",
    "region": "NY",
    "postal_code": "10118",
    "country_code": "US",
    "jurisdiction_code": "US-NY-NYC",
    "property_type": "hotel",
    "star_rating": 4,
    "default_legal_issuer_id": 7
  }'

{
  "id": 42,
  "external_reference": "PMS-HOTEL-42",
  "name": "Downtown Hotel",
  "jurisdiction_code": "US-NY-NYC",
  "jurisdiction_confidence": "high",
  "mapping_status": "mapped",
  "tax_driver_status": "complete",
  "property_type": "hotel",
  "star_rating": 4,
  "default_legal_issuer_id": 7
}

Importing a whole portfolio? POST /v1/properties/bulk-map creates up to 500 properties in one request — the recommended path for a PMS or channel-manager listing sync. Each row supports the same fields as a single create, and org-admin permissions are required only when a row sets a non-null legal issuer default.

curl -X POST https://api.taxlens.getdynamiq.ai/v1/properties/bulk-map \
  -H "X-API-Key: $TAXLENS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": [
      { "external_reference": "LIST-ROME-1", "name": "Rome Host Unit",
        "address_line1": "Via del Corso 1", "city": "Rome", "country_code": "IT",
        "property_type": "vacation_rental" },
      { "external_reference": "LIST-BCN-1", "name": "Barcelona Loft",
        "address_line1": "Carrer de Mallorca 200", "city": "Barcelona", "country_code": "ES",
        "property_type": "apartment" }
    ]
  }'

GET /v1/properties/{property_id} returns a single property with richer detail than the list: alongside every list field it adds the resolved jurisdiction, its full ancestors chain (country → state → city → …), and the tax_driver_hints — the tax-driver fields that prefill bookings from this property. Use it to confirm a tricky address resolved to the place you expected.

curl https://api.taxlens.getdynamiq.ai/v1/properties/42 \
  -H "X-API-Key: $TAXLENS_KEY"

PATCH /v1/properties/{property_id} partially updates a stored property — this is the right way to correct an address, fix a tax driver, or pin a jurisdiction. Send only the fields you want to change; every field is optional and omitted fields are left untouched. When you change an address field (address_line1, city, region, postal_code, country_code) or jurisdiction_code, TaxLens re-maps the property automatically as part of the same request — you don't need a separate remap call after an address fix.

# Correct the address — this re-maps the property in the same call
curl -X PATCH https://api.taxlens.getdynamiq.ai/v1/properties/42 \
  -H "X-API-Key: $TAXLENS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address_line1": "20 W 34th St",
    "postal_code": "10001"
  }'

List your inventory with GET /v1/properties (filter by mapping_status, country_code, and more — paginated with items + total). Re-run geocoding for one property with POST /v1/properties/{property_id}/remap when its address is already correct but the mapping needs a refresh; the refreshed mapping applies to future bookings while existing snapshots remain frozen.

# List mapped US properties
curl "https://api.taxlens.getdynamiq.ai/v1/properties?mapping_status=mapped&country_code=US" \
  -H "X-API-Key: $TAXLENS_KEY"

# Re-run geocoding for one property whose address is already current
curl -X POST https://api.taxlens.getdynamiq.ai/v1/properties/42/remap \
  -H "X-API-Key: $TAXLENS_KEY"