Amsi

Ruby client of AMSI Evolution Suite API

Versions

See the changelog

Installation

Add this line to your application's Gemfile:

gem 'amsi'

And then execute:

$ bundle

Or install it yourself as:

$ gem install amsi

Usage

SOAP Actions

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

Amsi::Request::AddGuestCard

Add a new guest card for the prospect

Initialization parameters

Required initializer parameters:

  • contact_type [String] See Amsi::Parameter::ContactType
  • password [String] Amsi account password
  • portfolio_name [String] the unique identifier for the property in AMSI
  • property_id [String] AMSI property id
  • prospect Amsi::Parameter::Prospect
  • user_id [String] Amsi account username
  • web_service_url [String] Amsi Url to the leasing.asmx resource

Optional initializer parameters:

  • appointment_date [Date] date the prospect is going to visit the property
  • comments [String]
  • contact_datetime [DateTime]
  • date_needed [Date]
  • initial_source_id [String]
  • lease_term_desired [Integer]
  • leasing_agent_id [String]
  • qualified [Boolean]
  • unit_subtype [String]
  • unit_type [String]
Response

Amsi::Model::GuestCardResult

Amsi::Request::GetMoveinsByFirstMarketingSource

Get all leases matching the specified marketing source and within the specified time window.

Initialization parameters

Required initializer parameters:

  • from_date [Date] Beginning of date interval within which to search
  • marketing_source_code [String] Code corresponding to the marketing source for which to fetch move ins. Max of 3 characters according to their docs.
  • password [String] Amsi account password
  • portfolio_name [String] the unique identifier for the property in AMSI
  • property_id [String] AMSI property id
  • through_date [Date] End of date interval within which to search
  • user_id [String] Amsi account username
  • web_service_url [String] Amsi Url to the leasing.asmx resource
Response

Array<Amsi::Model::Lease>

Amsi::Request::GetPropertyList

Retrieve a list of properties and detailed information about each.

Initialization parameters

Required initializer parameters:

  • user_id [String] Amsi account username
  • password [String] Amsi account password
  • portfolio_name [String] the unique identifier for the property in AMSI
  • web_service_url [String] Amsi Url to the leasing.asmx resource

Optional initializer parameters and default values:

  • property_id [String] Amsi property id (if this field is left blank, the response will include all properties in the portfolio)
  • include_leasing_agents [Boolean] if true, response will include leasing agents for each property returned.
  • include_marketing_sources [Boolean] if true, response will include marketing sources for each property returned.
  • include_unit_types [Boolean] if true, response will include unit types for each property returned.
Response

Array<Amsi::Model::Property>

Amsi::Request::GetPropertyResidents

Retrieve resident leases for a given property. Returns current leases only by default.

Initialization parameters

Required initializer parameters:

  • user_id [String] Amsi account username
  • password [String] Amsi account password
  • portfolio_name [String] the unique identifier for the property in Amsi
  • property_id [String] Amsi property id
  • web_service_url [String] Amsi Url to the leasing.asmx resource
  • params [Hash] extra configuration fields: :start_date [String], :end_date [String], :remote_id [String], :billing_config [BillingConfiguration], :import_id [String], :pmc_id [String], :app_name [String], :timezone [String]

Optional initializer parameters and default values:

  • lease_status [String] Lease status filter; defaults to current leases ("C"). Valid values: (A)pplicant, (C)urrent, (I)ntent to Transfer, (L)eased, (N)otice, (P)revious, (T)ransfer, (V)approved, (X)cancelled
  • include_marketing_source [Boolean] if true, response will include marketing sources on each lease returned.
Response

Array<Amsi::Model::Lease>

Parameters

Amsi::Parameter::ContactType

Constants for the different channels prospects can use for contacting. Available constants are:

  • INTERNET
  • PHONE
  • RETURN_VISIT
  • VISIT

Amsi::Parameter::Prospect

A container for prospect details.

Required initializer parameters:

  • last_name [String]

Optional initializer parameters:

  • daytime_phone [String]
  • email [String]
  • first_name [String]

Models

Amsi::Model::Address

A Amsi::Model::Property has an address and a remit_to_address

  • line_1 [String] 1st line in the street address
  • line_2 [String] 2nd line in the street address
  • line_3 [String] 3rd line in the street address
  • line_4 [String] 4th line in the street address
  • city [String] the city
  • state [String] the state
  • zip_code [String] the zip code
  • country [String] the country

Amsi::Model::GuestCardResult

The response from AddGuestCard, will have the following attributes:

  • contact_sequence_number Integer
  • guest_card_id [String] the unique identifier for the newly created guest card
  • property_id [String]
  • status [String] either "SUCCESS" or "FAILURE" (also has convenience method success?)

Amsi::Model::GuestCard

The response from GetMoveinsByFirstMarketingSource is an array of Amsi::Model::Lease instances. Leases have guest_card and matched_guest_cards. guest_card is either an Amsi::Model::GuestCard or nil and matched_guest_cards is an array of Amsi::Model::GuestCards (can be empty). Amsi::Model::GuestCards have the following attributes:

  • email [String]
  • create_date [DateTime] The time the guest card was created according to AMSI
  • first_name [String] The renter's first name
  • id [String] The ID of the guest card in AMSI
  • initial_source_id [String] the short code for the marketing source attributed to the lease
  • last_name [String] The renter's last name
  • property_id [String] The unique identifier of the property that the guest card belongs to

Amsi::Model::Lease

The response from GetPropertyResidents is an array of Amsi::Model::Lease instances. Each instance will have the following attributes:

  • property_id [String]
  • building_id [String] Building ID
  • unit_id [String] Unit name
  • resident_id [String] Resident ID
  • external_reference_id [String]
  • guest_card [Amsi::Model::GuestCard] or nil
  • matched_guest_cards [Array<Amsi::Model::GuestCard>], can be []
  • occupant_status_code [String in Amsi::Model::Lease::Status]
  • occupant_status_code_description [String]
  • begin_date [Date]
  • end_date [Date]
  • application_date [Date]
  • sign_date [Date]
  • move_in_date [Date]
  • rent_amount [Integer]
  • occupants [Array<Amsi::Model::Occupant>]
  • lead_id [String] Guest Card No.
  • lead_date [DateTime] Guest first contact date
  • lead_source_code [String] Marketing source code

Amsi::Model::LeasingAgent

A Amsi::Model::Property has 0 or more leasing agents

  • agent_active_flag [String] "Y" if the agent is active, otherwise "N" (also has convenience method active?)
  • code [String] the unique identifier for the agent within the property (alias of agent_code)
  • agent_name [String] the leasing agent's full name (alias of agent_name)
  • property_id [String] the unique ID of the property the leasing agent works at

Amsi::Model::Manager

A Amsi::Model::Property has a manager

  • fax [String] the property manager's fax number
  • first_name [String] the property manager's first name
  • last_name [String] the property manager's last name
  • middle_name [String] the property manager's middle name
  • phone [String] the property manager's phone number
  • salutation [String] the property manager's salutation, e.g. "Mrs"

Amsi::Model::MarketingSource

A Amsi::Model::Property has 0 or more marketing sources

  • code [String] unique identifier within the property (alias of source_code)
  • description [String] a description of the marketing source (alias of source_desc)
  • source_active_flag [String] "Y" if the marketing source is active, otherwise "N" (also has convenience method active?)
  • property_id [String] the unique ID of the property the marketing source belongs to

Amsi::Model::Occupant

One occupant of a lease. Each instance will have the following attributes:

  • property_id [String]
  • building_id [String] Building ID
  • unit_id [String] Unit name
  • resident_id [String] Resident ID
  • sequence_number [String] Sequence number
  • first_name [String]
  • last_name [String]
  • phone_1 [String]
  • phone_2 [String]
  • responsible_flag [String in ["Responsible" | "Non-Responsible"]]
  • email [String]

Amsi::Model::Property

The response from GetPropertyList is an array of Amsi::Model::Property instances. Each instance will have the following attributes:

  • address [Amsi::Model::Address] the property's physical address
  • email [String] the email address of the property (alias of property_addr_email)
  • id [String] the property's unique identifier
  • leasing_agents [Array<Amsi::Model::LeasingAgent>] the list of leasing agents for the property
  • live_date [Date] the date the property went live
  • live_flag [String] "Y" if the property is live, otherwise "N" (also has convenience method live?)
  • manager [Amsi::Model::Manager] the property manager's contact info
  • marketing_sources [Array<Amsi::Model::MarketingSource>] the list of marketing sources for the property
  • name [String] the name of the property (alias of property_name_1)
  • name_2 [String] an optional alternate name of the property (alias of property_name_2)
  • remit_to_address [Amsi::Model::Address] the property's mailing address
  • unit_types [Array<Amsi::Model::UnitType>] the list of unit types for the property

Amsi::Model::UnitType

A Amsi::Model::Property has 0 or more unit types

  • baths [Decimal] the number of bathrooms in the unit
  • bedrooms [Integer] the number of bedrooms in the unit
  • count [Integer] Number of units in the property that are of this type
  • description [String] a description of the unit type (alias of unit_type_desc)
  • market_rent [Decimal] the rental price of the unit
  • minimum_security_deposit [Decimal] the minimum security deposit needed for the unit (alias of sec_min)
  • month_to_month_renew [Decimal] the month-to-month renewal amount (alias of mtm_renew)
  • other_renew [Decimal] other renewal amount
  • property_id [String] the unique ID of the property the unit is in
  • rooms [Integer] the total number of rooms in the unit
  • sqft [Integer] the total area of the unit (alias of sqftg)
  • standard_renew [Decimal] the standard renewal amount
  • type [String] the unique identifier within the property for this unit type (alias of unit_type)

Compatibility

This gem sets global configurations on other dependent libraries, which makes it inherently not thread-safe. Notably, it sets the following

  • MultiXml.parser = :ox

If your client depends on any of these global settings, it is recommended that you do not run in a multi-threaded environment.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/apartmentlist/amsi.