| Next Generation Building Services

Back To Home

Leap Plaza

Resources

Customer Web Services API

Skip to end of metadata
Go to start of metadata
Contents

API Context

Customer account details are exposed via the Customer Web Services API. This API enables you to:

  • Create new customer accounts
  • Update existing customer accounts
  • Change the customer login ID
  • View customer account details
  • Update the external identifier for a customer account
  • Acknowledge changes to a customer account
  • Add operator-visible comments to customer accounts
  • Find customer accounts by additional account fields.
  • Find all customer accounts.

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

Concepts

Add customer account

The following information can be specified for a customer:

Customer information
  • Email* - must be unique per community
  • Password* - strong password enforcement.
Personal information
  • Title
  • First Name*
  • Middle Name
  • Last Name*
  • Date of Birth (dd/mm/YY).
  • Nationality (Dropdown of countries)
  • Gender
Contact Information
  • Contact Phone
  • Other Phone
  • Residential Address
  • Residential State
  • Residential Postcode/ZIP
  • Residential Country
Billing Information
  • Billing Address
  • Billing State
  • Billing Postcode
  • Billing Country
Additional Fields
  • Field value
Communities
  • community*

This specifies the communities (Stores) that the customer belongs to. Note currently a customer can only belong to one community. Being able to send more than one community is an extension point for the future.

* Denotes a mandatory field.

NB. Billing address details are optional for self-registration/customer account creation, however, if not provided, the customer will be prompted to provide them at purchase time or when a payment is made.

Once a customer has been created, the first name and last name comprise the 'customer full name' (for example, Joseph Banks).

Types

Gender - one of MALE, FEMALE.

Base URL

Using the leapcities.com SSL certificate

https://{your_company_name}.leapcities.com/api/v1/customers

Using your own SSL certificate

https://api.{your_domain}.com/api/v1/customers

API

Create a customer account

This method allows an external system to create a new customer account.

URL:
customers/
Method: POST
Response Codes:

  • 201 Created - 
    <ref xmlns="http://schema.majitek.com/leap-ws-v1.0" ref="http://company.leapcities.com/api/v1/customers/123456" identifier="123456"/>


  • 400 Validation error 
    <error xmlns="http://schema.majitek.com/leap-ws-v1.0">
    <field-errors>
                <field xpath="/account/owner/bday" errorhint="invalid"/>
                <field xpath="/account/owner/name/given-name" errorhint="required"/>
                <field xpath="/account/owner/name/family-name" errorhint="required"/>
                <field xpath="/account/owner/email" errorhint="required"/>
    </field-errors>
</error>
  • 403 Forbidden if account limit is reached 
    <error xmlns="http://schema.majitek.com/leap-ws-v1.0">
    <message>Account limit reached.</message>
    <field-errors/>
</error>

Example Request:

<account>
    <owner>
        <email>joe@example.net</email>
        <password>newpassword</password>
        <name>
            <family-name>Banks</family-name>
            <given-name>Joseph</given-name>
            <additional-names>A</additional-names>
            <honorific-prefixes>Mr.</honorific-prefixes>
        </name>
        <bday>1974-09-08</bday>
        <gender>MALE</gender>
        <nationality code="US"/>
        <tel type="pref">(704) 451 3434</tel>
        <tel type="voice"></tel>
        <residential-address>
            <street-address>222 Example Street</street-address>
            <region>Example State</region>
            <postal-code>99221</postal-code>
            <country-name code="US"/>
        </residential-address>
    </owner>

    <billing-address>
        <street-address>10 Example Road</street-address>
        <postal-code>21345</postal-code>
        <region>Example State</region>
        <country-name code="US" />
    </billing-address>

    <additional-fields>
        <field key="crm-identifier">CRM123</field>
    </additional-fields>

    <communities>
        <community>original</community>
    </communities>

</account>

Update customer account details

This method allows an external system to update a customer's account details.

URL:
customers/identifier
customers/extid/external-identifier

Where identifier or external-identifier are the values for the required account.

Method: PUT
Error Response Codes:

  • 400 Invalid customer identifier
  • 404 Customer identifier not found or customer inactive
  • 409 Validation error 
    <error xmlns="http://schema.majitek.com/leap-ws-v1.0">
    <field-errors>
                <field xpath="/account/owner/bday" errorhint="required"/>
                <field xpath="/account/owner/name/given-name" errorhint="required"/>
                <field xpath="/account/owner/name/family-name" errorhint="required"/>
    </field-errors>
</error>


  • 201 Updated - 
    <ref xmlns="http://schema.majitek.com/leap-ws-v1.0" ref="http://company.leapcities.com/api/v1/customer/49927398716" identifier="49927398716" extid="CRM-123"/>

Example Request:

<account>
    <owner>
        <name>
            <family-name>Banks</family-name>
            <given-name>Joseph</given-name>
            <additional-names>B</additional-names>
            <honorific-prefixes>Mr.</honorific-prefixes>
        </name>
        <bday>1974-09-08</bday>
        <gender>MALE</gender>
        <nationality code="US"/>
        <tel type="pref">(704) 451 3434</tel>
        <tel type="voice"></tel>
        <residential-address>
            <street-address>1 A Street</street-address>
            <region>My State</region>
            <postal-code>90210</postal-code>
            <country-name code="US"/>
        </residential-address>
    </owner>

    <billing-address>
        <street-address>1 Bank Street</street-address>
        <postal-code>2345</postal-code>
        <region>California</region>
        <country-name code="US" />
    </billing-address>

    <additional-fields>
        <field key="crm-identifier">CRM123</field>
    </additional-fields>

    <communities>
        <community>original</community>
    </communities>

</account>

Change the customer login ID

This method allows an external system to update a customer's login id. This also changes their email address.

URL:
customers/identifier/change-login
customers/extid/external-identifier/change-login

Where identifier or external-identifier are the values for the required account.

Method: PUT
Error Response Codes:

  • 400 Validation error 
    <error xmlns="http://schema.majitek.com/leap-ws-v1.0">
    <field-errors>
        <field xpath="/change-login/login-id errorhint="required"/>
        <field xpath="/change-login/login-id errorhint="invalid"/>
    </field-errors>
</error>


  • 201 Updated - 
    <ref xmlns="http://schema.majitek.com/leap-ws-v1.0" ref="http://company.leapcities.com/api/v1/customer/49927398716" identifier="49927398716" extid="CRM-123"/>

Example Request:

<change-login>
    <login-id>user@exmaple.com</login-id>
</change-login-id>

Retrieve customer account details

This method allows an external system to retrieve customer account details.

URL:
customers/identifier
customers/extid/external-identifier

Where identifier or external-identifier are the values for the required account.

Method: GET
Error Response Codes:

  • 400 Invalid customer account identifier
  • 404 Customer account identifier or external identifier not found or account inactive

Example Response:

<account xmlns="http://schema.majitek.com/leap-ws-v1.0" identifier="01234574"
        ref="http://company.leapcities.com/api/v1/customers/01234574" extid="CRM-1234" unacked-since="2011-02-08T22:07:43.000+0000">
    <creation-time>2011-02-08T22:06:43.000+0000</creation-time>
    <account-status>Active</account-status>
    <owner>
        <full-name>Joseph Banks</full-name>
        <name>
            <family-name>Banks</family-name>
            <given-name>Joseph</given-name>
            <additional-names>J</additional-names>
            <honorific-prefixes>Mr.</honorific-prefixes>
        </name>
        <bday>1974-09-08</bday>
        <gender>MALE</gender>
        <nationality code="US"/>
        <email>user@example.net</email>
        <tel type="pref">(704) 451 3434</tel>
        <tel type="voice"></tel>
        <residential-address>
            <street-address>1 A Street</street-address>
            <region>My State</region>
            <postal-code>90210</postal-code>
            <country-name code="US"/>
        </residential-address>
    </owner>

    <billing-address>
        <street-address>1 Bank Street</street-address>
        <region>90210</region>
        <postal-code>90210</postal-code>
        <country-name code="US"/>
    </billing-address>

    <!-- This is read only.  Use the property relationship web service to create a relationship between an account and property -->
    <property-relationships>
        <property-relationship identifier="1" ref="http://company.leapcities.com/api/v1/property-relationship/1"  unacked-since="2011-03-17T16:34:29.000+1100"/>
    </property-relationships>

    <additional-fields>
        <field key="crm-identifier" label="CRM System Identifier">CRM123</field>
    </additional-fields>

    <communities>
        <community>original</community>
    </communities>

</account>

Update the external identifier for a customer account

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

URL:
customers/identifier/extid

Where identifier is the identifier for the required account.

Method: POST

POST Parameters:

  • extid - The new external identifier to apply to the customer account.

Error Response Codes:

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

Example

Request:

POST:

extid=CRM-56789

Response:

 <ref xmlns="http://schema.majitek.com/leap-ws-v1.0" ref="http://company.leapcities.com/api/v1/customers/000000001" identifier="000000001" extid="CRM-56789"/>

Acknowledge changes to a customer account

Allows an external system to acknowledge that it has dealt with the fact that there has been an update to a customer accounts.

Performing this POST will clear the unacked-since flag on the customer accounts. It does not affect the unacked-since flag on any entity references. (eg a property reference)

URL:
customers/acked
customers/external/acked

Method: POST

Parameters:

  • none

Example Request:

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

Error Response Codes:

  • 404 The supplied account identifier / external identifier does not exist.

Find customer accounts using additional fields

Additional account fields are custom information fields that can be used to capture information about your customers.

Finding a customer account by additional account field requires:

  • field-name - The unique key for the field to query.
  • field-value - The value to match on for the specified field.

URL:
/customers/by-additional-field/field-name/field-value

Where field-name and field-value are the values for the required additional field.

Method: GET

GET Parameters:

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

Error Response Codes:

  • 400 Invalid additional field name

Example Response:

<accounts xmlns="http://schema.majitek.com/leap-ws-v1.0">
	<account xmlns="http://schema.majitek.com/leap-ws-v1.0" identifier="01234574"
            ref="http://company.leapcities.com/api/v1/accounts/01234574" extid="CRM-123" unacked-since="2011-02-08T22:07:43.000+0000">
            <creation-time>2011-02-08T22:06:43.000+0000</creation-time>
            <account-status>Active</account-status>
	    <owner>
	        <full-name>James A Banks</full-name>
	        <name>
	            <family-name>Banks</family-name>
	            <given-name>James</given-name>
	            <additional-names>A</additional-names>
	            <honorific-prefixes>Mr.</honorific-prefixes>
	        </name>
	        <bday>1974-09-08</bday>
                <gender>MALE</gender>
                <nationality code="US"/>
	        <email>user@example.net</email>
	        <tel type="pref">(704) 451 3434</tel>
	        <tel type="voice"></tel>
                <residential-address>
                     <street-address>1 A Street</street-address>
                     <region>My State</region>
                     <postal-code>90210</postal-code>
                     <country-name code="US"/>
                </residential-address>
	    </owner>

	    <billing-address>
	        <street-address>1 A Street</street-address>
	        <region>My State</region>
	        <postal-code>3456</postal-code>
	        <country-name code="US"/>
	    </billing-address>

            <property-relationships>
                <property-relationship identifier="1" ref="http://company.leapcities.com/api/v1/property-relationship/1"  unacked-since="2011-03-17T16:34:29.000+1100"/>
            </property-relationships>

	    <additional-fields>
	        <field key="shoe-size" label="Shoe Size">Nine</field>
	        <field key="career-name"label="Career Name">pleb</field>
	    </additional-fields>

            <communities>
                <community>original</community>
            </communities>

	</account>
<accounts>

Find customer accounts using email address

Find accounts with a matching email address within a community

URL:
customers/by_email/community-key/email-address

Method: GET

Example Response:

<accounts xmlns="http://schema.majitek.com/leap-ws-v1.0">
	<account xmlns="http://schema.majitek.com/leap-ws-v1.0" identifier="01234574"
            ref="http://company.leapcities.com/api/v1/accounts/01234574" extid="CRM-123" unacked-since="2011-02-08T22:07:43.000+0000">
            <creation-time>2011-02-08T22:06:43.000+0000</creation-time>
            <account-status>Active</account-status>
	    <owner>
	        <full-name>James A Banks</full-name>
	        <name>
	            <family-name>Banks</family-name>
	            <given-name>James</given-name>
	            <additional-names>A</additional-names>
	            <honorific-prefixes>Mr.</honorific-prefixes>
	        </name>
	        <bday>1974-09-08</bday>
                <gender>MALE</gender>
                <nationality code="US"/>
	        <email>user@example.net</email>
	        <tel type="pref">(704) 451 3434</tel>
	        <tel type="voice"></tel>
                <residential-address>
                     <street-address>1 A Street</street-address>
                     <region>My State</region>
                     <postal-code>90210</postal-code>
                     <country-name code="US"/>
                </residential-address>
	    </owner>

	    <billing-address>
	        <street-address>1 A Street</street-address>
	        <region>My State</region>
	        <postal-code>3456</postal-code>
	        <country-name code="US"/>
	    </billing-address>

            <property-relationships>
                <property-relationship identifier="1" ref="http://company.leapcities.com/api/v1/property-relationship/1"  unacked-since="2011-03-17T16:34:29.000+1100"/>
            </property-relationships>

	    <additional-fields>
	        <field key="shoe-size" label="Shoe Size">Nine</field>
	        <field key="career-name"label="Career Name">pleb</field>
	    </additional-fields>

            <communities>
                <community>original</community>
            </communities>

	</account>
<accounts>

Add customer account comment

This method allows an external system to add an agent-visible comment to a customer account. NB. This comment is not visible to the customer.

URL:
customers/identifier/comments
customers/extid/external-identifier/comments

Where identifier or external-identifier are the values for the required account.

Method: POST
Error Response Codes:

  • 400 Invalid customer account identifier
  • 404 Customer account identifier or external identifier not found

Example Request:

<customer-update>
  <comment>Adding a comment to the customer account.</comment>
</customer-update>

Retrieve all customers

This method allows the retrieval of all customers.

URL:
customers

GET Parameters:

  • acked - restricts results to only customers with changes that have been acknowledged / or need to be acknowledged, as applicable.
  • 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.

The returned details may be filtered the by acked parameter.

Method: GET
Example Parameters:

  • acked=true

Error Codes:

Example Response:

<accounts xmlns="http://schema.majitek.com/leap-ws-v1.0">
	<account xmlns="http://schema.majitek.com/leap-ws-v1.0" identifier="01234574"
            ref="http://company.leapcities.com/api/v1/accounts/01234574" extid="CRM-123" unacked-since="2011-02-08T22:07:43.000+0000">
            <creation-time>2011-02-08T22:06:43.000+0000</creation-time>
            <account-status>Active</account-status>
	    <owner>
	        <full-name>James A Banks</full-name>
	        <name>
	            <family-name>Banks</family-name>
	            <given-name>James</given-name>
	            <additional-names>A</additional-names>
	            <honorific-prefixes>Mr.</honorific-prefixes>
	        </name>
	        <bday>1974-09-08</bday>
                <gender>MALE</gender>
                <nationality code="US"/>
	        <email>user@example.net</email>
	        <tel type="pref">(704) 451 3434</tel>
	        <tel type="voice"></tel>
                <residential-address>
                     <street-address>1 A Street</street-address>
                     <region>My State</region>
                     <postal-code>90210</postal-code>
                     <country-name code="US"/>
                </residential-address>
	    </owner>

	    <billing-address>
	        <street-address>1 A Street</street-address>
	        <region>My State</region>
	        <postal-code>3456</postal-code>
	        <country-name code="US"/>
	    </billing-address>

            <property-relationships>
                <property-relationship identifier="1" ref="http://company.leapcities.com/api/v1/property-relationship/1"  unacked-since="2011-03-17T16:34:29.000+1100"/>
            </property-relationships>

	    <additional-fields>
	        <field key="shoe-size" label="Shoe Size">Nine</field>
	        <field key="career-name"label="Career Name">pleb</field>
	    </additional-fields>

            <communities>
                <community>original</community>
            </communities>

	</account>
<accounts>
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.