A Ruby client for v4 of Yardi's Guestcard (and soon ILS) API


Add this line to your application's Gemfile:

gem 'yardi'

And then re-install your application's bundle:

$ bundle install

Or install it yourself as:

$ gem install yardi



Configure the gem with your Yardi license, entity and platform:

Yardi.configure do |config|
  # Use your web service URL below
  config.license_key = ENV['LICENSE_KEY']
  config.entity = 'Apartment List'
  config.platform = 'SQL Server'
  config.enable_event_tracking = true
  config.gcs_bucket = ENV['_GCS_BUCKET']

Useful classes


Yardi SOAP actions require authentication so the SOAP action classes (see below) require a :credential parameter in the initializer.

credential =
  username: 'my-username',
  password: 'my-password',
  database: 'test_db_live',
  server: '0SQL_DBtest'

params = {
  agent: 'Test', last_name: 'Agent'),
  credential: credential,
   ... # any other required params
response =

SOAP Actions

To request an action, instantiate the appropriate class (see below) and invoke #perform on it. The API response will be parsed and returned as a ruby object.


Insert a guest card into Yardi's system.

Initialization parameters
  • agent [Yardi::Parameter::Agent]
  • credential [Yardi::Parameter::Credential] information needed to authenticate with Yardi
  • lead_source [String] what Yardi calls TransactionSource
  • reason [String] what Yardi calls Event Reasons. This is the reason for the event, e.g. price inquiry, tour, etc.
  • property [Yardi::Parameter::Property] the property to associate the guest card with
  • user [Yardi::Parameter::User] the user to associate the guest card with


Get all the residents for a given property ID.

Initialization parameters
  • credential [Yardi::Parameter::Credential] information needed to authenticate with Yardi
  • property_id [String] the remote YardiPropertyId

An array of Yardi::Model::Residents

  credential: credential, params: { property_id: 'p263656'}


    @email="[email protected]",
        "PhoneType" => "home",
        "PhoneDescription" => "Home",
        "PhoneNumber" => "(123) 456-7890"
    @email="[email protected]",
        "PhoneType" => "cell",
        "PhoneDescription" => "Mobile",
        "PhoneNumber" => "8507742326"


Get a list of Yardi::Model::Prospects for a given Prospect at the specified property ID.

Initialization parameters
  • credential [Yardi::Parameter::Credential] information needed to authenticate with Yardi
  • params [Hash]
    • property_id [String]
    • prospect [Yardi::Parameter::Prospect]
    • with_or [Yardi::Parameter::With_or]

An array of Yardi::Model::Prospects

  credential: credential,
  params: { property_id: 'p263656', prospect: prospect, with_or: with_or }
# => [#<Yardi::Model::Prospect>, #<Yardi::Model::Prospect>]


  • first_name The Prospect's first name according to Yardi's database
  • last_name The Prospect's last name according to Yardi's database
  • email The Prospect's email address according to Yardi's database
  • phones An Array of the Prospect's phone numbers, or nil if there are none
  • events An Array of Yardi::Model::Event objects
  • prospect_id The Prospect id from Yardi's database e.g. "p00003693"
  • tenant_id The tenant id from Yardi's database e.g. "t000456"


To install this gem onto your local machine, run bundle exec rake install. To release a new version, follow the instructions here.


If you are interested in contributing to this project, please review the contribution guidelines.


  • 5.0.1 Add remote_property_id to prospects
  • 5.0.0 Make Yardi gem compatible with Rails 6
  • 4.10.3 Patch for NilClass when building prospect
  • 4.10.2 Patch for send_prospect_events in validator
  • 4.10.1 Patch for send_prospect_events default value
  • 4.10.0 GetYardiGuestActivity uses send_prospect_events parameter
  • 4.9.1 Bug fix for request using GetYardiGuestActivity_SearchWithOR which does not need prospect eventing
  • 4.9.0 Fix to change get_soap_action to action and add phones to prospect params
  • 4.8.4 GetYardiGuestActivity uses a with_or parameter
  • 4.8.2 Update EmptyResponse validator to look for Envelope in Xml
  • 4.8.1 Update document parser to look for Envelope in Xml
  • 4.8.0 Add GetPropertyConfigurations request
  • 4.6.10 Update pms_resident and pms_prospect: add unit_name, resident_id and move_in_report_type
  • 4.6.0 Add Snowflake eventing for residents and prospects
  • 4.2.0 Add ability to build xml to reactivate and update guestcards
  • 4.1.1 Fix to change param name of action to guestcard_action
  • 4.1.0 Add guestcard action to build xml for active or inactive guestcard
  • 4.0.0 Add handling for 404 errors and move ConnectionError to be a subclass of Yardi::Error::Base
  • 3.1.2 Fix Prospect parsing to properly handle missing Event nodes
  • 3.1.1 Fix roommate parsing to properly extract roommate data from GetResidents response
  • 3.1.0 Add roommates to Resident Model and Parser
  • 3.0.6 Handle Yardi connection errors
  • 3.0.5 Handle missing event ids
  • 3.0.4 Add GuestsNotFound Error
  • 3.0.3 Handle roommates in prospect search results
  • 3.0.2 Raise an error when GetResidents call returns no Residents
  • 3.0.1 Handle parsing resident response when there is only one result
  • 3.0.0 GetYardiGuestActivity returns an Array of Prospects
  • 2.0.0 GetYardiGuestActivity uses a Prospect parameter
  • 1.0.3 Fix when GetResidents call returns nil dates
  • 1.0.2 Fix when GetResidents call returns a single phone number
  • 1.0.1 Fix when GetResidents call returns nil phone numbers
  • 1.0.0 Change response for GetYardiGuestActivity to be an array of Events instead of Tours. Also add lease dates GetResidents response.
  • 0.3.0 Add GetResidents request
  • 0.2.1 Handle when Yardi's response is completely empty
  • 0.2.0 Insert FirstContact events as Email instead of Other
  • 0.1.5 Handle missing bed/price preferences
  • 0.1.4 Fix Prospect search, which requires a property ID
  • 0.1.3 Fetch existing tours from Yardi
  • 0.1.2 Support custom connections for use with a proxy
  • 0.1.1 Handle multiple errors in the response
  • 0.1.0 Initial release with guestcard insertion and response handling