Ts-Immo REST API

Base URL

https://api.ts-immo.org/v1/gateway

All Client API endpoints are served under the /v1/gateway/ prefix. Responses are JSON, identifiers are UUID v4 and dates follow ISO 8601.

Authentication

Every call must carry an active token. The Client API accepts either an OAuth2 bearer (user flow) or an API Token (programmatic use, e.g. the WordPress plugin), interchangeably.

# OAuth2 Bearer (user flow)
Authorization: Bearer <access_token>

# API Token (programmatic, e.g. WordPress plugin)
Authorization: Bearer <api_token>
# or:
X-TS-IMMO-KEY: <api_token>

Both formats are introspected by ts-identity. No scope constraint is enforced: any active token is accepted. Resource filtering relies on the item_ids and client_id carried by the token — a request whose token carries no item_id matches no listing.

Conventions

All JSON field names (requests and responses) are snake_case. Query parameters stay camelCase (e.g. ?crmReference=…, ?gatewayId=…). Null fields are omitted from responses. Dates are ISO 8601 (e.g. 2026-01-15T10:00:00Z).

Endpoints

Key endpoints in detail

The most-used endpoints are detailed below with their parameters, request bodies and sample responses.

POST/v1/gateway/gateways

Creates a gateway for the authenticated client. The provided item_id must be one of the token's item_ids. The plan is automatically extracted from the token.

Request body

{
  "item_id": "item-123",
  "name": "Apimo -> WordPress",
  "market": "fr",
  "category": "professional",
  "mode": "PROD",
  "input_connector": {
    "connector_type": "APIMO",
    "connector_id": "770e8400-e29b-41d4-a716-446655440000",
    "config": { "api_key": "apimo-api-key", "provider": "12345" }
  },
  "output_connectors": [
    {
      "connector_type": "TS_SYNC",
      "connector_id": "880e8400-e29b-41d4-a716-446655440000",
      "config": {
        "url": "https://www.your-agency.com",
        "plugin_auth_key": "your-plugin-auth-key"
      }
    }
  ]
}

201 Created response — the created gateway and an API Token generated for programmatic use (e.g. WordPress plugin), nullable:

{
  "gateway": { "id": "660e8400-...", "item_id": "item-123", "status": "DRAFT", "...": "..." },
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...."
}

POST/v1/gateway/gateways/{id}/sync-jobs

Creates and immediately starts a sync job. The gateway must be in ACTIVE status.

# Full sync
curl -X POST "https://api.ts-immo.org/v1/gateway/gateways/GATEWAY_ID/sync-jobs" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Single-property sync
curl -X POST "https://api.ts-immo.org/v1/gateway/gateways/GATEWAY_ID/sync-jobs?crmReference=REF-12345" \
  -H "X-TS-IMMO-KEY: your-api-token"

GET/v1/gateway/properties

Returns the listings of the gateways tied to the token's item_ids (including delegated gateways). No parameters: filtering is automatic.

200 OK response — an array of TsImmoProperty (normalised real-estate model, snake_case fields, null fields omitted):

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "gateway_id": "660e8400-e29b-41d4-a716-446655440000",
    "stream_id": "770e8400-e29b-41d4-a716-446655440000",
    "crm_source": "apimo",
    "reference": "REF-12345",
    "crm_reference": "CRM-12345",
    "type": "apartment",
    "sub_type": "duplex",
    "offer_type": "sale",
    "status": "available",
    "title": { "fr": "Bel appartement 3 pièces", "en": "Beautiful 3-room apartment" },
    "description": { "fr": "Lumineux duplex traversant...", "en": "Bright through-duplex..." },
    "bedrooms": 2,
    "bathrooms": 1,
    "floor": "3",
    "orientation": "S",
    "financial": {
      "transaction": {
        "price": { "amount": 350000, "currency": "EUR" }
      }
    },
    "location": {
      "city": "Paris",
      "postal_code": "75001",
      "countryCode": "FR",
      "geo": { "latitude": 48.8566, "longitude": 2.3522 }
    },
    "sizes": {
      "liveable_area": { "size": 75.5, "unit": "sq_m" }
    },
    "images": [
      { "url": "https://cdn.example.com/photo1.jpg", "ordinal": 0 }
    ],
    "property_url": "https://www.your-agency.com/property/apartment-paris",
    "cover_thumbnail": "https://cdn.example.com/photo1-thumb.jpg",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z",
    "fetched_at": "2026-01-15T10:00:00Z"
  }
]

PUT/v1/gateway/properties/{id}/url

Callback used by the client plugin to set the URL of a listing's published page after synchronisation. Updates the property_url field.

curl -X PUT "https://api.ts-immo.org/v1/gateway/properties/PROPERTY_ID/url" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.your-agency.com/property/apartment-t3-paris" }'

POST/v1/gateway/properties/search/ai

Natural-language property search. Input is treated as hostile: control characters stripped, length truncated to 500, LLM output validated against a whitelist. The gateway_id filter is always forced from the token.

curl -X POST "https://api.ts-immo.org/v1/gateway/properties/search/ai" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "query": "3-bedroom apartment near Lyon, max 500000 EUR, with a pool" }'

The response returns the matching properties (max 50), the total count and the generated MongoDB filter (for transparency):

{
  "results": [ { "id": "...", "type": "apartment", "offer_type": "sale", "...": "..." } ],
  "total_count": 5,
  "filter": {
    "type": "apartment",
    "bedrooms": { "$gte": 3 },
    "amenities": { "$all": ["pool"] },
    "financial.transaction.price.amount": { "$lte": 500000 }
  }
}

POST/v1/gateway/site/activate

Validates that at least one of the client's gateways has a TS_SYNC output connector whose URL matches the domain. If found, the plugin_auth_key is propagated and an activation record is created.

Sample response:

{
  "success": true,
  "status": "activated",
  "domain": "https://your-site.com",
  "activated_at": "2026-03-26T10:00:00Z",
  "plan": "pro",
  "expires_at": "2027-03-26T00:00:00Z",
  "biens_max": 500
}

POST/v1/gateway/estimations

Issues a DVF-anchored price estimation. The caller passes no gateway identifier: it is resolved from the token. At least (address | postal_code) or (latitude, longitude) must be provided — the geocoded address wins over coordinates.

{
  "property_type": "house",
  "offer_type": "sale",
  "liveable_area_sqm": 120,
  "address": "10 Rue de la République, 74300 Cluses",
  "postal_code": "74300",
  "construction_year": 1985,
  "epc_category": "B",
  "with_commentary": true
}

200 OK response — central / low / high range, confidence level, applied adjustments, comparables and (on ESTIMATION_IA) a commentary:

{
  "request_id": "8c1c0c5e-...",
  "offer_type": "sale",
  "central":   { "total": 415000, "price_per_sqm": 3458, "currency": "EUR" },
  "low_bound": { "total": 385000, "price_per_sqm": 3208, "currency": "EUR" },
  "high_bound":{ "total": 448000, "price_per_sqm": 3733, "currency": "EUR" },
  "confidence": { "level": "MEDIUM", "sample_size": 17, "final_radius_km": 1.5 },
  "adjustments": [ { "code": "DPE_A_B", "percent": 0.03 } ],
  "top_comparables": [ { "source": "DVF", "sold_price": 395000, "price_per_sqm": 3291 } ]
}

GET/v1/gateway/leads

Paginated list of prospects captured via the lead block of estimations, sorted by creation date descending.

{
  "items": [
    {
      "id": "uuid",
      "first_name": "Marie",
      "last_name": "Dupont",
      "email": "marie.dupont@example.com",
      "project_timeframe_months": 6,
      "offer_type": "SALE",
      "property_type": "HOUSE",
      "estimated_central_total": 415000,
      "currency": "EUR",
      "created_at": "2026-05-02T23:14:58Z"
    }
  ],
  "page": 0,
  "size": 50,
  "total_elements": 87,
  "total_pages": 2
}

POST/v1/gateway/gateways/{id}/addons/{addonCode}

Buys the addon for the gateway. The price is resolved server-side from the catalogue. Idempotent: if the addon is already active, the existing purchase is returned. Restricted to the owner or a FULL_ACCESS delegate.

curl -X POST "https://api.ts-immo.org/v1/gateway/gateways/GATEWAY_ID/addons/ESTIMATION" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "period": "MONTHLY", "currency": "EUR" }'

GET/v1/gateway/insights/{gatewayId}/overview

Dashboard overview over a window. gatewayId is passed in the path and checked against the token scope; the INSIGHTS addon must be active (otherwise 409). Includes a comparison with the previous window.

{
  "unique_visitors": 1432,
  "sessions": 1879,
  "page_views": 5421,
  "leads": 28,
  "conversion_rate": 0.0195,
  "hot_leads": 7,
  "urgent_leads": 2,
  "series": [
    { "date": "2026-05-01", "unique_visitors": 52, "sessions": 67, "page_views": 198, "leads": 1 }
  ]
}

PATCH/v1/gateway/notification-preferences

Partial update of preferences. Each field is optional: an omitted or null field leaves the stored value unchanged. Defaults are all true (opt-out).

curl -X PATCH "https://api.ts-immo.org/v1/gateway/notification-preferences" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "sync": false }'

Error codes

Errors follow the standard envelope shared by all ts-services APIs: a human-readable message, a machine code, a timestamp and an optional detail.

{
  "message": "Human-readable message",
  "code": "ERROR_CODE",
  "timestamp": "2026-04-18T10:00:00Z",
  "detail": "Optional technical detail, may be null"
}