API Reference

The TPX API Reference provides the technical details for the currently available endpoints within the TPX MLS & Syndication Server.

This section documents authentication, request formats, property synchronization, response structures and common error conditions.

Only endpoints currently implemented by the TPX server are documented here. Future endpoints and webhook functionality will be added as they become available.

Base API Structure

TPX API endpoints are accessed through the TPX server using standard HTTPS requests.

Protected endpoints require valid TPX API client credentials to be included in the request headers.

X-TPX-Client-ID: YOUR_CLIENT_ID
X-TPX-Secret: YOUR_CLIENT_SECRET
Accept: application/json
Content-Type: application/json

Authentication

TPX API clients authenticate using two request headers.

The TPX server validates the API client, verifies that it is active, checks that the associated agency or organization is active and then authorizes the request.

Health Check

The health endpoint can be used to confirm that the TPX API server is responding.

This endpoint is intended as a simple system availability check.

GET /api/health

It can be used by administrators, monitoring tools or deployment checks to confirm that the TPX API application is running.

Authentication Test

The authentication test endpoint verifies that the supplied TPX API credentials are accepted by the server.

This endpoint should be used when configuring a new integration before attempting to synchronize property data.

X-TPX-Client-ID: YOUR_CLIENT_ID
X-TPX-Secret: YOUR_CLIENT_SECRET
Accept: application/json

GET /api/auth-test

A successful response confirms that the client credentials are valid and that the associated organization is authorized to access TPX.

Property Synchronization

The property synchronization endpoint creates or updates a canonical TPX property record for the authenticated source.

The same endpoint is used for both new property creation and subsequent updates.

TPX identifies the source property using the authenticated organization together with the external property identifier.

Property Sync Request

A basic property synchronization request may contain:

{
  "external_id": "PROPERTY-1001",
  "title": "Modern Sea View Villa",
  "status": "for-sale",
  "sale_price": 6250000,
  "exchange_available": true
}

Core Request Fields

Creating a Property

If TPX cannot find an existing source relationship for the authenticated organization and external property identifier, a new canonical property record may be created.

SOURCE AGENCY
      +
EXTERNAL ID PROPERTY-1001
      ↓
NO EXISTING MATCH
      ↓
CREATE TPX PROPERTY

The new property is associated with the authenticated source organization.

Updating a Property

When the same source submits the same external identifier again, TPX updates the existing canonical property record.

SOURCE AGENCY
      +
EXTERNAL ID PROPERTY-1001
      ↓
EXISTING SOURCE FOUND
      ↓
UPDATE EXISTING TPX PROPERTY

This prevents duplicate canonical records from being created during routine property synchronization.

Successful Response

A successful property synchronization response identifies whether the property was created or updated.

{
  "status": "success",
  "action": "updated",
  "property": {
    "id": 4831
  }
}

For a newly created record, the action may indicate that the property was created rather than updated.

Connected systems should retain the TPX property ID where useful for future synchronization and local property tracking.

Network Availability

The exchange_available field controls whether the property is available for syndication within the private TPX network.

To make the property available:

{
  "exchange_available": true
}

To remove the property from network availability:

{
  "exchange_available": false
}

Changing the value from true to false can also cause active, non-revoked syndication records associated with the property to be revoked by the server.

Source Protection

TPX protects canonical ownership by ensuring that one authenticated organization cannot overwrite another organization's property.

AGENCY A PROPERTY
      ↓
CAN ONLY BE UPDATED
BY AUTHORIZED SOURCE
AGENCY A

A property associated with another source organization should not be modified by an unrelated API client.

External Property Identity

The external_id should remain stable for the lifetime of the property within the originating system.

AGENCY 12
+
EXTERNAL ID: PROPERTY-1001
=
TPX PROPERTY #4831

If the external ID changes unnecessarily, TPX may no longer be able to identify the existing source relationship correctly.

HTTP Response Handling

Integrations should inspect both the HTTP status code and the returned JSON response.

Validation Errors

Property requests are validated before the canonical record is created or updated.

A request may fail because of:

• Missing required data
• Invalid field types
• Invalid property status values
• Inconsistent pricing information
• Invalid network availability data
• Authentication failure
• Inactive API client
• Inactive associated organization
• Unauthorized property ownership

{
  "status": "error",
  "message": "Property validation failed"
}

Authentication Errors

Protected endpoints reject requests that do not contain valid API credentials.

Possible causes include:

• Missing X-TPX-Client-ID
• Missing X-TPX-Secret
• Unknown API client
• Incorrect secret
• Expired client credentials
• Inactive API client
• Inactive associated agency

{
  "status": "error",
  "message": "Authentication failed"
}

API Client Security

TPX API credentials should always be treated as confidential server-side credentials.

• Do not place API secrets in browser JavaScript.
• Do not expose credentials in public HTML.
• Do not publish API secrets in source repositories.
• Store credentials securely in application configuration.
• Revoke credentials that are no longer required.

Each integration should normally use its own API client credentials so that access can be managed independently.

Current Endpoints

Planned API Capabilities

Additional endpoints will be documented as the TPX platform develops.

Future capabilities may include:

• Property retrieval endpoints
• Exchange inventory endpoints
• Syndication creation and management
• Property media endpoints
• Webhook subscription management
• Property lifecycle events
• Agency and network management endpoints

Planned Webhook Events

Future event-driven integration may include events such as:

property.created
property.updated
property.withdrawn
property.sold
syndication.revoked

Webhook delivery is not yet part of the currently documented public API.

Recommended Client Behaviour

Applications integrating with TPX should follow several basic reliability rules.

SEND API REQUEST
      ↓
CHECK HTTP STATUS
      ↓
READ JSON RESPONSE
      ↓
STORE TPX PROPERTY ID
      ↓
MARK LOCAL SYNC STATUS
      ↓
RETRY TEMPORARY FAILURES

A failed API request should not automatically be treated as a permanent failure. Network and server errors may require retry handling within the integration.

Versioning

Versioned API routes allow TPX to introduce future changes without unnecessarily breaking existing integrations.

The current property synchronization route uses:

/api/v1/properties/sync

Future API versions may be introduced when changes require different request or response behavior.