| Next Generation Building Services

Back To Home

Leap Plaza

Resources

Requests Web Services API

Skip to end of metadata
Go to start of metadata
Contents

API Context

Support Requests are raised by customers using the Community Portal. Using this API, an external system can find and update a Support Request's details and status.

The Requests Web Services API enables external systems to -

  • View full details for a support request by LEAP identifier or external identifier
  • Update the external identifier for a support request.
  • Acknowledge changes to a support request.
  • Find all support requests (optionally restricted to a date range)
  • Find all support requests classified by topic (optionally restricted to a date range)
  • Find all support requests classified by topic in a nominated state (optionally restricted to a date range)
  • Post a status change
  • Post a comment to a request.

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

Concepts

Raising a support request

A support request can be raised directly by a customer, or by an agent on behalf of a specific customer. A support request is also generated when a customer submits the self-registration form.

The following information is requested when a new support request is raised:

  • Issue Type - the related area the issue relates to, for example 'air conditioning'.
  • Related Property - indicates whether the issue directly affects a property the customer is associated with.
  • Related Product Offer - indicates whether the issue is covered by a product offer that the customer has subscribed to at some time. The product offer must be configured to allow support request relationships.
  • Summary - a brief summary of the problem; this serves as the 'support request name'.
  • Description - a detailed description of the problem.
  • Email Address - the address updates will be sent to as the support request progresses.

Support Request states

A support request can have the following states:

  • New - support request has been received and is awaiting action
  • In Progress - support request has been assigned to an agent and is being actioned
  • Problem - the agent has encountered a problem with resolving the support request
  • Successful - support request has been successfully completed
  • Cancelled - the support request could not be successfully completed and as such was cancelled

When a new request is raised by a customer, it appears in the Operator Portal > Requests zone with a status of 'New'. When a new request is assigned to an agent, the request status changes from New to In Progress.

NB. One a request has transitioned to successful or cancelled it cannot be changed back to another state.

An external system with External Access to Support Requests can update the status of a support request.
An agent with Requests Zone - Basic can update the status of a support request.

The tracking section for the support request maintains a history of state changes.

For each state change, an email notification is sent to the customer's nominated email address.

Request History

On the Customer Portal > Requests zone, the Request History section maintains a history of state changes for the support request.

  • When a support request changes state, the state is added to the history.
  • When a comment is added to a support request, the comment is added to the history.

The following information is displayed in the request history:

  • Agent/customer who added the comment; agent who changed the state
  • Relative timestamp the request was updated
  • The status of the support request.

Types

State - one of NEW, IN_PROGRESS, SUCCESSFUL, PROBLEM, CANCELLED. CANCELLED and SUCCESSFUL are terminal states.
Update Type - one of COMMENT_ADDED, STATE_CHANGED, ASSIGNED

BASE URL

Using the leapcities.com SSL certificate

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

Using your own SSL certificate

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

API

View full details for a support request by LEAP identifier or external identifier

This method allows an external system to retrieve the details of a request by its LEAP identifier or external identifier

URL:
requests/identifier
requests/extid/external-identifier

Where identifier or external-identifier are the values for the required support request.

Method: GET
Error Codes:

  • 404 The supplied support request identifier / external identifier does not exist

Example Response:

<support-request xmlns="http://schema.majitek.com/leap-ws-v1.0" identifier="10000001" ref="http://company.leapcities.com/api/v1/requests/10000001"
        extid="MAX-1234" unacked-since="2011-02-08T22:07:43.000+0000">
    <state>IN_PROGRESS</state>
    <topic identifier="Parking" extid="1/>
    <sub-topic identifier="Stolen Spot" extid="2/>
    <summary>My parking spot has been taken.</summary>
    <description>When I drove to work this morning I found that my designated parking spot had been taken by a maintenance van.
This is a real nuisance as there were no other parking spots available at the time.Could you please resolve as soon as possible!</description>
    <creation-time>2011-02-08T22:06:43.000+0000</creation-time>
    <last-update-time>2011-02-08T22:07:43.000+0000</last-update-time>
    <creator>Joseph Banks</creator>
    <assignee>Jenny Bujold</assignee>
    <community>original</community>
    <email>some_special_email@example.net</email>
    <account identifier="01234574" ref="http://company.leapcities.com/api/v1/customers/01234574"/>
    <updates>
        <update unacked-since="2011-02-08T22:07:43.000+0000">
            <type>COMMENT_ADDED</type>
            <update-time>2011-02-08T22:07:43.000+0000</update-time>
            <updater>Orville Wright</updater>
            <comment>I've called the maintenance driver and am waiting to hear back. I'll keep you informed.</comment>
        </update>
        <update>
            <type>STATE_CHANGED</type>
            <state>IN_PROGRESS</state>
            <update-time>2011-02-08T22:07:43.000+0000</update-time>
            <updater>Orville Wright</updater>
            <comment></comment>
        </update>
    </updates>
</support-request>

Update the external identifier for a support request

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

URL:
requests/identifier/extid

Where identifier is the identifier for the required support request.

Method: POST

POST Parameters:

  • extid - The new external identifier to apply to the support request

Error Codes:

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

Example

Request:

POST:

extid=MAX-56789

Response:

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

Acknowledge changes to a support request

Allows an external system to acknowledge that it has dealt with the fact that there has been an update to the support request/s. The acknowledgement can acknowledge the entire support request change or it can optionally acknowledge the support request and not acknowledge the updates on the support request. The acknowledgeUpdates flag signifies whether or not to acknowledge updates. If no flag is passed true is assumed.

Performing this POST will clear the unacked-since flag on the support request/s and all its updates. It does not affect the unacked-since flag on any entity references. (eg a property reference)

URL:
requests/acked - Identifies that acknowlegements will use the internal reference for the support request
requests/external/acked - Identifies that acknowlegements will use the external reference for the support request

Method: POST

Parameters:

  • none

Method: POST
Response Codes:

Example Request:

<acknowledgements acknowlegdeUpdates="true">
 <acknowledgement>10000001</acknowledgement>
 <acknowledgement>10000002</acknowledgement>
</acknowledgements>

Error Codes:

  • 404 One of the supplied support request identifier / external identifier does not exist.

Find all support requests

This method allows the retrieval of the details of all support requests. The update history is not included when retrieving via this URL.

URL:
requests/

GET Parameters:

  • last-update-from - restricts results to those requests updated after this time.
  • last-update-to - restricts results to those requests updated before this time.
  • acked - restricts results to only requests 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 by any of these parameters.

Method: GET
Example Parameters:

  • last-update-from=2010-04-06T12:43:17.123Z
  • last-update-to=2011-12-03T11:11:12.987Z
  • acked=true

Error Codes:

  • 400 Invalid date(s) supplied

Example Response:

<support-requests xmlns="http://schema.majitek.com/leap-ws-v1.0">
    <support-request xmlns="http://schema.majitek.com/leap-ws-v1.0" identifier="10000001" ref="http://company.leapcities.com/api/v1/requests/10000001"
            extid="MAX-1234" unacked-since="2011-02-08T22:07:43.000+0000">
        <state>IN_PROGRESS</state>
        <topic identifier="Parking"/>
        <summary>My parking spot has been taken.</summary>
        <description>When I drove to work this morning I found that my designated parking spot had been taken by a maintenance van.
This is a real nuisance as there were no other parking spots available at the time. Could you please resolve as soon as possible!</description>
        <creation-time>2011-02-08T22:06:43.000+0000</creation-time>
        <last-update-time>2011-02-08T22:07:43.000+0000</last-update-time>
        <creator>Joseph Banks</creator>
        <assignee>Jenny Bujold</assignee>
        <community>original</community>
        <email>some_special_email@example.net</email>
        <account identifier="01234574" ref="http://company.leapcities.com/api/v1/customers/01234574"/>
    </support-request>
    ...
</support-requests>

Find all support requests classified by topic

This method allows an external system to retrieve the details of a request by specifying the Topic identifier.

URL:
requests/by-topic/topic-identifier

Where topic-identifier is the identifier for the required topic.

GET Parameters:

  • last-update-from - restricts results to those with last updated greater than or equal to this value.
  • last-update-to - restricts results to those with last updated less than this value.
  • acked - restricts results to only ones 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 by any of these parameters.

Method: GET
Example Parameters:

  • last-update-from=2010-04-06T12:43:17.123Z
  • last-update-to=2011-12-03T11:11:12.987Z
  • acked=true

Error Codes:

  • 404 The supplied support request topic doesn't exist
  • 400 Invalid date(s) supplied

Example Response:

<support-requests xmlns="http://schema.majitek.com/leap-ws-v1.0">
	<support-request xmlns="http://schema.majitek.com/leap-ws-v1.0"
	  identifier="0000001"
	  ref="http://company.leapcities.com/api/v1/requests/0000001"
          extid="EXT-1234">
	    <state>IN_PROGRESS</state>
	    <topic identifier="Parking"/>
	    <property identifier="PP-01"
               ref="http://company.leapcities.com/api/v1/properties/PP-01" external-reference="PROP-1234"/>
            <purchased-product-offer identifier="POF-12345"/>
            <purchased-product-offer-name>Car Park</purchased-product-offer-name>
	    <summary>My parking spot has been taken.</summary>
            <description>When I drove to work this morning I found that my designated parking spot had been taken by a maintenance van.
This is a real nuisance as there were no other parking spots available at the time.Could you please resolve as soon as possible!</description>
	    <creation-time>2010-08-10T15:30:10.000+1000</creation-time>
	    <last-update-time>2010-08-10T15:30:10.000+1000</last-update-time>
	    <creator>Joseph Banks</creator>
	    <assignee>Jenny Bujold</assignee>
            <community>original</community>
	    <email>joe@example.com</email>
            <account identifier="01234574" ref="http://company.leapcities.com/api/v1/customers/01234574"/>
	</support-request>
    ...
</support-requests>

Find all support requests classified by topic in a nominated state

This method allows an external system to retrieve the details of requests by specifying the Topic identifier and State of the requests.

URL:
/requests/by-topic/topic_identifier/in-state/state

Where topic-identifier is the identifier for the required topic and state is the required state.

topic-identifier

GET Parameters:

  • last-update-from - restricts results to those with last updated greater than or equal to this value.
  • last-update-to - restricts results to those with last updated less than this value.
  • acked - restricts results to only ones 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 by any of these parameters.

Method: GET
Example Parameters:

  • last-update-from=2010-04-06T12:43:17.123Z
  • last-update-to=2011-12-03T11:11:12.987Z
  • acked=true

Error Codes:

  • 400 An invalid state was supplied
  • 400 Invalid date(s) supplied
  • 404 The supplied topic does not exist

Example Response:

<support-requests xmlns="http://schema.majitek.com/leap-ws-v1.0">
	<support-request xmlns="http://schema.majitek.com/leap-ws-v1.0"
	  identifier="in-progress-alarm"
	  ref="http://company.leapcities.com/api/v1/requests/in-progress-alarm"
          extid="MY_SPECIAL_REFERENCE">
	    <state>IN_PROGRESS</state>
	    <topic identifier="Alarm"/>
	    <property identifier="PP-01"
               ref="http://company.leapcities.com/api/v1/properties/PP-01" external-reference="PROP-1234"/>
	    <summary>My parking spot has been taken.</summary>
            <description>When I drove to work this morning I found that my designated parking spot had been taken by a maintenance van.
This is a real nuisance as there were no other parking spots available at the time.Could you please resolve as soon as possible!</description>
	    <creation-time>2010-08-10T15:30:10.000+1000</creation-time>
	    <last-update-time>2010-08-10T15:30:10.000+1000</last-update-time>
	    <creator>Joseph Banks</creator>
	    <assignee>Jenny Bujold</assignee>
            <community>original</community>
	    <email>joe@example.com</email>
            <account identifier="01234574" ref="http://company.leapcities.com/api/v1/customers/01234574"/>
	</support-request>
    ...
</support-requests>

Post a status change

This method allows the status of a request to be updated

URL:
/requests/identifier/updates
/requests/extid/external-identifier/updates

Where identifier or external-identifier are the values for the required support request.

POST Parameters:

  • none

Method: POST
Response Codes:

  • 409 Could not update the support request due to an invalid state
  • 400 Invalid state

Example Request:

<support-request-update>
 <state>IN_PROGRESS</state>
 <comment>optional comment</comment>
</support-request-update>

Post a comment to a request

This method allows a customer visible comment to be added to a support request.

URL:
/requests/identifier/updates
/requests/extid/external-identifier/updates

Where identifier or external-identifier are the values for the required support request.

Method: POST
Response Codes:

Example Request:

<support-request-update>
 <comment>adding a comment without state change</comment>
</support-request-update>
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.