Desktop API
An API to interact between the Reapit AgencyCloud CRM and a AppMarket Web Application
Last updated
An API to interact between the Reapit AgencyCloud CRM and a AppMarket Web Application
Last updated
During the Beta period certain elements of AgencyCloud may not function end-to-end with a web application. For example, pictures or documents added to Agency Cloud via the desktop will not be available via the platform.
Applications that are built on our Foundations Platform are able to communicate with Reapit's AgencyCloud CRM system. Using a well-defined API, you are able to trigger a wide variety of actions in our award-winning desktop application to augment your own applications and build a rich integration between systems.
Note - apps cannot rely on cookies/local storage being available between separate instances of AgencyCloud. Therefore any data which will need to be shared between separate sessions will need to be handled outside of these methods.
When you are testing your app inside of AgencyCloud Developer Edition then there is a button top left of the app window which will allow launching of the Chromium Developer Tools in a separate window.
Clicking this button will launch a separate window which hosts the developer tools:
When a AppMarket application is launched and hosted within AgencyCloud, that application can interact with AgencyCloud by using our custom URI scheme. When a user triggers a link with an agencycloud: prefix, AgencyCloud will interpret that action and perform the corresponding action.
Links are structured in a REST style to provide a well-defined and descriptive mechanism for interacting with the screens and functionality that AgencyCloud offers. The primary and secondary screens that exist in the AgencyCloud user interface broadly map to the REST notion of resources and sub-resources. Some actions also accept parameters which can be applied to the URI in the usual manner. Full documentation of the available interactions is listed below, grouped by primary screen.
Opens the property edit screen for the property with specified id
Performs a property to applicant match for the applicant with specified id
Opens the journal screen for the specified property
Opens the offers screen for the specified property
Opens advanced search screen in property mode and runs a search with provided parameters. At least one parameter is required.
Parameter
Type
Description
Required
name
string
A full or partial name fragment to search for
No
address
string
An address fragment to search for (eg. a postcode)
No
communication
string
An email address or phone number to search for
No
mode
string
The marketing mode of the properties to search for:
s or sales
l or lettings
Yes
appId
string
The GUID of the app to return the code of the selected property to (if not present then search will not return to an app)
No
appParam
string
The key to use in the query string when returning the property primary key to an app (required if appId is set)
No
Opens the applicant edit screen for the applicant with specified id
Performs a applicant to applicant match for the applicant with specified id
Opens the journal screen for the specified applicant
Opens advanced search screen in applicant mode and runs a search with provided parameters. At least one parameter is required.
Parameter
Type
Description
Required
name
string
A full or partial name fragment to search for
No
address
string
An address fragment to search for (eg. a postcode)
No
communication
string
An email address or phone number to search for
No
mode
string
The marketing mode of the properties to search for:
s or sales
l or lettings
Yes
appId
string
The GUID of the app to return the code of the selected property to (if not present then search will not return to an app)
No
appParam
string
The key to use in the query string when returning the property primary key to an app (required if appId is set)
No
Opens the diary screen to provide a calendar view of appointments for the given date range. The dates don’t need to be set, but if you set one, you need to set both. If you don’t set a date range then the current default dates for the negotiator will be used.
Note: the dates must be in the format yyyy-MM-dd to be parsed correctly.
Parameter
Type
Description
Required
dateFrom
date
Only display appointments scheduled after and including this date (i.e. inclusive)
No
dateTo
date
Only display appointments scheduled before this date (i.e. exclusive)
No
Opens advanced search screen in contact mode and runs a search with provided parameters. At least one parameter is required.
Parameter
Type
Description
Required
name
string
A full or partial name fragment to search for
No
address
string
An address fragment to search for (eg. a postcode)
No
communication
string
An email address or phone number to search for
No
appId
string
The GUID of the app to return the code of the selected contact to (if not present then search will not return to an app)
No
appParam
string
The key to use in the query string when returning the contact primary key to an app (required if appId is set)
No
Opens the contact edit screen for the contact with specified id
Opens the journal screen for the specified contact
Opens the specific works order screen
Opens the works order search screen and prepopulate any search criteria as specified. As with other search urls it should also support the appId and appParam which will allow the selected item in the search to be sent back to an app.
From version 12.122.0 there will also be a resource called process which will have two sub processes:
webpage
This will allow you to launch a webpage in the local default browser. An example would be:
This will launch the https://www.reapit.com site in the default browser. Note: the url parameter must start with http for this to work.
This will allow you to launch the users default e-mail client and send to an address. An example would be:
This will create a new e-mail in the users default mail client. It will do this by taking the value of the address parameter, prefixing it with mailto: and then starting a process with that argument.
Not only can Applications built on the Foundations Platform trigger events in the AgencyCloud CRM system, but installed apps can also be associated with common actions in AgencyCloud to replace the default behaviour.
The most common way that this will manifest itself is by replacing a screen in AgencyCloud with an application. For example if you want to use an App to manage all of your AML and ID checking then you can associate the app with this action in AgencyCloud and every time you click to launch the ID check screen, the associated App will be presented instead.
All apps should be able to be launched from the Installed Apps screen and be ran standalone without the need to be linked to an action. They will just be hosted in the AppMarket and launched in AgencyCloud – for example the Geo Diary application.
To be able to associate an application with an action in AgencyCloud the application will need to be given a desktop type. This will be required so that AgencyCloud can be confident of the way the application will behave and that the application is agreeing to accept certain parameters when launched. These parameters will be available inside the window.__REAPIT_MARKETPLACE_GLOBALS__ javascript object which is used to identify that a page is in Desktop mode.
For example – an AML or ID checking app will need to be able to accept a parameter in the dictionary with a key of cntCode which tells the application which contact to show the ID checks for.
There are currently seven supported application desktop types which are based on the most commonly customised parts of AgencyCloud. This list will be extended as we learn what apps developers are building;
Property
Applicant
ID Check
Property Marketing Information
Vendor Marketing Report
Property Detail Generation (print wizard)
Applicant Export
From version 12.118.0 the following will also be available:
Landlord
Contact
Company
Tenancy
Offer
Sales Progression
Chain Management
From version 12.130.1 the following will also be available:
Outbound - Email
Outbound - Landline
Outbound - Mobile
From version 12.142.0 the following will also be available:
Match Output
From version 12.152.3 the following will also be available:
Diary
From version 12.153+ the following will also be available:
Pre Tenancy Checks
Works Order
From version 12.156+ the following with also be available:
Referrals
From version 12.160+ the following with also be available:
Renewal Negotiation Checks
From version 12.161+ the following with also be available:
Property Images
From version 12.163+ the following with also be available:
Property Licensing
The type of Property will be given to an application that can be launched for a specific property from AgencyCloud. The globals dictionary will contain the below key when launched by AgencyCloud for a specific property:
Parameter
Type
Description
Required
prpCode
string
The primary key of the property to load the application for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the desktop type route).
Yes
When an app with a type of Property is installed then an Apps menu will appear on the Property screen. Clicking on an app will launch it with the property code.
The type of Applicant will be given to an application that can be launched for a specific applicant from AgencyCloud. The globals dictionary will contain the below key when launched by AgencyCloud for a specific property:
Parameter
Type
Description
Required
appCode
string
The primary key of the applicant to load the application for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the desktop type route).
Yes
When an app with a type of Applicant is installed then an Apps menu will appear on the Applicant screen. Clicking on an app will launch it with the applicant code.
The type of ID Check will be given to an application that can be used to replace the ID Check screen in AgencyCloud. The globals dictionary will contain the below key when launched by AgencyCloud for a specific contact:
Parameter
Type
Description
Required
cntCode
string
The primary key of the contact to load the ID checks for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the desktop type route).
Yes
This desktop type will take affect in AgencyCloud when the following button is clicked (this will be seen on various screens, for example contact and applicant).
The type of Property Marketing Information can be given to an application that can replace the standard property marketing screen in AgencyCloud. This is the most commonly customised screen in AgencyCloud as it allows clients the opportunity to store bespoke information for their business. The globals dictionary will contain the below key when launched by AgencyCloud for a specific property:
Parameter
Type
Description
Required
prpCode
string
The primary key of the property to load the marketing information app for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the app association route).
Yes
An application of this type can be launched from the Marketing button on the property screen in AgencyCloud:
The type of Vendor Marketing Report can be given to an application that can produce a customised Vendor Marketing Report. This is also one of the most commonly customised areas of AgencyCloud as different agents have different requirements for how their vendor marketing reports should look. The globals dictionary will contain the below key when launched by AgencyCloud for a specific property:
Parameter
Type
Description
Required
prpCode
string
The primary key of the property to generate the report for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the app association route).
Yes
An application of this type can be launched from the Applicant Interest and Reports screen in AgencyCloud (launched from the Property Journal window):
The type of Property Detail Generation can be given to an application that can replace the standard details template generation and brochure ordering process. This application could allow selection of a template as defined in the application – selection of pictures to include, what paper size to print the brochures on etc. The globals dictionary will contain the below key when launched by AgencyCloud for a specific property:
Parameter
Type
Description
Required
prpCode
string
The primary key of the property to load generate the brochures for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the app association route).
Yes
An application of this type can be launched from the Property Details screen in AgencyCloud:
The category of Applicant Export would enable an application to be used to export the details of an applicant to a separate system. The globals dictionary will contain the below key when launched by AgencyCloud for a specific property:
Parameter
Type
Description
Required
appCode
string
The primary key of the applicant to export (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the app association route).
Yes
An application of this type would be triggered in two ways from AgencyCloud:
Upon first save of the applicant
As an option when clicking Print on the applicant screen:
The type of Landlord will be given to an application that can be launched for a specific landlord from AgencyCloud. The globals dictionary will contain the below key when launched by AgencyCloud for a specific landlord:
Parameter
Type
Description
Required
lldCode
string
The primary key of the landlord to load the application for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the desktop type route).
Yes
When an app with a type of Landlord is installed then an Apps menu will appear on the Landlord screen. Clicking on an app will launch it with the landlord code.
The type of Contact will be given to an application that can be launched for a specific contact from AgencyCloud. The globals dictionary will contain the below key when launched by AgencyCloud for a specific contact:
Parameter
Type
Description
Required
cntCode
string
The primary key of the contact to load the application for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the desktop type route).
Yes
When an app with a type of Contact is installed then an Apps menu will appear on the Contact screen. Clicking on an app will launch it with the contact code.
The type of Company will be given to an application that can be launched for a specific company from AgencyCloud. The globals dictionary will contain the below key when launched by AgencyCloud for a specific company:
Parameter
Type
Description
Required
cmpCode
string
The primary key of the company to load the application for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the desktop type route).
Yes
When an app with a type of Company is installed then an Apps menu will appear on the Company screen. Clicking on an app will launch it with the company code.
The type of Tenancy will be given to an application that can be launched for a specific tenancy from AgencyCloud. The globals dictionary will contain the below key when launched by AgencyCloud for a specific tenancy:
Parameter
Type
Description
Required
tenCode
string
The primary key of the tenancy to load the application for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the desktop type route).
Yes
When an app with a type of Tenancy is installed then an Apps menu will appear on the Tenancy screen. Clicking on an app will launch it with the tenancy code.
The type of Offer will be given to an application that can be launched for a specific offer from AgencyCloud. The globals dictionary will contain the below key when launched by AgencyCloud for a specific offer:
Parameter
Type
Description
Required
offerCode
string
The primary key of the offer to load the application for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the desktop type route).
Yes
When an app with a type of Offer is installed then an Apps menu will appear on the Offer screen. Clicking on an app will launch it with the code of the selected offer.
The type of Sales Progression will be given to an application that can be launched in place of the standard Sales Progression screen in AgencyCloud. The globals dictionary will contain the below key when launched by AgencyCloud for a specific property:
Parameter
Type
Description
Required
prpCode
string
The primary key of the property to load the sales progression information app for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the app association route).
Yes
An application of this type can be launched from the Sales Progression button on the offers screen in AgencyCloud:
The type of Chain Management will be given to an application that can be launched in place of the standard Chain screen in AgencyCloud. The globals dictionary will contain the below key when launched by AgencyCloud for a specific property:
Parameter
Type
Description
Required
prpCode
string
The primary key of the property to load the chain management information app for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the app association route).
Yes
An application of this type can be launched from the Chain button on the offers screen in AgencyCloud:
The category of Match Output would enable an application to be used to export the details of a match either from an applicant to a property or a property to an applicant. The globals dictionary will contain the below key when launched by AgencyCloud for a specific match:
Match type (PrpToappMatch/AppToPrpMatch)
Property to applicant or applicant to property
Property ID(s)
Single/Array of property IDs
Applicant ID(s)
Single/Array of applicant IDs
Negotiator ID - User (NegCode)
Neg ID of the logged in Negotiator
An app with the integration type 'Match Output' will be visible by selecting 'Print' after running a match:
The desktop type of Diary can be given to an application that can be launched on an existing appointment in AgencyCloud. The globals dictionary will contain the below key when launched by AgencyCloud for a specific appointment:
{diaryCode: 'OXF2202628'}
Parameter
Type
Description
Required
diaryCode
string
The primary key of the appointment (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the app association route).
Yes
The type of Pre Tenancy Checks will be given to an application that replaces the Pre Tenancy screen from AgencyCloud. The globals dictionary will contain the below key when launched by AgencyCloud for a specific tenancy:
Parameter
Type
Description
Required
tenCode
string
The primary key of the tenancy to load the application for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the desktop type route).
Yes
When an app with a type of Pre Tenancy Check is installed, it will be launched when accessing the Pre Tenancy screen (if multiple apps with the same integration type are installed, an option to select will be presented). Clicking on an app will launch it with the tenancy code.
The desktop type of Works Order can be given to an application that can be launched from a Works Orders screen in AgencyCloud. When an application has this desktop type, it will replace the native behaviour and will launch when selecting ‘Create’. The globals dictionary will contain the below key when launched by AgencyCloud:
Parameter
Type
Description
Required
prpCode
string
The primary key of the property to load the Works Order information app for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the app association route).
Yes
You can also launch the app from an existing works order and the globals dictionary will contain the below key when launched by AgencyCloud:
Parameter
Type
Description
Required
woCode
string
The primary key of the works order to load the Works Order information app for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the app association route).
Yes
The desktop type of Referral can be given to an application that can be launched after a user creates a referral in AgencyCloud. The globals dictionary will contain the below key when launched by AgencyCloud for a referral:
{refCode: 'MKT220075'}
Parameter
Type
Description
Required
refCode
string
The primary key of the referral to load the referral information within the app (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the app association route).
Yes
Referrals/Leads are part of the AgencyCloud configuration and will need to be setup before you can launch your app from the panel (this cannot be setup via Platform).
Configuration can only be accessed by an Admin with the correct permissions or by the agent making a request to our service desk.
The agent should first install your app from the AppMarket and after installation, restart AgencyCloud
Open the ‘Setup Referrals/Leads’ section under configuration:
Either click 'Add' or edit an existing referral and enter the required information and select ‘Marketplace App’, the menu should open to display any apps that have been installed with the desktop type of ‘Referral’:
Once the setup is saved, the new referral option should appear on the chosen screen. For example, on the Applicant screen 'Referral Example':
When a user clicks on the referral, it will prompt them to ‘Create New Referral’:
Once created, the app setup for that referral will automatically launch.
If a user closes the app or wishes to make amendments/relaunch the app, they can simply right click on the referral and select ‘Launch App…’:
The desktop type of Renewal Negotiation Check can be given to an application that will replace the checks section on a Renewal Negotiation screen in AgencyCloud. The global dictionary will contain the below key when launched by AgencyCloud for a renewal:
Parameter
Type
Description
Required
renewalCode
string
The primary key of the renewal to load the application for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the desktop type route).
Yes
When an app with a type of Renewal Negotiation Check is installed, it will replace the 'checks' on the Renewal Negotiation screen (when heavy weight renewals are enabled). If multiple apps with the same integration type are installed, an option to select will be presented). Clicking on an app will launch it with the renewal code.
The desktop type of Property Image can be given to an application that can be launched from the 'Apps' menu on the property images screen. The globals dictionary will contain the below key when launched by AgencyCloud:
The below key when launched by AgencyCloud:
Parameter
Type
Description
Required
prpCode
string
The primary key of the property to load the property images app (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the app association route).
Yes
The desktop type of Property Licensing can be given to an application that replaces the 'Licensing' button on the property attributes screen. When an application has this desktop type, it will replace the native behaviour and will launch when selecting ‘Licensing’. The globals dictionary will contain the below key when launched by AgencyCloud:
Parameter
Type
Description
Required
prpCode
string
The primary key of the property to load the property licensing app for (note that this won’t be present when the app loads from the AppMarket, but the app needs to be able to accept this parameter when it is launched via the app association route).
Yes
