PostLeadManagement4_0

This method is to be used to add prospect records, including the people on the prospect record, their preferences, and any events that need to be recorded.  Note that this method is intended to allow the posting of a guest card with minimal information but all values in the MITS Lead Management 4.0, except those listed below, are supported.

Request

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

Parameters

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

NameValueCollection postData = new NameValueCollection();

// Integration Partner values

postData["IntegrationPartnerID"] = "1000";

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

// Method specific parameters

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

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

WebClient client = new WebClient();                

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

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

Note that if you can’t provide the IntegrationPartnerID or ApiKey as parameters to the method, they can be included as a query string parameter on the url:

string url = "https://api.myresman.com/MITSLite/PostLeadManagement4_0?IntegrationPartnerID=1000&ApiKey=6aw8...";

Also, if you cannot provide a parameter named Xml that contains the MITS Lead Management 4.0 XML, it can be provided as the body of the HTTP Post.

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.

<LeadManagement>

         <Prospects>

                 <Prospect>

                         <Customers>

                                 <Customer Type="prospect">

                                         <Identification IDType="PropertyID" IDValue="1234" />

                                         <Name>

                                                 <FirstName>Amy</FirstName>

                                                 <MiddleName>Rebecca</MiddleName>

                                                 <LastName>Prospect</LastName>

                                         </Name>

                                         <Address AddressType="current">

                                                 <AddressLine1>1234 Main St</AddressLine1>

                                                 <AddressLine2>#480</AddressLine2>

                                                 <City>Provo</City>

                                                 <State>UT</State>

                                                 <PostalCode>84601</PostalCode>

                                         </Address>

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

                         <Phone PhoneType="cell">

                                 <PhoneNumber>(904) 555-5555</PhoneNumber>

                                         </Phone>

                                 </Customer>

                         </Customers>

                         <CustomerPreferences>

                                 <DesiredFloorplan>2B2b</DesiredFloorplan>

                 <DesiredUnit>

                                         <MarketingName>1008</MarketingName>

                 </DesiredUnit>

                 <DesiredRent Exact="850.00" />

                 <DesiredNumBedrooms Exact="1" />

                 <DesiredLeaseTerms>1</DesiredLeaseTerms>

                         </CustomerPreferences>

                         <Events>

                 <Event EventDate="2013-09-06T13:23:35.944" EventType="WalkIn">

     <Comments>Interested in a two bedroom apartment</Comments>

     <FirstContact>true</FirstContact>              

                                 </Event>

                        </Events>

                 </Prospect>

         </Prospects>

</LeadManagement>

Response

When submitting a request to PostLeadManagement4_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.

<ResMan>

          <MethodName>PostLeadManagement4_0</MethodName>

          <Status>Success</Status>

          <ErrorDescription />

          <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.  Note that an Identification node with type IDType of PropertyID must be provided in the Customers > Customer node to identify which property the guest card should be added.  Providing ResMan’s PropertyID is the preferred method of use but if this is not possible, custom arrangements can be made.

Customers Node Response

In the response, each Customer node will include at least 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”.

<Customers>

<Customer Type="prospect">

                <Identification IDType="PropertyID" IDValue="1234" />

                <Identification IDType="ProspectID" IDValue="60396bb1-96c6-4570-abf9-29666ccaac79" OrganizationName="ResMan" />

                <Identification IDType="PersonID" IDValue="31d638fb-500d-4f22-b907-386b85ff9358" OrganizationName="ResMan" />

                <Name>

          <FirstName>Amy</FirstName>  

          <LastName>Prospect</LastName>

        </Name>

<Address AddressType="current">

          <AddressLine1>123 Main St</AddressLine1>

          <City>Provo</City>

          <State>UT</State>

          <PostalCode>84601</PostalCode>

        </Address>

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

        <Phone PhoneType="cell">

          <PhoneNumber>(801) 555-5555</PhoneNumber>

        </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:

<ResMan>

  <MethodName>PostLeadManagement4_0</MethodName>

  <Status>Error</Status>

  <AccountID>400</AccountID>

  <PropertyID>07413576-f764-44c6-be35-df4139deec01</PropertyID>

  <ErrorDescription>Missing Customer Type attribute</ErrorDescription>

  <Response>

        <LeadManagement>

          <Prospects>

            <Prospect>

              <Customers>

                <Customer>

                  <Name>

                    <FirstName>Amy</FirstName>

                    <MiddleName>X</MiddleName>

                    <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 GetMarketingX_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 GetMarketingX_0.

<CustomerPreferences>

          <TargetMoveInDate>2013-8-30</TargetMoveInDate>

          <DesiredFloorplan>2B2b</DesiredFloorplan>

          <FloorLevelDesired>1</FloorLevelDesired>

          <DesiredUnit>

                <MarketingName>1008</MarketingName>

          </DesiredUnit>

          <DesiredRent Exact="850" />

          <DesiredNumBedrooms Exact="2" />

          <DesiredNumBathrooms Exact="2" />

          <DesiredDeposit Exact="50" />

<Pets PetType="Cat" Count="1" Size="Small" Weight="8" />

          <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

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

<ResMan>

  <MethodName>PostLeadManagement4_0</MethodName>

  <Status>Error</Status>

  <AccountID>400</AccountID>

  <PropertyID>07413576-f764-44c6-be35-df4139deec01</PropertyID>

  <ErrorDescription>

        Missing Pet Count attribute

        Missing Pet Type attribute

  </ErrorDescription>

  <Response>

        <LeadManagement>

          <Prospects>

            <Prospect>

...

              <CustomerPreferences>

                <DesiredUnit>

                          <MarketingName>1008</MarketingName>

                </DesiredUnit>

                <DesiredRent Exact="850.00" />

                <DesiredNumBedrooms Exact="1" />

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

Adding a New Event

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

<Events>

          <Event EventDate="2013-09-06T13:23:35.944" EventType="WalkIn">

        <Agent>

          <AgentID IDValue="DAD9E28F-8BC2-4328-84F0-000662F435A0" />

          <AgentName>

            <FirstName>Andrew</FirstName>

            <LastName>Oliver</LastName>

          </AgentName>

        </Agent>

        <FirstContact>true</FirstContact>

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

          </Event>

          <Event EventDate="2013-09-06T13:23:35.944" EventType="Application">

        <Agent>

          <AgentID IDValue="DAD9E28F-8BC2-4328-84F0-000662F435A0" />

          <AgentName>

            <FirstName>Andrew</FirstName>

            <LastName>Oliver</LastName>

          </AgentName>

        </Agent>

        <FirstContact>false</FirstContact>        

        <Comments>Submit Application</Comments>

        <Quotes>

          <Quote>

                    <QuotedRent Exact="850" />

          </Quote>

        </Quotes>

          </Event>

</Events>

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.

<Events>

  <Event EventDate="2013-09-24T13:23:35.944" EventType="WalkIn">

        <EventID IDType="EventID" IDValue="d2e6e6ff-a334-4d4a-9804-13789f4afe7c" OrganizationName="ResMan" />

        <FirstContact>true</FirstContact>

        <Agent>

          <AgentID IDValue="DAD9E28F-8BC2-4328-84F0-000662F435A0" />

        </Agent>

<FirstContact>true</FirstContact>

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

<Events>

          <Event EventDate="2013-09-06T13:23:35.944" EventType="WalkIn">

<EventID IDType="EventID" IDValue="0bcb0975-33b4-40a7-8120-aa80d5b1b685" OrganizationName="ResMan" />

        <Agent>

          <AgentID IDValue="DAD9E28F-8BC2-4328-84F0-000662F435A0" />

          <AgentName>

            <FirstName>Andrew</FirstName>

            <LastName>Oliver</LastName>

          </AgentName>

        </Agent>

        <FirstContact>true</FirstContact>

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

          </Event>

          <Event EventDate="2013-09-06T13:23:35.944" EventType="Application">

                <EventID IDType="EventID" IDValue="0bc615aa-0bbd-42ca-8557-456b0b353b65" OrganizationName="ResMan" />

        <Agent>

          <AgentID IDValue="DAD9E28F-8BC2-4328-84F0-000662F435A0" />

          <AgentName>

            <FirstName>Andrew</FirstName>

            <LastName>Oliver</LastName>

          </AgentName>

        </Agent>

        <FirstContact>false</FirstContact>

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

        <Comments>Submit Application</Comments>

        <Quotes>

          <Quote>

                    <QuotedRent Exact="850" />

          </Quote>

        </Quotes>

          </Event>

</Events>

Event 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 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

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

<ResMan>

  <MethodName>PostLeadManagement4_0</MethodName>

  <Status>Error</Status>

  <AccountID>400</AccountID>

  <PropertyID>07413576-f764-44c6-be35-df4139deec01</PropertyID>

  <ErrorDescription>

        Missing Agent node

  </ErrorDescription>

  <Response>

        <LeadManagement>

          ...

              <Events>

                <Event EventDate="2013-09-06T13:23:35.944" EventType="WalkIn">

<Agent>        

<AgentID IDValue="DAD9E28F-8BC2-4328-84F0-000662F435A0" />

          <AgentName>

            <FirstName>Andrew</FirstName>

            <LastName>Oliver</LastName>

          </AgentName>

        </Agent>

                  <FirstContact>true</FirstContact>

<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