Skip to Content
API v1IntegrationsEntrataEntrata Integration

Entrata Integration

Overview

This document outlines the integration flow between our platform and Entrata, a property management system. The integration allows us to receive property data from Entrata and handle tour scheduling.

Webhook Logging

  1. Logging Process

    • Every incoming webhook from Entrata is logged in the entrata_webhooks table
    • The logWebhook() function in db.php handles this process
    • The following information is captured for each webhook:
      • Request type (e.g., ACTIVATION, SUSPENDED, CHANGE_FEED_TYPE)
      • Client ID (CID)
      • Property ID
      • Raw query string (complete URL parameters)
    • This logging is essential for debugging and auditing purposes

  2. Implementation Details

    • The logging happens at the beginning of the webhook processing in index.php
    • A unique log ID is generated for each webhook request
    • If logging fails, the system continues processing but logs a warning

  3. Benefits

    • Provides a complete audit trail of all Entrata interactions
    • Helps with troubleshooting integration issues
    • Allows for analysis of webhook patterns and frequencies
    • Enables correlation between webhook events and system responses

Authentication Flow

  1. Initial Authentication

    • Entrata sends a webhook to our platform with an authorisation code
    • We validate the request and client credentials
    • We exchange the authorisation code for an access token using Entrata’s OAuth endpoint
    • The access token is stored in the entrata_clients table for future API calls

  2. Client Setup

    • When a new Entrata client is authenticated, we create for them:
      • A agent user record in the users table
      • A property operator record in the property_operators table
      • An Entrata client record in the entrata_clients table
    • These records are linked together to maintain the relationship between the client and their properties
    • This is necessary as it allows their properties to also be managed through our Portal using the existing flow

Property Activation Flow

  1. Property Activation

    • When a client using Entrata sends a property activation request:
      • We send back an approval to Entrata
      • We retrieve the relevant property data from Entrata
      • We store the property data in the houses table
      • The property is linked to the appropriate property operator and agent created earlier

  2. Property Ingestion

    • Property data includes:
      • Basic information (address, bedrooms, bathrooms, etc.)
      • Pricing information
      • Images

Tour Scheduling Flow

  1. User Initiates Tour Request

    • User taps on an Entrata property in the app
    • App calls /api/getEntrataTourTimes.php with the property ID
    • Backend retrieves the property’s Entrata client information and access token
    • Backend calls Entrata’s getTourAvailability() service to fetch available tour slots for that property, converting them from whatever timezone they were sent in to America/Chicago
    • Available tour times are returned to the app and displayed to the user

  2. User Selects Tour Time

    • User selects a preferred tour time slot from the available options
    • App calls /api/requestViewing.php with the selected time slot and user information
    • Backend creates a viewing request record in our viewings table
    • Backend calls sendLeadToEntrataFromViewing() function to send the tour booking to Entrata
    • Entrata confirms the booking and returns a confirmation
    • Note: Entrata requires time slots sent to them to be in the exact same format they were sent to us in (i.e. 10:00 MST - 10:30 MST). This is why both the raw and formatted tour dates are sent back to the app

  3. Tour Confirmation

    • User sees their new tour booking on the Tours screen
    • Property operator receives new tour request on their dashboard

Database Structure

  1. Key Tables

    • entrata_clients: Stores Entrata client information and access tokens
    • property_operators: Links Entrata clients to property operators
    • houses: Stores property data from Entrata
    • users: Stores Entrata client agent information
    • entrata_webhooks: Stores logs of all incoming webhooks from Entrata

  2. Relationships

    • Entrata clients are linked to property operators
    • Properties are linked to property operators and agents
    • Tour and lead data are associated with specific properties

Error Handling

  1. Validation

    • Request validation ensures all required fields are present
    • Data validation and formatting ensures data is sent as expected to Entrata
    • Error responses include appropriate HTTP status codes and messages

  2. Logging

    • Extensive error logging is implemented throughout the integration
    • Logs include request details, response data, and error messages
    • This helps with debugging and troubleshooting integration issues

Security Considerations

  1. Authentication

    • OAuth tokens are used for API authentication
    • Tokens are stored securely in the database
    • Client credentials are validated on each request
Last updated on
Entrata IntegrationFinix Integration