API Context

Most Service Providers and Operators will have Properties within their community. Managing the associations between these properties and customer accounts can be achieved with this API.

The Property Relationship Web Services API enables external systems to -

• Find a property relationship by identifier or external reference
• Update the external reference for a property relationship
• Associate a property with a customer account
• Find property relationships
• Acknowledge changes that have occurred for a property relationship by identifier or external reference.

External systems are required to authenticate to gain access to web services.

Concepts

Associating customer with properties

Customer accounts can be associated with properties through this API.

A property can be associated with one or more customers. A customer's relationship to a property can be one of the following:

• Occupier
• Owner
• Occupier + Owner (listed as both an occupier and an owner record).

A relationship cannot be removed, only ended.

Base URL

https://{your_company_name}.leapcities.com/api/v1/property-relationship

API

Get a Property Relationship by LEAP identifier / external reference

This enables an external system to retrieve information about a property relationship by the internal Leap property relationship identifier or by the external reference.

URL:
property-relationship/identifier
property-relationship/extid/external-reference

Where identifier or external-reference is the value for the required property relationship.

Method: GET

Error Response Codes:

• 404 The supplied identifier doesn't exist
• 404 The supplied external reference doesn't exist

Example Response:

<property-relationship xmlns="http://schema.majitek.com/leap-ws-v1.0" identifier="1" ref="http://company.leapcities.com/api/v1/property-relationship/1" 
unacked-since="2011-03-18T08:27:40.000+1100" extid="1234">
    <property identifier="PP-01" ref="http://company.leapcities.com/api/v1/properties/PP-01"  unacked-since="2011-03-18T08:27:40.000+1100" extid="XREF1"/>
    <account identifier="01234574" ref="http://company.leapcities.com/api/v1/customers/01234574"  unacked-since="2011-03-18T08:27:39.000+1100" extid="12345"/>
    <relationship>OCCUPIER</relationship>
    <start-date>2011-03-18</start-date>
</property-relationship>

Update the external reference for a property relationship

This method allows the external identifier to be set or updated on a property relationship. The external identifier can then be used for future queries and updates.

URL:
property-relationship/identifier/extid

Where identifier is the identifier for the required property relationship.

Method: POST

POST Parameters:

• extid - The new external reference to apply to the property relationship

Response Codes:

• 404 The supplied property relationship identifier does not exist.
• 409 The supplied external identifier is already in use by another property relationship.

Example

Request:

POST:

extid=MAX12345

Response:

 <ref xmlns="http://schema.majitek.com/leap-ws-v1.0" ref="http://company.leapcities.com/api/v1/property-relationship/1" identifier="1" extid="MAX12345"/>

Acknowledge changes to a property relationship

Allows an external system to acknowledge that it has dealt with the fact that there has been a creation or update to a property relationship.

Performing this POST will clear the unacknowledged-since flag on the property relationship. It does not affect the unacknowledged-since flag on any entity references. (eg account, property)

URL:
property-relationship/acked - * Uses LEAP identifiers to indicate which property relationships to clear the flag for.
property-relationship/external/acked - * Uses external identifiers to indicate which property relationships to clear the flag for.

Method: POST

Parameters:

• none

Response Codes:

• 404 The supplied property relationship identifier / external reference does not exist.

Example Request:

<acknowledgements>
 <acknowledgement>10000001</acknowledgement>
 <acknowledgement>10000002</acknowledgement>
</acknowledgements>

Associate a Property with a Customer Record

This enables an external system to associate a property to a customer record.

URL:
property-relationship/

Method: POST

Error Response Codes:

• 409 If a conflicting property-account association exists
• 404 If the supplied account doesn't exist
• 400 If the supplied account number is in invalid format

Example Request:

<associated-account>
    <account identifier="01234574"/>
    <property identifier="12345"/>
    <relationship>OWNER</relationship>
    <start-date>2010-01-12</start-date>
</associated-account>

Find Property Relationships

This method allows an external system to retrieve the property relationships in the system:

• acked - restricts results to only property relationships that have been acknowledged / or need to be acknowledged, as applicable. Not passing the parameter will result in find all.
• limit - number of results to return. Optional - default is 100. Maximum limit is 100.
• offset - number of results to skip. Used to page through results.

URL:
property-relationship/
Method: GET
Example Parameters:

• acked=false

Example Response:

<property-relationships xmlns="http://schema.majitek.com/leap-ws-v1.0">
<property-relationship xmlns="http://schema.majitek.com/leap-ws-v1.0" identifier="1" ref="http://company.leapcities.com/api/v1/property-relationship/1" 
unacked-since="2011-03-18T08:27:40.000+1100" extid="1234">
    <property identifier="PP-01" ref="http://company.leapcities.com/api/v1/properties/PP-01"  unacked-since="2011-03-18T08:27:40.000+1100" extid="XREF1"/>
    <account identifier="01234574" ref="http://company.leapcities.com/api/v1/customers/01234574"  unacked-since="2011-03-18T08:27:39.000+1100" extid="1234"/>
    <relationship>OCCUPIER</relationship>
    <start-date>2011-03-18</start-date>
</property-relationship>

<property-relationship xmlns="http://schema.majitek.com/leap-ws-v1.0" identifier="2" ref="http://company.leapcities.com/api/v1/property-relationship/2" 
unacked-since="2011-03-18T08:27:40.000+1100" extid="12345">
    <property identifier="PP-99" ref="http://company.leapcities.com/api/v1/properties/PP-99"  unacked-since="2011-03-18T08:27:40.000+1100" extid="XREF3"/>
    <account identifier="06543201" ref="http://company.leapcities.com/api/v1/customers/06543201"  unacked-since="2011-03-18T08:27:40.000+1100" />
    <relationship>OCCUPIER</relationship>
    <start-date>2011-03-18</start-date>
</property-relationship>
</property-relationships>