[![Build Status](https://magnum.travis-ci.com/apartmentlist/real_page.svg?token=7UeXK6PaMuQ9eC79sCsV&branch=master)](https://magnum.travis-ci.com/apartmentlist/real_page)

# RealPage

Client for RealPage Exchange API.

## Versions

See the [changelog](CHANGELOG.txt)

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'real_page'
```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install real_page

## Usage

### Configuration
Configure the gem with your RealPage web service URL:

```ruby
RealPage.configure do |config|
  # Use your web service URL below
  config.web_service_url = 'https://gateway.rpx.realpage.com/rpxgateway/partner/Client/Client.svc'
  config.username = '<RealPage Exchange username>'
  config.password = '<RealPage Exchange password>'
  config.license_key = '<RealPage Exchange license key>'
  config.app_name = '<Service that uses this gem>'
end
```

### Models
Responses from RealPage are parsed from XML into a ruby Model class

#### RealPage::Model::Activity

An activity represents an event that happens in relation to a [RealPage::Model::GuestCard](#realpagemodelguestcard).

* `agent_id` [Fixnum]
* `agent_name` [String]
* `create_date` [Date]
* `date` [String]
* `edit_type_name` [String]
* `guest_card_journal_edit_type_id` [String]
* `guest_card_journal_type_id` [String]
* `id` [String]
* `logged_by_name` [String]
* `loss_reason_cd` [String]
* `max_create_date_time` [Fixnum]
* `name` [String]
* `notes` [String]
* `result_cd` [String]
* `result` [String]
* `status_change_reason` [String]
* `status` [String]
* `system` [Boolean]
* `time` [String]

#### RealPage::Model::Address

The address of a [RealPage::Model::Prospect](#realpagemodelprospect)

* `city` [String]
* `country` [String]
* `line1` [String]
* `line2` [String]
* `state` [String]
* `zip` [String]

#### RealPage::Model::Amenity

An identifier for an Amenity at a particular property.

* `id` [String]
* `pmc_id` [String]
* `site_id` [String]

#### RealPage::Model::Appointment

An appointment to visit the property. May be attached to a [RealPage::Model::GuestCard](#realpagemodelguestcard)

* `day` [Integer]
* `hour` [Integer]
* `leasing_agent_id` [String]
* `minute` [Integer]
* `month` [Integer]
* `pmc_id` [String]
* `site_id` [String]
* `task_notes` [String]
* `year` [Integer]

#### RealPage::Model::FloorPlan

The response from [GetFloorPlanList](#realpagerequestgetfloorplanlist) is an array of `RealPage::Model::FloorPlan`
instances. Each instance will have the following attributes:

* `bathrooms` [Float]
* `bedrooms` [Integer]
* `code` [String]
* `description` [String]
* `excluded_from_occupancy` [Boolean]
* `gross_square_footage` [Integer]
* `group_id` [String]
* `group_name` [String]
* `id` [Integer]
* `maximum_occupants` [Integer]
* `name_marketing` [String]
* `name` [String]
* `rent_max` [Float]
* `rent_min` [Float]
* `rentable_square_footage` [Integer]

#### RealPage::Model::FollowUp

A task for a leasing agent, perhaps to get back in touch with a [RealPage::Model::Prospect](#realpagemodelprospect) about a [RealPage::Model::GuestCard](#realpagemodelguestcard).

* `agent_id` [Integer]
* `agent_name` [String]
* `notes` [String]
* `past_due_task` [Boolean]
* `priority_cd` [String]
* `task_appt_date_time` [String]
* `task_category_cd` [String]
* `task_confirmed` [String]
* `task_contact_date_time` [Date]
* `task_contact_type_cd` [String]
* `task_duration_end` [String]
* `task_duration_start` [String]
* `task_id` [Integer]
* `task` [String]

#### RealPage::Model::GuestCard

The main object in RealPage's system representing a potential renter. The
response from [ProspectSearch](#realpagerequestprospectsearch) is an array of
these.


* `activities` [Array<[RealPage::Model::Activity](#realpagemodelactivity)>]
* `amenities` [Array<[RealPage::Model::Amenity](#realpagemodelamenity)>]
* `appointment` [[RealPage::Model::Appointment](#realpagemodelappointment)]
* `contact_type` [String]
* `create_date` [String]
* `customer_id` [String]
* `date_contact` [String]
* `date_followup` [String]
* `follow_ups` [Array<[RealPage::Model::FollowUp](#realpagemodelfollowup)>]
* `id` [String]
* `lease_actions` [Array<[RealPage::Model::LeaseAction](#realpagemodelleaseaction)>]
* `leasing_agent_id` [String]
* `move_in_reason` [String]
* `pet_weight_range` [String]
* `pmc_id` [String]
* `preferences` [[RealPage::Model::Preferences](#realpagemodelpreferences)]
* `primary_lead_source` [String]
* `primary_traffic_source_minor` [String]
* `property_status` [String]
* `prospect_comment` [String]
* `prospects` [Array<[RealPage::Model::Prospect](#realpagemodelprospect)>]
* `quotes` [Array<[RealPage::Model::Quote](#realpagemodelquote)>]
* `screenings` [Array<[RealPage::Model::Screening](#realpagemodelscreening)>]
* `secondary_lead_source` [String]
* `site_id` [String]
* `status_is_active` [Boolean]
* `status_is_leased` [Boolean]
* `status_is_lost` [Boolean]
* `units_shown` [Array<[RealPage::Model::UnitShown](#realpagemodelunitshown)>]

#### RealPage::Model::Lease

The response from [GetLeasesByTrafficSource](#realpagerequestgetleasesbytrafficsource) is an array of
`RealPage::Model::Lease` instances. Each instance will have the following attributes:

* `begin_date` [Date]
* `email` [String]
* `end_date` [Date]
* `first_name` [String]
* `guest_card_id` [String]
* `id` [String]
* `last_name` [String]
* `middle_name` [String]
* `move_in_date` [Date]
* `phone_1` [String]
* `phone_2` [String]
* `phone_ext_1` [String]
* `phone_ext_2` [String]
* `resident_household_id` [String]
* `resident_member_id` [String]
* `term_id` [String]
* `type` [String]
* `unit_id` [String]
* `unit_number` [String]

The allowed values of `leasetype` are set as constants in the `RealPage::Model::Lease::Type` module:

* `RealPage::Model::Lease::Type::FIRST_LEASE`
* `RealPage::Model::Lease::Type::RENEWAL`
* `RealPage::Model::Lease::Type::TRANSFER`

#### RealPage::Model::LeaseAction

An action taken on the path towards signing a [RealPage::Model::Lease](#realpagemodellease)

* `editable` [Boolean]
* `for_correct_date_sort` [String]
* `lal_org_lea_id` [Integer]
* `note_comment_length` [Integer]
* `note_comment` [String]
* `note_date` [Date]
* `note_id` [Integer]
* `note_source` [String]
* `note_type` [String]
* `note_user` [String]
* `rentable_item_reserved` [Boolean]
* `sort_date` [Date]

#### RealPage::Model::PhoneNumber

A person's phone number.

* `number` [String]
* `type` [String]

#### RealPage::Model::PicklistItem

Several responses from RealPage include a Picklist. These requests (e.g.
[GetMarketingSourcesByProperty](#realpagerequestgetmarketingsourcesbyproperty)) return an array of
`RealPage::Model::PicklistItem`s, which have 2 string attributes: `value` and `text`.

#### RealPage::Model::Preferences

Details of what the [RealPage::Model::Prospect](#realpagemodelprospect) wants in
an apartment.

* `date_needed` [Date]
* `desired_rent` [Integer]
* `floorplan_group_id` [String]
* `floorplan_id` [Integer]
* `lease_term_months` [Integer]
* `occupants` [String]
* `price_range_id` [String]
* `site_id` [String]

#### RealPage::Model::Prospect

The main object representing a renter. It will be found on a
[RealPage::Model::GuestCard](#realpagemodelguestcard).

* `address` [[RealPage::Model::Address](#realpagemodeladdress)]
* `customer_id` [Integer]
* `email` [String]
* `first_name` [String]
* `gender` [String]
* `id_issuer` [String]
* `id_number` [String]
* `id_numberencrypted` [String]
* `id_type` [String]
* `last_name` [String]
* `middle_name` [String]
* `phone_numbers` [Array<[RealPage::Model::PhoneNumber](#realpagemodelphonenumber)]
* `pmc_id` [Integer]
* `pref_communication_type` [String]
* `relationship_id` [String]
* `site_id` [Integer]
* `ssn_encrypted` [String]
* `ssn` [String]

#### RealPage::Model::Quote

A rental price quoted before move-in.

* `agent_name` [String]
* `bldg_unit`  [String]
* `building` [String]
* `context_name` [String]
* `date_created` [String]
* `date_lease_begin` [String]
* `date_lease_end` [String]
* `date_move_in` [String]
* `date_quote_expires` [String]
* `date_range_lease` [String]
* `deposit` [Float]
* `enable_payment_plan` [Boolean]
* `floor_plan_id` [Integer]
* `floor_plan_id` [String]
* `floor_plan_name` [String]
* `id` [Integer]
* `id` [String]
* `lease_term_id` [Integer]
* `lease_term_id` [String]
* `market_rent` [Float]
* `rent` [Float]
* `reservation_expire_date` [Date]
* `site_id` [String]
* `site` [String]
* `time_created` [String]
* `type_code` [String]
* `type` [String]
* `unit_applied` [Boolean]
* `unit_id` [String]
* `unit_reserved` [String]
* `unit_status` [String]
* `unit` [String]
* available [Boolean]

#### RealPage::Model::RentMatrix

The response from [GetRentMatrix](#realpagerequestgetrentmatrix) is an array of `RealPage::Model::RentMatrix`
instances. Each instance will have the following attributes:

* `lease_term` [Integer]
* `lease_term_max` [Integer]
* `lease_term_min` [Integer]
* `needed_by_date` [Date]
* `property_id` [String]
* `rows` [Array<[RealPage::Model::RentMatrix::Row](#realpagemodelrentmatrixrow)>]

##### RealPage::Model::RentMatrix::Concessions

* `monthly_fixed` [Float]
* `monthly_percent` [Float]
* `months` [Float]
* `one_time_fixed` [Integer]
* `total` [Integer]

##### RealPage::Model::RentMatrix::Option

* `best` [Boolean]
* `lease_end_date` [Date]
* `lease_start_date` [Date]
* `lease_term` [Integer]
* `concessions` [[RealPage::Model::RentMatrix::Concessions](#realpagemodelrentmatrixconcessions)]
* `rent` [Integer]

##### RealPage::Model::RentMatrix::Row

* `building` [String]
* `lease_end_date` [Date]
* `lease_start_date` [Date]
* `make_ready_date` [Date]
* `max_rent` [Integer]
* `min_rent` [Integer]
* `options` [Array<[RealPage::Model::RentMatrix::Option](#realpagemodelrentmatrixoption)>]
* `rent` [Integer]
* `unit` [String]
* `ys_quote_id` [String]

#### RealPage::Model::Screening

Screening conducted on a [RealPage::Model::Prospect](#realpagemodelprospect)
before their application is accepted.

* `apg_id` [String]
* `app_id` [String]
* `customer_id` [Integer]
* `customer_name` [String]
* `external_screening_service` [String]
* `result_code` [String]
* `result_date` [String]
* `result` [String]

#### RealPage::Model::Unit

The response from [GetUnitsByProperty](#realpagerequestgetunitsbyproperty) is an array of `RealPage::Model::Unit`
instances. Each instance will have the following attributes:

* `address_1` [String]
* `address_2` [String]
* `available` [Boolean]
* `available_date` [Date]
* `base_rent_amount` [Float]
* `building_id` [Integer]
* `city_name` [String]
* `county_name` [String]
* `country_name` [String]
* `description` [String]
* `deposit_amount` [Float]
* `floor_number` [String]
* `floor_plan_id` [Integer]
* `floor_plan_market_rent` [Float]
* `fp_report_unit_occupancy` [Boolean]
* `gross_sqft_count` [String]
* `hearing` [Boolean]
* `id` [Integer]
* `last_action_code` [String]
* `last_action_desc` [String]
* `lock` [Boolean]
* `lock_owner` [String]
* `made_ready` [Boolean]
* `made_ready_date` [Date]
* `market_rent` [Float]
* `mobility` [Boolean]
* `nonrefund_fee` [Float]
* `nonrevenue_description` [String]
* `nonrevenue` [Boolean]
* `note_description` [String]
* `number` [String]
* `pmc_id` [String]
* `property_number_id` [Integer]
* `rent_sqft_count` [String]
* `reserve` [Boolean]
* `reserved_until` [Date]
* `site_id` [String]
* `state` [String]
* `unavailable_code` [String]
* `vacant` [Boolean]
* `vacant_date` [Date]
* `vision` [Boolean]
* `zip` [String]

#### RealPage::Model::UnitShown

A unit shown to a [RealPage::Model::Prospect](#realpagemodelprospect) during a
site visit.

* `activity_date` [Date]
* `activity_id` [String]
* `activity_name` [String]
* `activity_time` [String]
* `agent_id` [Integer]
* `agent_name` [String]
* `building` [String]
* `building_unit` [String]
* `create_date` [Date]
* `edit_type_name` [String]
* `guest_card_journal_type_edit_id` [String]
* `guest_card_journal_type_id` [String]
* `logged_by_name` [String]
* `market_rent` [Float]
* `max_create_date_time` [Integer]
* `notes` [String]
* `result` [String]
* `site` [String]
* `site_id` [String]
* `status` [String]
* `unit_applied` [Boolean]
* `unit_id` [Integer]
* `unit_number` [String]
* `unit_reserved` [Date]
* `unit_status` [Integer]

### Request Parameter Objects

These objects are used as parameters to request objects

#### RealPage::Parameter::ListCriterion

A request parameter used to filter lists (e.g. [GetUnitsByProperty](#realpagerequestgetunitsbyproperty)).
A ListCriterion takes the following parameters

* `max_value` Maximum of List Criterion to be retrieved
* `min_value` Minimum value of List Criterion to be retrieved
* `name` Name of List Criterion to be retrieved
* `single_value` Value of List Criterion to be retrieved

### 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.

#### RealPage::Request::GetFloorPlanList

##### Initialization parameters

* `list_criteria` [Array<[RealPage::Parameter::ListCriterion](#realpagelistcriterion)>] criteria used to filter the results
* `pmc_id` [String] the unique identifier for the property management company in RealPage
* `site_id` [String] the unique identifier for the property in RealPage

##### Response

Array<[RealPage::Model::FloorPlan](#realpagemodelfloorplan)>

#### RealPage::Request::GetLeasesByTrafficSource

##### Initialization parameters

* `end_date` [Date] the end of the date range for the query
* `pmc_id` [String] the unique identifier for the property management company in RealPage
* `site_id` [String] the unique identifier for the property in RealPage
* `start_date` [Date] the start of the date range for the query
* `traffic_source_id` [String] the identifier for the marketing/traffic source used to query leases

##### Response

Array<[RealPage::Model::Lease](#realpagemodellease)>

#### RealPage::Request::GetMarketingSourcesByProperty

##### Initialization parameters

* `pmc_id` [String] the unique identifier for the property management company in RealPage
* `site_id` [String] the unique identifier for the property in RealPage

##### Response

Array<[RealPage::Model::PicklistItem](#realpagemodelpicklistitem)>

#### RealPage::Request::GetRentMatrix

##### Initialization parameters

* `lease_term` [Integer] the term (in months) of the lease
* `need_by_date` [Date] the date the unit(s) is/are needed by
* `pmc_id` [String] the unique identifier for the property management company in RealPage
* `site_id` [String] the unique identifier for the property in RealPage
* `unit_ids` [Array<Integer>] the array of unit IDs to get pricing data for
* `viewing_quote_only` [Boolean] identifies whether the user is viewing or creating new quote

##### Response

Array<[RealPage::Model::RentMatrix](#realpagemodelrentmatrix)>

#### RealPage::Request::GetUnitsByProperty

##### Initialization parameters

* `list_criteria` [Array<[RealPage::Parameter::ListCriterion](#realpagelistcriterion)>] criteria used to filter the results
* `pmc_id` [String] the unique identifier for the property management company in RealPage
* `site_id` [String] the unique identifier for the property in RealPage

##### Response

Array<[RealPage::Model::Unit](#realpagemodelunit)>

#### RealPage::Request::ProspectSearch

##### Initialization parameters

* `guest_card_id` [String] the unique identifier for the guest card to fetch
* `pmc_id` [String] the unique identifier for the property management company in RealPage
* `site_id` [String] the unique identifier for the property in RealPage

##### Response

Array<[RealPage::Model::GuestCard](#realpagemodelguestcard)>

### Errors

#### RealPage::Error::Base

The base class for all RealPage errors

#### RealPage::Error::BadRequest

Raised when a RealPage request has an error node in the contents. This is generally
the case when one of the parameters in a section other than the auth section is invalid.

Includes an `#errors` array that includes all errors returned by the request. (The value
of `#message` will be the value of all <errormessage> elements concatenated together with a
semicolon delimiter.) Each item in the `#errors` array responds to

* `#message`
* `#internal_message`
* `#severity`

#### RealPage::Error::InvalidConfiguration

Raised when RealPage is not properly configured

#### RealPage::Error::RequestFault

Raised when a RealPage request has a fault node, which general appears when there is
an issue with the auth section in the request (e.g. invalid password)

Includes a `#fault_code` attribute based on the code returned in the response

## Development

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` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).

## Contributing

1. Fork it ( https://github.com/[my-github-username]/real_page/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request