MITS 4.0 Lead Management

PostLeadManagement4_0

This method is to be used to add or update prospect records, including the people on the prospect record, their preferences, and any events that need to be recorded.

Request

Data is added or updated by performing a HTTP Post to https://api.myresman.com/MITS/PostLeadManagement4_0 supplying the listed parameters below.

Parameters

Name	Description	Example	Required
IntegrationPartnerID	The ID assigned to your company by ResMan	1000	Yes
ApiKey	The API key assigned to your company by ResMan	a5w7d9g2m04…	Yes
AccountID	The AccountID associated with the property	400	Yes
PropertyID	The PropertyID associated with the property	07413576-f764-44c6-be35-df4139deec01	Yes
Xml	The MITS Lead Managment 4.0 compliant xml Update: 12/16/2020 Communication types	See below	Yes

The following demonstrates one way of submitting a request to the PostLeadManagment4_0 method using C#.

NameValueCollection postData = new NameValueCollection();

// Integration Partner values

postData["IntegrationPartnerID"] = "1000";

postData["ApiKey"] = "6aw7y9m3m04849lqld6em9sudl5fg01u";

// Account and property specific data

postData["AccountID"] = "400";

postData["PropertyID"] = "07413576-f764-44c6-be35-df4139deec01";

// Method specific parameters

postData["Xml"] = “<LeadManagement>...</LeadManagement>”;

string url = "https://api.myresman.com/MITS/PostLeadManagement4_0";

WebClient client = new WebClient();

byte[] response = client.UploadValues(url, "POST", postData);

string strResponse = System.Text.Encoding.Default.GetString(response);

Posting Xml Parameter

Below is example XML following the MITS Lead Management 4.0 standard to create a new prospect record. The remainder of this document will go through each section of the example below explaining how the data in each will be used and what data to include in order to make new and update requests.

Example XML - PostLeadManagement4_0.xml

<Name>

<LastName>Prospect</LastName>

</Name>

<City>Provo</City>

</Address>

<Email>amy@prospect.com</Email>

</Phone>

</Customer>

</Customers>

</DesiredUnit>

</CustomerPreferences>

<Agent>

<LastName>Leasing</LastName>

</AgentName>

</Agent>

<TransactionSource>FBCCF0C7-AF4A-4512-9378-8A5A1CB1F0C1</TransactionSource>

</Event>

<Agent>

<LastName>Leasing</LastName>

</AgentName>

</Agent>

<FirstContact>false</FirstContact>

<Comments>Submit Application</Comments>

<Quote>

</Quote>

</Quotes>

</Event>

</Events>

</Prospect>

</Prospects>

</LeadManagement>

Response

When submitting a request to the PostLeadManagment4_0, you will receive a response following the pattern below. The response will include information about the method that was called as well as a status indicating whether or not the request was successful. If there was an error in the request, the ErrorDescription node will identify any problems with the request. In addition the submitted request XML will be included in the Response node and will be modified to include various Identification nodes containing the values that will need to be included when updating an existing record.

<MethodName>PostLeadManagement4_0</MethodName>

<Status>Success</Status>

<Response>[Submitted request xml with added identification nodes]</Response>

</ResMan>

The next few sections of this document will explain each node of the LeadManagement xml that is accepted and returned.

Customers Node

This node contains at least one Customer node. Each customer node will either create or update a person record for the indicated prospect.

Adding a New Prospect

Providing a Customer node without a ResMan Identification node with an ID Type of “ProspectID” will create a new prospect.

<Name>

<LastName>Prospect</LastName>

</Name>

<AddressLine1>321 Center Str.</AddressLine1>

<City>Beach View</City>

</Address>

<Email>amy@prospect.com</Email>

</Phone>

</Customer>

</Customers>

Updating an Existing Prospect

Providing a Customer node with an Identification node with an IDType of “ProspectID” and an identification node with an IDType of “PersonID” and both with an OrganizationName of “ResMan” will update the prospect tied to those IDs.

<Name>

<MiddleName>Wilcox</MiddleName>

<LastName>Prospect</LastName>

</Name>

<City>Provo</City>

</Address>

<Email>amy@prospect.com</Email>

</Phone>

</Phone>

</Customer>

</Customers>

Adding a Roommate to an Existing Prospect

Providing a Customer node with an Identification node with an IDType of “ProspectID” and an OrganizationName of “ResMan” but without an Identification node with an IDType of “PersonID” will add a roommate to the prospect record.

<Name>

<LastName>Prospect</LastName>

</Name>

<City>Provo</City>

</Address>

<Email>amy@prospect.com</Email>

</Phone>

</Customer>

<Name>

<FirstName>Nicole</FirstName>

<LastName>Prospect</LastName>

</Name>

<City>Provo</City>

</Address>

<Email>nicole@Prospect.com</Email>

</Phone>

</Customer>

</Customers>

Customers Node Response

In the response, each Customer node will include two Identification nodes, one with an ID Type of “ProspectID” (identifies the group of prospects) and one with an ID Type of “PersonID” (identifies an individual person). The OrganizationName attribute for both Identification nodes will have a value of “ResMan”.

<Name>

<LastName>Prospect</LastName>

</Name>

<City>Provo</City>

</Address>

<Email>amy@prospect.com</Email>

</Phone>

</Customer>

</Customers>

Customers Node Possible Errors

If any errors occur while parsing the XML sent to the API, they will be returned in two ways; aggregated in the ErrorDescription node and in the Response node. The ErrorDescription node contains a list of error messages logged while parsing the XML. The Response node contains the original XML as well as Error nodes where errors were found.

The following errors will be logged and returned:

“Missing Customer Type attribute” - A Customer node is missing a Type attribute
"Missing Identification IDValue attribute" - A Customer Identification node is missing an IDValue attribute
"Invalid IDType and Organization Name" - An Identification node has an organization name of “ResMan”, but not an IDType of “ProspectID” or “PersonID”
"Missing Customer Name node" - A Customer node is missing a Name node
"Missing Customer FirstName node" - A Customer Name node is missing a FirstName node
"Missing Customer LastName node" - A Customer Name node is missing a LastName node
"At least one customer is required" - There are not Customer nodes present

Below is an example response if a customer node is missing a Type attribute:

<MethodName>PostLeadManagement4_0</MethodName>

<Status>Error</Status>

<ErrorDescription>Missing Customer Type attribute</ErrorDescription>

<Name>

<LastName>Prospect</LastName>

</Name>

...

<Error>Missing Customer Type attribute</Error>

</Customers>

...

</Prospect>

</Prospects>

</LeadManagement>

</Response>

</ResMan>

CustomerPreferences Node

This node contains specific information about the kind of unit the prospect might be interested in leasing.

When sending the CustomerPreferences node, please follow the guidelines below:

All customer preferences need to be included when either adding or updating a prospect as they will be overwritten upon each request.
The value of the DesiredFloorplan node must match a valid FloorplanID which can be found in the response returned from a call to the ResMan API method GetMarketing2_0.
The value of the MarketingName in the DesiredUnit node must match a valid UnitID which can be found in the response returned from a call to the ResMan API method GetMarketing2_0.

</DesiredUnit>

<Comment>Needs to move in quickly</Comment>

</CustomerPreferences>

CustomerPreferences Node Response

The XML returned in the response will be the same as the XML sent unless there are any errors while parsing the original XML.

CustomerPreferences Node Possible Errors

The following errors will be logged and returned:

"Missing Pet Count attribute" - A Pets node does not contain a Count attribute
"Missing Pet Type attribute" - A Pets node does not contain a Type attribute
"Pet weight should be an integer value (in pounds)" - The Weight attribute of a Pets node is cannot be converted to an integer

Below is an example response if a Pets node is missing the Count and a Type attributes.

<MethodName>PostLeadManagement4_0</MethodName>

<Status>Error</Status>

Missing Pet Count attribute

Missing Pet Type attribute

</ErrorDescription>

...

</DesiredUnit>

<Pets>

<Error>Missing Pet Count attribute</Error>

<Error>Missing Pet Type attribute</Error>

</Pets>

</CustomerPreferences>

...

</Prospect>

</Prospects>

</LeadManagement>

</Response>

</ResMan>

CustomerPreferences Node Unused Nodes

There is some data supported in the MITS specification that is not currently supported by ResMan. The following CustomerPreference elements or attributes will not be used if sent:

DesiredLeaseTerms
NumberOfOccupants
Amenities

AmenityType
Subtype
Description
Rank

AdditionalPreferenceType
Comment

Events Node

This node contains at least one Event node. Each Event node will either create or update a note record for the prospect in ResMan.

When sending the Event nodes, please follow the guidelines below:

There must be exactly one Event node that contains a FirstContact node with a value of true.
The event mentioned above must contain a TransactionSource node with a value matching a ProspectSourceID retrieved from the ResMan API method GetProspectSources (See Leasing API Documentation).
Each Event node must have an Agent node that contains an AgentID with an IDValue that matches an EmployeeID from the ResMan API method GetEmployees (See Leasing API Documentation).
After a new event is sent to ResMan, the response will include a new EventID node that will contain the ResMan EventID for the event. If this event needs to be updated in a future call, this ID must be used in the EventID node.
Supplying an EventID node with an OrganizationName of ResMan indicates that the Event has already been added to ResMan and will be updated if there have been any changes made to the Event.
An event with an EventType of Cancel indicates that the prospect has been lost and the TransactionSource must match an ID from the ResMan API method GetLostProspectReasons (see Leasing API Documentation).
An EventID node with IDType=“Unit” can be used to indicate what units where shown. The IDValue=“1008” will indicate the unit that was shown. Multiple EventID nodes of IDType=“Unit” can be supplied if more than one unit was shown. Remember to include in all the EventID nodes OrganizationName=“ResMan”. Also, in order for the Units Shown to show up on the ResMan communication log note, the EventType of the Event node must be “Show”.

Adding a New Event

The example below demonstrates how to add three new events to a prospect record.

<Agent>

<FirstName>Andrew</FirstName>

<LastName>Oliver</LastName>

</AgentName>

</Agent>

<TransactionSource>FBCCF0C7-AF4A-4512-9378-8A5A1CB1F0C1</TransactionSource>

</Event>

<Agent>

<FirstName>Andrew</FirstName>

<LastName>Oliver</LastName>

</AgentName>

</Agent>

<FirstContact>false</FirstContact>

<Comments>Submit Application</Comments>

<Quote>

</Quote>

</Quotes>

</Event>

<Agent>

<FirstName>Andrew</FirstName>

<LastName>Oliver</LastName>

</AgentName>

</Agent>

<FirstContact>false</FirstContact>

<TransactionSource>FBCCF0C7-AF4A-4512-9378-8A5A1CB1F0C1</TransactionSource>

</Event>

</Events>

The table below shows the resulting Contact Type and Interaction Type from the EventType included in the event node.

Updated 12/16/2020: Added new event type

EventType	ContactType	InteractionType
EmailToProspect	Email	FollowUp
EmailFromILS	Email	FollowUp
EmailFromProspect	Email	FollowUp
Email	Email	FollowUp
CallToProspect	Phone	FollowUp
CallFromProspect	Phone	FollowUp
Phone	Phone	FollowUp
Show	FaceToFace	UnitShown
WalkIn	FaceToFace	UnitNotShown
Appointment	Other	FollowUp
Contact	Other	FollowUp
Other	Other	FollowUp
Cancel	Other	Other
ReActivate	Other	Other/FollowUp
TextToProspect	Text Message	Text
TextFromProspect	Text Message	Text

Updating an Existing Event

The example below demonstrates how to update an existing event; note the EventID node specifies a ResMan EventID with the OrganizationName specified as ResMan.

<Agent>

</Agent>

<TransactionSource>FBCCF0C7-AF4A-4512-9378-8A5A1CB1F0C1</TransactionSource>

<Comments>Looking to move in on 8/1/2013</Comments>

</Event>

</Events>

Event Node Response

The XML returned in the response will have a new EventID node with an ID Type of “EventID” and an OrganizationName of ResMan.

<Agent>

<FirstName>Andrew</FirstName>

<LastName>Oliver</LastName>

</AgentName>

</Agent>

<TransactionSource>FBCCF0C7-AF4A-4512-9378-8A5A1CB1F0C1</TransactionSource>

</Event>

<Agent>

<FirstName>Andrew</FirstName>

<LastName>Oliver</LastName>

</AgentName>

</Agent>

<FirstContact>false</FirstContact>

<TransactionSource>FBCCF0C7-AF4A-4512-9378-8A5A1CB1F0C1</TransactionSource>

<Comments>Submit Application</Comments>

<Quote>

</Quote>

</Quotes>

</Event>

</Events>

Event Node Possible Errors

The following errors will be logged and returned:

"Missing EventType attribute" - The Event does not have an EventType attribute
"Missing EventDate attribute" - The Event does not have an EventDate attribute
"Unable to parse the EventDate attribute" - The EventDate cannot be converted to a DateTime
"Unable to parse the EventID IDValue attribute" - The IDValue attribute of the EventID node could not be converted to a Guid
"Missing Agent node" - There is no Agent node
"Missing AgentID node" - There is no AgentID node
"Missing AgentID IDValue attribute" - There is no IDValue attribute in the AgentID node
"Unable to parse the AgentID IDValue attribute" - The IDValue attribute of the AgentID could not be converted to a Guid
"Leasing agent could not be found" - The IDValue attribute of the AgentID node does not match an EmployeeID for the indicated property
"Missing TransactionSource node" - There is no TransactionSource node
"Unable to parse TransactionSource value" - The value in the TransactionSource node could not be converted to a Guid
"Transaction Source could not be found" - There is not a Prospect Source that matches the ProspectSourceID passed in
"At least one event is required" - There is not at least one Event node
"There must be exactly one event where FirstContact = true" - There are 0 or more than 1 events where the FirstContact node has a value of true
"The customer [name] has already been added" - A customer with a matching name, email, and phone has already been added within the last 24 hours

Below is an example response if the Event node is missing the Agent node.

<MethodName>PostLeadManagement4_0</MethodName>

<Status>Error</Status>

Missing Agent node

</ErrorDescription>

...

<Agent>

<FirstName>Andrew</FirstName>

<LastName>Oliver</LastName>

</AgentName>

</Agent>

<TransactionSource>FBCCF0C7-AF4A-4512-9378-8A5A1CB1F0C1</TransactionSource>

<Error>Missing Agent node</Error>

</Event>

</Events>

</LeadManagement>

</Response>

</ResMan>

Event Node Unused Nodes

There is some data supported in the MITS specification that is not currently supported by ResMan. The following Event elements or attributes will not be used if sent:

CallData

CallerID
CallFrom
CallThrough
RingThrough
Duration
CallStatus
AudioLink
CallTracker

EmailData

MessageID
EmailDate
EmailAddresses

EmailAddress

Scope

Subject
EmailBody
IsHTML

Event Types

The table below lists the possible MITS Event Types and what action will be performed during that particular event.

MITS Event Type	Action Performed
Cancel	The prospect will be marked as lost
Appointment	A new calendar appointment will be created

SearchProspects

This method is to be used to find existing prospect records in ResMan based on specific search criteria.

Request

Data is requsted by performing a HTTP Post to https://api.myresman.com/MITS/SearchProspects supplying the listed parameters below.

Parameters

Name	Description	Example	Required
AccountID	The AccountID associated with the property	400	Yes
PropertyID	The PropertyID associated with the property	07413576-f764-44c6-be35-df4139deec01	Yes
FirstName	The first name of the prospect	Robert	No
LastName	The last name of the prospect	Parr	No
Phone	The phone number of the prospect	(716) 763-5624	No
Email	The email of the prospect	robert@email.com	No
Address	The address of the prospect	123 Ewe Turn	No
StartDate	The date to begin searching for events	2013-12-01	No
EndDate	The date to stop searching for events	2013-12-31	No
ProspectID	The prospect id of the prospect	20d3c1d4-e3bd-47a5-9309-e884e98c96d6	No
PersonID	The person id of the one of the roommates on the prospect record	430af556-d211-42fd-a3cf-7a237a021e40	No
ModifiedStartDateTime	The date and time before the prospect was last modified (UTC Time)	2013-12-30 21:44:13.206	No
ModifiedEndDateTime	The date and time after the prospect was last modified (UTC Time)	2013-12-31 22:45:14.207	No
IncludeHouseholdStatus	The Household Status for the prospect	true/false	No

While none of the search parameters above are required, at least one must be provided or the call will fail with an error message of “At least one search parameter must be supplied”.

If IncludeHouseholdStatus is enabled, household statuses will only show if they are an applicant or resident.

The following demonstrates one way of submitting a request to the SearchProspects method using C#.

NameValueCollection postData = new NameValueCollection();

// Account and property specific data

postData["AccountID"] = "400";

postData["PropertyID"] = "07413576-f764-44c6-be35-df4139deec01";

// Search parameters

postData["FirstName"] = "Robert";

postData["LastName"] = "Parr";

string url = "https://api.myresman.com/MITS/SearchProspects";

WebClient client = new WebClient();

byte[] response = client.UploadValues(url, "POST", postData);

string strResponse = System.Text.Encoding.Default.GetString(response);

Response

The response will be provided in xml following the MITS Lead Management 4.0 standard, and it will contain information about the prospects found, including contact information, preferences, and any events recorded about the prospect.

Name	Description
Customer	Information about a person on the prospect record
CustomerPreferences	Specific preferences that the prospect is looking for
Event	Information about any contact with the prospect

Possible Event Types

The table below lists the possible MITS Event Types that will be returned and what action was performed during that particular event. Note that there may be other event types returned in the response that are ResMan specific and don’t necessarily correlate to a MITS specific Event Type.

MITS Event Type	Action Performed
Cancel	The prospect was marked as lost
Application	The prospect was converted to an applicant
Approve	The application was approved
ApplicationDenied	The application was denied
CancelApplication	The application was cancelled
LeaseSign	The lease was signed
MoveIn	The applicants were moved into a unit
MoveOut	The residents were moved out of the unit

The following are non-MITS types

Non-MITS Event Type	Action Performed
EmailToProspect	Email was sent.
EmailFromILS	Tracking email from an ILS.
EmailFromProspect	Email from a prospect
Email	Unspecified email.
CallToProspect	Phone call outbound to a prospect.
CallFromProspect	Phone call inbound to a prospect.
Phone	Unspecified phone (includes text)
Show	A unit was shown.
WalkIn	An on site face to face visit.
Appointment	A scheduled appointment (future or past)
Contact	Unspecified contact
Other	Other

Possible Customer Types

The table below lists the possible MITS customer types that will be returned. Note that this includes records that were prospects at one time and may now be in other phases of the resident life-cycle.

Customer Type	Description
Prospect	A prospect record that’s currently active.
Applicant	This person is in the application process.
Current_Resident	The person was moved into a unit.
Former_Resident	The resident was moved out of a unit.
Lost	A prospect record that was marked as lost and is now inactive.

Below is an example of the response that can be expected from this method.

<Status>Success</Status>

<Response>[Encoded MITS Lead Management 4.0 XML Response]</Response>

</ResMan>

Example MITS Lead Management 4.0 XML Response

<Name>

<FirstName>Robert</FirstName>

</Name>

<City>Dallas</City>

</Address>

<Phone>

</Phone>

<Email>robert@email.com</Email>

<HouseholdStatus>Head of Household</HouseholdStatus>

</Customer>

<Name>

</Name>

<City>Dallas</City>

</Address>

<HouseholdStatus>Dependant</HouseholdStatus>

</Customer>

</Customers>

</DesiredUnit>

</CustomerPreferences>

<Agent>

<Name>

<LastName>Manager</LastName>

</Name>

</Agent>

<EventReasons>Initial contact</EventReasons>

</Event>

</Events>

</Prospect>

Example MITS Lead Management 4.0 XML Response for a Prospect with a roomate

<Identification IDType="ProspectID"

IDValue="75494445-cb3a-4a70-8593-e17dad7e9e7a" OrganizationName="ResMan" />

<Identification IDType="PersonID"

IDValue="e6dbd523-b38d-4707-95c5-e48ab781f7ac" OrganizationName="ResMan" />

<Identification IDType="LeaseID"

IDValue="e2a733d9-9406-467f-8790-d6d90c7bf103" OrganizationName="ResMan" />

<Name>

<FirstName>Emilie</FirstName>

<LastName>Chavez</LastName>

</Name>

<Phone>

</Phone>

<Email>emilie.chavez@myresman.com</Email>

<HouseholdStatus>Head of Household</HouseholdStatus>

</Customer>

<Identification IDType="ProspectID"

IDValue="75494445-cb3a-4a70-8593-e17dad7e9e7a" OrganizationName="ResMan" />

<Identification IDType="PersonID"

IDValue="0ed8afe7-2366-4ad3-a803-75c8d9e1e882" OrganizationName="ResMan" />

<Identification IDType="LeaseID"

IDValue="e2a733d9-9406-467f-8790-d6d90c7bf103" OrganizationName="ResMan" />

<Name>

<LastName>Chavez</LastName>

</Name>

</Customer>

</Customers>

</CustomerPreferences>

<EventID IDType="EventID" IDValue="5e7a3eff-1686-4dfd-86f2-9b576373f9a0"

OrganizationName="ResMan" />

<Agent>

<FirstName>Minnie</FirstName>

<LastName>Manager</LastName>

</AgentName>

</Agent>

<EventReasons>Lease Signed</EventReasons>

<Comments>Emilie Chavez</Comments>

</Event>

<EventID IDType="EventID" IDValue="5d0f09bb-4f50-4251-b3af-540c1232ba4f”

OrganizationName="ResMan" />

<Agent>

<FirstName>Alivia</FirstName>

<LastName>Graham</LastName>

</AgentName>

</Agent>

<EventReasons>Initial contact</EventReasons>

<FirstContact>false</FirstContact>

</Event>

<Agent>

<FirstName>Minnie</FirstName>

<LastName>Manager</LastName>

</AgentName>

</Agent>

<EventReasons>Lease Signed</EventReasons>

<FirstContact>false</FirstContact>

<Comments>Jay Chavez</Comments>

</Event>

</Events>

</Prospect>