# Home

Welcome to Reapit Foundations Documentation

The documentation is split between the[ API](/api) and our [Open Source Packages](/app-development).

API usage documentation is again split between the [Foundations REST API](https://marketplace.reapit.cloud/developer/api-docs)[ ](/api/api-documentation)for querying the Reapit data platform, the[ Desktop API](/api/desktop-api) which is relevant to interactions between web-apps and [Reapit Agency Cloud](https://www.reapit.com/agency-cloud/), the [Reapit Connect OAuth](/api/reapit-connect) single sign on service, and finally, the [NPM packages](https://www.npmjs.com/org/reapit) we support for [web development.](/app-development/web)

In the Open Source docs you will find information, largely about the [Foundations Repo on Github](https://github.com/reapit/foundations). This is the home for all the source code for our web apps, tooling and published packages. 


# APIs

A complete guide to working with Reapit Foundations Web and Server-Side APIs


# MCP (Alpha)

A guide for interacting with our Platform MCP

> Parameters, tools, resources, prompts and responses are likely to change in the future

The Foundations MCP server exposes the Reapit Foundations platform as a set of [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) tools that an AI model or agent can call directly. Instead of integrating against the Foundations REST API endpoint by endpoint, you connect a single MCP client to the server and the model is given a ready-made toolset for searching and managing appointments, properties, contacts, applicants, offers, and more.

This guide covers how a third party connects to the server, authenticates, and what tools are available.

{% hint style="warning" %}
To register for early access, please complete this [form](https://share-eu1.hsforms.com/1N_JYy9RLS9qI0X1oqTRi6w2eoxls?utm_campaign=323420401-FY26%20l%20Q3%20Q4%20Tapi%20sunset\&utm_source=hs_email\&utm_medium=email&_hsenc=p2ANqtz--UZQS-606QhCTChwNmTKbIziCqw5h3KxqUdYy_ansSt-xJNapbQ9xyEVMXbumRv_H7Wkvw)
{% endhint %}

### Endpoint

The server uses **Streamable HTTP**. There is a single endpoint:

```
https://foundations-mcp.iaas.reapit.cloud/mcp
```

All MCP traffic (initialization, tool listing, and tool calls) flows through this URL.

### Authentication

Every request must carry a valid Reapit JWT and identify the tenant it is acting for.

| Requirement             | Detail                                                                                                                                                                                                                                   |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization`header   | `Bearer <jwt>` — a valid Reapit access token issued by Reapit Connect.                                                                                                                                                                   |
| Required scope          | The token's `scope` must include **`agencyCloud/mcp.access`**. A token without this scope is rejected.                                                                                                                                   |
| `reapit-customer`header | The tenant (customer) ID the request acts for, e.g. `SBOX`. **Only required for machine-to-machine (client-credentials) clients.** For user-context tokens the customer code is read from the token itself, so the header is not needed. |

Tokens are issued and verified by Reapit Connect. For how to register a client and obtain an access token, see the [Reapit Connect Documentation](/api/reapit-connect).

> **The `agencyCloud/mcp.access` scope is required to access the MCP server.** A token without this scope is rejected with a `403`.

### Connecting with the MCP Inspector

MCP can be awkward to reason about in the abstract, so the quickest way to see the server working is the official [MCP Inspector](https://github.com/modelcontextprotocol/inspector). It's a local UI that lets you connect to an MCP server, browse its tools, and call them by hand.

Run it with:

```bash
npx @modelcontextprotocol/inspector
```

This opens the Inspector in your browser. Configure the connection as follows:

| Field          | Value                                           |
| -------------- | ----------------------------------------------- |
| Transport Type | **Streamable HTTP**                             |
| URL            | `https://foundations-mcp.iaas.reapit.cloud/mcp` |

Then add the required headers under the Inspector's authentication / custom headers section:

| Header            | Value                                                                                                                                  |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization`   | `Bearer <your-jwt>`                                                                                                                    |
| `reapit-customer` | `<your-tenant-id>` (e.g. `SBOX`) — *machine-to-machine clients only*                                                                   |
| `x-timezone`      | `Europe/London` (default UTC). This header is used to convert date times to the provided timezone in the formatted text stream output. |

Click **Connect**. Once connected, open the **Tools** tab and select **List Tools** to see everything the server exposes. You can select any tool, fill in its parameters, and run it to see the live response — a fast way to validate your credentials and explore the data before wiring the server into an agent.

### Server configuration

If you connect from your own MCP client rather than the Inspector, the equivalent configuration is:

```json
{
  "mcpServers": {
    "foundations": {
      "type": "streamable-http",
      "url": "https://foundations-mcp.iaas.reapit.cloud/mcp",
      "headers": {
        "Authorization": "Bearer <your-jwt>",
        "reapit-customer": "<your-tenant-id>"
      }
    }
  }
}
```

The exact shape of the configuration block varies by client, but the things it always needs are the Streamable HTTP transport, the `/mcp` URL, and the `Authorization` header. Add the `reapit-customer` header only if you authenticate as a machine-to-machine (client-credentials) client; user-context tokens carry the customer code themselves.

### Available tools

When you list tools, the server registers the following domains. Each tool name is prefixed with its domain.

#### Appointments

The richest domain — search, retrieve, create, and update appointments, plus open-house attendee management.

`appointments_search`, `appointments_get_by_id`, `appointments_create`, `appointments_update`, `appointments_get_types`, `appointments_get_followup_responses`, `appointments_list_open_house_attendees`, `appointments_create_open_house_attendee`, `appointments_update_open_house_attendee`, `appointments_delete_open_house_attendee`

#### Properties

Search and retrieve properties, get driving directions between locations, and manage appraisals and key movements.

`properties_search`, `properties_get_by_id`, `get_directions`, `properties_appraisals_list`, `properties_appraisals_get`, `properties_appraisals_create`, `properties_appraisals_update`, `properties_key_movements_list`, `properties_key_movements_create`, `properties_key_movements_check_in`

#### Configuration

Reference lookups used to interpret and populate other records.

`get_departments`, `get_property_attribute_options`, `appointments_get_types`, `appointments_get_followup_responses`, `companies_get_types`

#### Contacts

`contacts_search`, `contacts_get_by_id`, `contacts_create`, `contacts_update`

#### Applicants

`applicants_search`, `applicants_create`, `applicants_update`

#### Companies

`companies_search`

#### Offices

`offices_search`, `offices_get_by_id`

#### Negotiators

`negotiators_search`, `negotiators_get_by_id`

#### Areas

`areas_search`

#### Offers

`offers_search`

#### Landlords

`landlords_search`, `landlords_get_by_id`

#### Vendors

`vendors_search`, `vendors_get_by_id`

#### Tenancies

`tenancies_search`, `tenancies_get_by_id`

> The registered toolset may grow over time. Always use **List Tools** to get the authoritative, current set for your tenant.

### Embedded resources

Several Foundations records can be returned with related entities "embedded" — for example, an appointment returned alongside its negotiators, office, and property, rather than just their IDs.

**For now, the server applies these embeds automatically** on your behalf, so related data comes back already attached without you having to request it. This behaviour is convenient but **may change in the future**, so don't build logic that assumes a fixed, permanent set of embedded fields.

### Errors

Failures are returned as standard HTTP status codes:

| Status | Meaning                                                                                      |
| ------ | -------------------------------------------------------------------------------------------- |
| `400`  | Bad request — e.g. a client-credentials token without the required `reapit-customer` header. |
| `401`  | Unauthorized — missing, expired, or invalid token.                                           |
| `403`  | Forbidden — the token is valid but lacks the `agencyCloud/mcp.access` scope.                 |
| `502`  | Upstream verification failure (e.g. the identity provider could not be reached).             |

### Further reading

* [Model Context Protocol specification](https://modelcontextprotocol.io/)
* [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
* [Reapit Connect documentation](/api/reapit-connect)


# REST API

Complete technical guidance on how to work with the Foundations REST APIs

## Introduction

The Foundations API is organised around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has predictable resource-oriented URLs using standard HTTP response codes and verbs. All requests and responses, including errors, are [JSON-encoded](http://www.json.org/).

You can immediately start testing our APIs in [sandbox mode](/api/api-documentation#sandbox-mode) by using our [Interactive API Explorer](https://developers.reapit.cloud/swagger). Please see our [help page](https://marketplace.reapit.cloud/developer/help) for support and information on preview / upcoming changes.

| Service base location                                                                      | Description                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p><strong>Authentication service</strong></p><p><https://connect.reapit.cloud/></p>       | First, use our [authentication service](/api/api-documentation#authentication) to receive an access token. Include this in the header of any request you issue to our other platform services.  |
| <p><strong>All other platform services</strong></p><p><https://platform.reapit.cloud/></p> | Once authenticated, you can issue requests to our other platform services. For details on the endpoint we provide, see our [Interactive API Explorer](https://developers.reapit.cloud/swagger). |

The current version of our APIs is **2020-01-31** - please include it in your `api-version` request header. For more information, see our [versioning](/api/api-documentation#versioning) information

{% hint style="success" %}
**Our Platform is in** **beta** and we'll be continually building new features during this phase. Please see our [help section](https://foundations-documentation.reapit.cloud/help) to view our milestones or to submit a feature request or bug.
{% endhint %}

## Entity References and Data Uniqueness

Reapit entity references (`id` values) are designed to uniquely identify a record within a specific entity type and customer database. These identifiers should not be treated as globally unique across the Reapit platform.

When working with Reapit data, developers should be aware that:

* The same `id` value may exist in multiple customer databases.
* The same `id` value may exist for different entity types within the same customer database.
* An `id` value alone should not be used as a globally unique key when storing or aggregating data from multiple Reapit customers.

Reapit does not guarantee that identifier values are unique across all customer databases or across all entity types.

When storing or processing data from Reapit, developers should construct unique keys using:

* The customer or organisation identifier
* The entity type (e.g. Contact, Property, Tenancy, Applicant)
* The Reapit entity reference (`id`)

This approach ensures records remain uniquely identifiable when integrating with multiple Reapit customers or when working with data from different entity types.

## REST

### Request methods

Our APIs present a uniform interface for performing CRUD (create, retrieve, update, delete) operations. Each endpoint adheres to REST guidelines to map the correct verb to the operation being performed.

Our APIs support the following HTTP request methods:

| Method   | Action                                                                                   |
| -------- | ---------------------------------------------------------------------------------------- |
| `GET`    | Retrieve a resource or collection of resources                                           |
| `POST`   | Create a new resource                                                                    |
| `PATCH`  | Partially update an existing resource by only including the fields to replace in payload |
| `DELETE` | Soft delete an existing resource                                                         |

### Response codes

We use standardized HTTP status codes to indicate the outcome of a request. Below is a listing of the codes our APIs may return and their meaning.

* Codes in the `2xx` range indicate that the request was fulfilled successfully.&#x20;
* Codes in the `4xx` range indicate an error caused by the information provided.
* Codes in the `5xx` range indicate an error with our APIs which will be logged and investigated.

| Code                       | Description                                                                                                                                                                                              |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200 OK`                   | The request has been fulfilled.                                                                                                                                                                          |
| `201 Created`              | The request has been fulfilled and a new resource has been created.                                                                                                                                      |
| `204 No Content`           | The request has been fulfilled but there is no need to send any data back.                                                                                                                               |
| `400 Bad Request`          | The request was not understood by the server. This is generally due to bad request syntax.                                                                                                               |
| `401 Unauthorized`         | The provided authentication credentials are incorrect or not present. Generally, this is due to the lack of an "Authorization" header                                                                    |
| `403 Forbidden`            | The authentication credentials request do not provide sufficient scope to fulfill the request                                                                                                            |
| `404 Not Found`            | The requested resource was not found.                                                                                                                                                                    |
| `412 Precondition Failed`  | The was not fulfilled because preconditions provided by the client could not be met. Usually occurs [optimistic concurrency control ](/api/api-documentation#optimistic-concurrency)rejects the request. |
| `422 Unprocessable Entity` | A validation error has occurred. The error response body will provide additional information on the failure(s).                                                                                          |
| `429 Too Many Requests`    | The request was not accepted because the application has exceeded the rate limit.                                                                                                                        |
| `500 Internal Error`       | The request triggered an unexpected error which will be logged and investigated.                                                                                                                         |

### Errors

In addition to the relevant response code, unsuccessful requests will return a JSON encoded error response as outlined below:

| Attribute     | Description                                                                                                           |
| ------------- | --------------------------------------------------------------------------------------------------------------------- |
| `statusCode`  | The integer response code issued by this response                                                                     |
| `dateTime`    | UTC formatted timestamp of when error response was issued                                                             |
| `description` | Human readable message providing details about the error.                                                             |
| `errors`      | A collection of validation issues with the provided payload. Only populated for `422 Unprocessable Entity` responses. |

{% hint style="info" %}
**All responses** are issued with a unique request id, regardless of whether they were successful or not. You can find this in the `x-amzn-RequestId` response header. If you [report a bug](https://marketplace.reapit.cloud/developer/help) be sure to include this id to allow us to examine your problem in greater depth.
{% endhint %}

### Rate limits

We apply rate limits on the API calls an application can make within a given time period. If this limit is exceeded the app will be throttled and API requests will fail.

* 20 requests can be sent per second
* 5 maximum concurrent requests at any time per customer&#x20;
* 250,000 maximum requests per day&#x20;

If your application exceeds these limits, your app will be presented with `429 Too Many Requests` responses.

## Authentication

The Foundations platform uses [OpenID Connect](https://openid.net/connect/faq/) for authenticating requests. OpenID Connect is a protocol for authenticating users, built on top of the OAuth 2.0 specification.

### Registering your app

Submitting your application to our AppMarket is the first step for it to be able to interact with our clients data. After you have [successfully submitted your app](https://marketplace.reapit.cloud/developer/submit-app), you will be issued with a **client id** and **secret.** You can obtain these by clicking your app in the [My Apps](https://marketplace.reapit.cloud/developer/apps) area of our developer portal.

{% hint style="info" %}
**For more information** on how to get started and register your application with our AppMarket, please see our[ developer portal guide](/developer-portal).
{% endhint %}

### Customer installation

You can immediately access our [sandbox environment](https://foundations-documentation.reapit.cloud/api/api-documentation#sandbox-mode) but in order to be authorized to access a customers data, they must choose to install it.

Customer administrators are able to control your applications access to their companies data by opted to install it once it has been listed in our AppMarket. As part of this process, they will grant your application with any permissions (scopes) it requires to interact with Foundations API endpoints.

### OAuth 2.0 Grants

We support the use of two different OAuth 2.0 grants for applications built on our Platform:

| Grant                   | Description                                                                                                                                                                                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Authorization code flow | For use by client and server side applications that have a user in context. Allows the implementing application to be authenticated on the behalf of the user. **To use this grant, please see the documentation for our** [**Reapit Connect**](/api/reapit-connect#overview) **service.** |
| Client credentials flow | For use by server side machine to machine applications that do not have a user in context. Allows the implementing application to be authenticated on behalf of itself.                                                                                                                    |

### Client credentials flow

To obtain tokens for your application to interact with our protected endpoints, you must send a `POST` request to our token endpoint, as below:

`https://connect.reapit.cloud/token`

| Request payload | Description                                                                 |
| --------------- | --------------------------------------------------------------------------- |
| `client_id`     | The unique client id that was issued to your application after registration |
| `grant_type`    | Must be set to `client_credentials`                                         |

Content-Type must be set to `application/x-www-form-urlencoded` and the `Authorization` header should be set to `Basic <base64 secret>`where `<base64 secret>` is the **base64 representation of the client id and secret concatenated with a colon**. You can obtain **client id** and **secret** by clicking your app in the [My Apps](https://marketplace.reapit.cloud/developer/apps) area of our developer portal.

If your request is properly formed and valid, you'll receive a response similar to below.

```
HTTP/1.1 200 OK
Content-Type: application/json

{ 
 "access_token" : "eyJz9sdfsdfsdfsd", 
 "token_type" : "Bearer", 
 "expires_in" : 3600
}
```

| Response payload | Description                                               |
| ---------------- | --------------------------------------------------------- |
| `access_token`   | Token to grant access to protected Foundations endpoints  |
| `expires_in`     | The number of seconds that the access token is valid for  |
| `token_type`     | The type of tokens issued. Will always be set to `bearer` |

{% hint style="danger" %}
**Client credentials flow** must not be used for applications that are client side only. A server side component is required to be able to safely store credentials.
{% endhint %}

### Using access tokens

Access tokens (also known as bearer tokens) are designed to provide your application with access to protected resources. Once you have been issued an access token from our token endpoint, your application can access Foundations APIs by including it in a`Authorization` header, prefixed with `Bearer`

`Authorization: Bearer <your access token>`

Our servers will validate this token and fulfill the request, subject to your application application requesting the relevant endpoint scope during registration.

### Accessing customer data

Requests issued with access codes gained from the client credentials flow must also indicate which customers/agents data they wish to interact with.

You must additionally include a `reapit-customer` header in your request so that it can be fulfilled appropriately. The header should be set to the customers unique id which becomes available to view after a customer has chosen to install your application. You can find out the unique ids and names of the clients that have installed your application via the installations section on your app in the DeveloperPortal. Please [click here](https://foundations-documentation.reapit.cloud/faqs#installation) for more information on installation data.&#x20;

If a customer chooses to uninstall your application then your access to their data will be revoked.

Please note that the resource identifiers are only unique to a specific customer's database and *not* globally unique. To determine uniqueness, create a composite key using the customer id and resource id.

{% hint style="info" %}
We recommend using our webhooks system to be instantly notified when a Reapit customer installs your application. See our [webhooks documentation](/api/webhooks)  for more information.
{% endhint %}

## Sandbox mode

You can use the Foundations APIs in Sandbox mode which provides a set of demonstration data that can be interacted with without requiring a customer to install your application. Sandbox mode supports processing of all read and write requests so that you can build and test in confidence without impacting customer data.

To access the sandbox, you just need to be registered as a developer on our Portal.

* You can use **authorization code flow** by providing your developer portal credentials to our [Reapit Connect](/api/reapit-connect#overview) service
* You can use **client credentials flow** by providing `SBOX` as your `reapit-customer` request header

{% hint style="info" %}
**For a quick start experience**, our [interactive API explorer](https://developers.reapit.cloud/swagger) is connected to the sandbox automatically
{% endhint %}

## Issuing requests

### Timestamps

The Foundations platform exclusively works with UTC date times to allow us to present a uniform interface and ensure that behavior remains predictable, regardless of your application or user timezone.

Our APIs enforce that any date information that your application issues to us adheres to the [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. If you provide a time component, then it must be accompanied by a [time zone designator](https://en.wikipedia.org/wiki/ISO_8601#Time_zone_designators). If you provide a request body, query string or header that does not adhere to this standard, you will receive a validation error reporting the problem. Any date times issued from our endpoints will be returned to you in the same format.

Some of the fields we provide are date-only and have no time component. Date only fields will not accept a time component in a request and will not include a time component in their response. You can see which fields these are by examining the model documentation and example responses provided by our [Interactive API Explorer](https://developers.reapit.cloud/swagger).

```javascript
{
  "myDateAndTimeField": "2020-02-11T13:32:03.6759302Z",
  "myDateOnlyField": "2020-02-11"
}
```

### Retrieving data

Our APIs support retrieval of resources using the `GET` verb.  When a `GET` request has been successfully fulfilled, you will receive a `200 OK` response with results included as a JSON payload. To ensure that parameters that `GET` resources accept work as you expect, please ensure you URL encode the parameters you provide.

When working with boolean query string parameters, if they are not provided then no filter is applied to the dataset returned. This can be confusing for some developers who assume that not passing these parameters is like passing them as false (typically the default value for a boolean property). If they are not passed at all, our APIs ignore them completely and so no filtering is applied to the respective field(s).

For practical and performance reasons, our top level APIs enforce paging and require a standardised set of query strings in their requests. The `pageSize` and `pageNumber` parameters are used to cycle through the available results from a top level API.

For example, `GET /contacts?pageSize=10&pageNumber=2` will return the second page of ten contact resources in the following structure:

| Response payload | Description                                                                              |
| ---------------- | ---------------------------------------------------------------------------------------- |
| `pageSize`       | The requested number of records per page. Default is 25 and maximum 100 unless specified |
| `pageNumber`     | The page number that this response represents                                            |
| `pageCount`      | The actual number of records that the current page contains                              |
| `totalPageCount` | The total number of pages available in the response                                      |
| `totalCount`     | The total number of resources available that fulfil the criteria of the current request  |
| `_embedded`      | The list of resources that have been returned in this paged response                     |

{% hint style="info" %}
**Extras field**\
If you represent an AgencyCloud customer and require access to data held in the 'extras' semi structured field, please submit a GitHub developer request using the issue template provided.
{% endhint %}

### Creating data

Our APIs support resource creation using the `POST` verb. When a creation request has been successfully fulfilled, you will receive a `201 Created` response.

The body of a `POST` request should always be sent as a JSON object, with the `Content-Type` header set to `application/json`

Since the creation of new resources is often asynchronous, we do not include the payload of the newly created resource in the `POST` response. Instead, we include the the location of where the new resource can be retrieved from in the `Location` header of the `POST` response.

### Updating data

Our APIs support resource updates using the `PATCH` verb. When an update request has been successfully fulfilled, you will receive a `204 No Content` response.

The body of a `PATCH` request should always be sent as a JSON object, with the `Content-Type` header set to `application/json`

When you provide an update to use using the `PATCH` verb, you're able to only update the parts of a resource that you care about, rather than completely replacing the entire resource. Usage is simple and you just need to specifically send us the data you wish to update.

The below example will only update the notes field on a representation that may allow you update many other attributes:

```javascript
{
  "notes": "Returned Mr Johnsons Call",
}
```

As with resource creation, we do not include the updated resource in the `PATCH` response. Instead, simply re-fetch the latest state of the resource by issuing a `GET` request.

### Uploading files

The following APIs allow consumers to upload certain types of documents to the Reapit Platform:

* documents
* propertyImages
* identityChecks

Each respective APIs `POST` endpoint supports uploads of content up to 6Mb in size, however we understand that there may sometimes be a legitimate need to upload larger files. To support this requirement, it is possible to obtain a pre-signed URL from each of these APIs which you can then send your data to.&#x20;

Please note that the 6Mb limit is the combined size of the different request components (headers, body etc). As a result the limit of the size of the encoded file being uploaded will in fact be slightly less than 6Mb.  In the case of endpoints that accept multiple documents, for example the POST /identityChecks endpoint, the *total* request size cannot exceed 6Mb.

#### Using pre-signed URLs

To upload larger files (between 6Mb and 30Mb), a pre-signed URL should be obtained from the Platform and used to upload your data. Each of the APIs listed in the [Uploading files](/api/api-documentation#uploading-files) section of this documentation has a `POST /signedUrl` endpoint which can be called to generate up to 10 pre-signed URLs. This can be useful where you need to upload more than one file.&#x20;

Use the following request body when calling the endpoint, setting amount to a value between 1 and 10 to have the respective number of URLs returned to you

```
POST /documents/signedUrl
{
    "amount": 2
}
```

The response will contain a collection of URLs which can then be used to upload your content to, along with an expiry date for the provided URLs, which will expire after 15 minutes

```
{
  "urls": [
    "https://reapit-file-uploads-prod.s3.eu-west-2.amazonaws.com/443e4a98-dfcb-4345-abb2-e52031928ed1?X-Amz-Expires=900&x-amz-security-token=IQoJb3JpZ2luX2VjEBcaCWV1LXdlc3QtMiJHMEUCIQC0Lx67%2F6JwNS9X7faUwm%2BwHYYpTLQ1UM42ge5WXDHKrgIgPh7r4O%2BLSlV0xhCQ5qoifZmIHajay2%2BMSddWghyj1Acq6wMIEBABGgw1MDM2MTQ4Mjg1MTciDO3pV3zkZcZVtWhWxyrIA6%2Bt4yRlh3g4B%2FCgt7T7YJ7yX3VUcOg%2F2fOKATN2qSqAjshXNMQ2ZKkqDDiHbAgvbzuZBkQDbKirksRmhqVGVv1A8VBcJ7JYP5jqpiwUuwgKjjQtsHWocKsfPVYsiBReiP%2Fw%2FJD9d0hWLPAvl%2FGwUoQr4bFveQxTTbh59G%2FUJx%2B%2BJO1vX3iAPLaLGSbEk7vWsyEDHlnCZKt3FftJ6rLlPlldzTLSl0dxjXUuYHXtwfHr2xT%2FMEkznvCxfYvhkRq2JqMrRFDs9HhYmgNKGSq22RTXpG6H6bvPj2CB1%2F2wKOAXbeZxnrtcWdnHlgE3xqOYwr1QaoL0w4llwGwGKIv5bQndF8MOiqDYIKZmWoH%2Bd3oQRfX2lFsBx3Ou1VDc4T28PkN8nPUnAx5OZ%2Fqu4A%2FWAbNnxM6L9%2B0kwDU0ijXro%2FjKNaTynYmqzNHVei6MTeEv7l2IaBV4eYZcU76jNIa8qPntGZjfCNm3nHHoTalPj6jYVYQJLGGe5OAa5U5YLm%2FczFhjPNQdBW5QsUaFEdccAV5QDYoQdaQba%2FnuTXvPS2147LYNdNMiQsi1M5peEhe89kaIitGONn9GOBXdeh2OBIrfRDYVICmQKjDjlbqHBjqlAUlaHQsfcgpG0NXSVM4q0XaxTWUQs117DKno2d5kJpur35M%2Bmk1ywaOg%2BQQs1elOD5lWUW7iQU8OKP6OFFe4pEMQlM02lz%2BtdNCy7aUQ%2FBVl43buUyDgciDI5DTbhEJe0LZuv1Yf0bGhuhtS%2FZhesqgbAlMVTwy8TiKPd7hE3%2FfsrThEtrgvrAMVSr4hbrZSDItfdsFb976epf%2BZt%2Fb5aTsz%2BxHzgA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAXKQOIN7STXK57JEK/20210714/eu-west-2/s3/aws4_request&X-Amz-Date=20210714T082753Z&X-Amz-SignedHeaders=host;x-amz-security-token&X-Amz-Signature=f8f5fb8919dc1a4aff335be64bd0746e6c523480f27a47d17106ed9d98181799",
    "https://reapit-file-uploads-prod.s3.eu-west-2.amazonaws.com/f6ea00ba-1b70-49ed-9a4a-d480d438d443?X-Amz-Expires=900&x-amz-security-token=IQoJb3JpZ2luX2VjEBcaCWV1LXdlc3QtMiJHMEUCIQC0Lx67%2F6JwNS9X7faUwm%2BwHYYpTLQ1UM42ge5WXDHKrgIgPh7r4O%2BLSlV0xhCQ5qoifZmIHajay2%2BMSddWghyj1Acq6wMIEBABGgw1MDM2MTQ4Mjg1MTciDO3pV3zkZcZVtWhWxyrIA6%2Bt4yRlh3g4B%2FCgt7T7YJ7yX3VUcOg%2F2fOKATN2qSqAjshXNMQ2ZKkqDDiHbAgvbzuZBkQDbKirksRmhqVGVv1A8VBcJ7JYP5jqpiwUuwgKjjQtsHWocKsfPVYsiBReiP%2Fw%2FJD9d0hWLPAvl%2FGwUoQr4bFveQxTTbh59G%2FUJx%2B%2BJO1vX3iAPLaLGSbEk7vWsyEDHlnCZKt3FftJ6rLlPlldzTLSl0dxjXUuYHXtwfHr2xT%2FMEkznvCxfYvhkRq2JqMrRFDs9HhYmgNKGSq22RTXpG6H6bvPj2CB1%2F2wKOAXbeZxnrtcWdnHlgE3xqOYwr1QaoL0w4llwGwGKIv5bQndF8MOiqDYIKZmWoH%2Bd3oQRfX2lFsBx3Ou1VDc4T28PkN8nPUnAx5OZ%2Fqu4A%2FWAbNnxM6L9%2B0kwDU0ijXro%2FjKNaTynYmqzNHVei6MTeEv7l2IaBV4eYZcU76jNIa8qPntGZjfCNm3nHHoTalPj6jYVYQJLGGe5OAa5U5YLm%2FczFhjPNQdBW5QsUaFEdccAV5QDYoQdaQba%2FnuTXvPS2147LYNdNMiQsi1M5peEhe89kaIitGONn9GOBXdeh2OBIrfRDYVICmQKjDjlbqHBjqlAUlaHQsfcgpG0NXSVM4q0XaxTWUQs117DKno2d5kJpur35M%2Bmk1ywaOg%2BQQs1elOD5lWUW7iQU8OKP6OFFe4pEMQlM02lz%2BtdNCy7aUQ%2FBVl43buUyDgciDI5DTbhEJe0LZuv1Yf0bGhuhtS%2FZhesqgbAlMVTwy8TiKPd7hE3%2FfsrThEtrgvrAMVSr4hbrZSDItfdsFb976epf%2BZt%2Fb5aTsz%2BxHzgA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAXKQOIN7STXK57JEK/20210714/eu-west-2/s3/aws4_request&X-Amz-Date=20210714T082753Z&X-Amz-SignedHeaders=host;x-amz-security-token&X-Amz-Signature=bc30d0325591bbb5a315440fcf3dc815b4339678282e737f7422fd926aba0d51"
  ],
  "expiration": "2021-07-14T08:42:53.6452618Z"
}
```

To then upload your file to the presigned URL, you will need to make a `PUT` to that URL with the 'Body' type set to 'Binary File'. Upload the file and 'Send'.&#x20;

When the file has been uploaded, you will still need to use the main `POST` endpoint of the relevant API to store your file to a customer's file system. Rather than sending the base64 encoded file content in the `fileData` property, you should use the `fileUrl` property and send the pre-signed URL that the file was sent to. The platform will then transfer the file from the holding area to the relevant customer's file system. It is not necessary to include all the query string parameters from the pre-signed URL in the subsequent `POST`, as per the example below

```
POST /documents
{
  "associatedType": "property",
  "associatedId": "OXF190347",
  "typeId": "DET",
  "name": "24 Smithson Road Details.pdf",
  "fileUrl": "https://reapit-file-uploads-prod.s3.eu-west-2.amazonaws.com/443e4a98-dfcb-4345-abb2-e52031928ed1",
}
```

To watch a short video on pre-signed URLs, please [click here](https://www.youtube.com/watch?v=lBYzD7T5_bQ).

### Request validation

To protect the integrity of our clients data, we enforce proper validation on all `POST` and `PATCH` requests

Should your request not pass the validation requirements of the endpoint, then you'll be issued a `422 Unprocessable Entity` code. The[ error response ](/api/api-documentation#errors)will include a listing of validation problems and how you can solve them.

```javascript
{
  "errors": [
    {
      "field": "type",
      "message": "The enum value provided for AreaType is incorrect"
    }
  ],
  "statusCode": 422,
  "dateTime": "2020-02-11T13:32:03.6759302Z",
  "description": "One or more validation failures have occurred. Please refer to Errors list for details"
}
```

### Optimistic concurrency

Our APIs serve Platform functionality and data to various different applications and users at the same time, which needs to be managed carefully to avoid concurrency problems.

In some systems, when multiple systems perform updates at the same time without knowledge of each others changes, you can be left with the problem of **lost updates** whereby the last update "wins" and previous updates are lost. Our APIs enforce o[ptimistic concurrency control](https://en.wikipedia.org/wiki/Optimistic_concurrency_control) to help avoid this problem.

We use [entity tags](https://tools.ietf.org/html/rfc7232#section-2.3) as an indicator of the current version of any resource returned from our APIs and whenever a singular representation is served by any of our `GET` endpoints, it will include `eTag` in the response header. For convenience, we also include this as an `_eTag` attribute in the response for each object.

This gives both client and server a means of understanding the version of a particular resource an application has received. Subsequently when a resource is updated, it's `eTag` value will also be updated.

To ensure that updates aren't lost, you must include an `If-Match` header in your `PATCH` request containing the `eTag` value exactly as you received it **including quotation marks.** The server will then compare its version of the resource with the `eTag` you provided.

* If they match, then the update is intended for the same version of the resource and the request will be processed&#x20;
* If they do not match, then the resource has been updated since it was fetched and the request will be rejected with a `412 Precondition Failed` error response

If rejected, you need to retrieve the latest version of the resource and replay your changes before attempting another update.

{% hint style="info" %}
**For more information** about entity tags and our implementation of conditional requests, please see [RFC 7232](https://tools.ietf.org/html/rfc7232)
{% endhint %}

## Versioning

As we evolve our platform, new features will be added and fixes will be made. We categorize changes in two ways: **breaking** and **non-breaking** changes. We make every effort to implement changes as non-breaking wherever possible, however, there are sometimes situations that require this.

Whenever a breaking change is introduced into our platform we release a new, dated version. The current version is **2020-01-31.**

All requests should indicate the version that should be used to fulfill them. You can do this by including the header `api-version` set to the dated version required.

### Breaking changes

We consider the following to be examples of breaking changes:

* Renaming or removing an existing field or endpoint
* Changing the URL structure of an existing endpoint
* Changing the filters that an existing endpoint provides
* Changing error response codes or messages that an endpoint provides
* Modifying or adding a new validation to an existing resource
* Changing the data type of an existing field
* Requiring a parameter that wasn't previously required

### Deprecation

Whenever a new version is released, the previous version enters its sunset period. This is presently six months though will be reviewed as our platform continues to grow and evolve.

At the end of a versions sunset period it will become deprecated and you will be required to adopt more recent version. You will be notified if your application is using a version that is soon to be deprecated.

{% hint style="info" %}
**Stay up to date:** please see the [help section](https://marketplace.reapit.cloud/developer/help) of our developer portal for information on recent and upcoming changes.
{% endhint %}

## Metadata

Our metadata system allows you to easily extend the data that our platform supports. Most of our POST and PATCH endpoints provide the ability to attach a JSON document to our entities which will be automatically included in future fetches of that entity.&#x20;

We also provide specific metadata endpoints for more direct, granular control on the data you provide. You can use these same endpoints to build new, standalone entities that are specific to your application without needing to hosting your own datastore.&#x20;

Metadata is specific to a customer and any data that your application sets will not be made available to users of your application who represent a different customer. We do not recommend using metadata storage for any sensitive information (personally identifiable details, bank accounts, etc).

### Attaching metadata to our entities

The easiest way to work with metadata is to populate the `metadata` attribute on our existing endpoints. You can provide a JSON document in the `PATCH` or `POST` payload as below:&#x20;

```javascript
{
  <rest_of_payload>
  ...
  "metadata": {
    "MyCustomField1": "MyCustomValue1",
    "MyCustomField2": true
  }
}
```

Once metadata has been set against an entity, it will be automatically returned in the same format for future `GET` requests originating from your app.&#x20;

For more granular control, you can use our dedicated metadata endpoints to create, update and retrieve outside of the context of one of our Foundations endpoints.

### Creating custom entities

You can use these metadata endpoints to use Foundations as a simple datastore. You can create a standalone entity by providing a custom `entityType` with your JSON payload. You can then fetch, filter and update your entity using the `/metadata` REST endpoints we provide.

```javascript
{
  "entityType": "myCustomEntityType",
  "entityId": "75c46440-5cb9-4db1-801d-f57eab8999e2",
  "metadata": {
    "CustomStringField": "my string",
    "CustomBoolField": false,
    "CustomNumericField": 100.5,
    "CustomDateField": "2019-06-15T13:45:30Z"
  }
}
```

If you'd like to associate your custom entity with an entity your hold outside of Foundations, you may pass in an `entityId` which you can later use for searching/filtering. If you do not, an `entityId` will be generated and returned to you automatically.&#x20;

### Validating custom entities

Our `metadataSchema` endpoints allow you to provide a [JSON Schema](https://json-schema.org/) to validate the metadata JSON document that you provide the platform. Once you associate a schema with a custom entity type, you it will be used to validate future metadata submissions for entities of that type. If this content does not conform with the JSON schema you've provided for that entity type, the request with fail with a `422 Unprocessable Entity` response and a[ listing of the reasons why validation](/api/api-documentation#request-validation) failed. For more information, see our Swagger documentation.

### Searching for metadata

{% hint style="warning" %}
**Breaking change - coming soon**

From October 28th, 2026 metadata GET requests will only support `$eq`, `$ne` and `$con` .
{% endhint %}

Once metadata has been set against an entity, its content can then be used to re-locate that entity by using your metadata as a search term. The `metadata` query string parameter accepts a filter expression to identity the record(s) required in the following prescribed format:

`GET /<endpoint>?metadata=metadata.<fieldName> <operation> <criteria>`

Failure to adhere to the format required will provide a `400 Bad Request` response detailing the problem. If you are having trouble, consult our example [usage guide](/api/api-documentation#example-usage) below.

### Search operations

We support querying using up to eight different filter operations, depending on the data type of the metadata field you’re searching upon.

| **Operation**            | **Keyword** | **Information**                                                                                                                     |
| ------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Equals                   | **$eq**     | Works for all data types                                                                                                            |
| Not equals               | **$ne**     | Works for all data types                                                                                                            |
| Greater than             | **$gt**     | Works for datetime and numeric data types                                                                                           |
| Less than                | **$lt**     | Works for datetime and numeric data types                                                                                           |
| Greater than or equal to | **$gte**    | Works for datetime and numeric data types                                                                                           |
| Less than or equal to    | **$lte**    | Works for datetime and numeric data types                                                                                           |
| In list                  | **$in**     | Provide a comma separated list of values to check for the value provided within. Works for string, datetime and numeric data types. |
| Not in list              | **$nin**    | Provide a comma separated list of values to check for the value provided within. Works for string, datetime and numeric data types. |
| Contains                 | **$con**    | Provide a comma separate list of values to determine if they exist in the specified array                                           |

### Example usage

| Criteria Type | Example filters                                                                                                                                 | Information                                                            |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Boolean**   | metadata.myBooleanField $eq true                                                                                                                | Only works for `$eq` and `$neq`. Criteria must be either true or false |
| **Numeric**   | <p>metadata.myNumericField $gte 100<br></p><p>metadata.myNumericField $nin 30,50,60,100</p>                                                     | Criteria decimal places                                                |
| **String**    | <p>metadata.myStringField $neq ‘London’<br></p><p>metadata.myStringField $in ‘red’,’brown’,’green’<br><br>metadata.myArray $con 'ONE','TWO'</p> | Criteria must be contained within apostrophes                          |
| **DateTime**  | <p>metadata.myDateField $lt <br>2020-11-05T13:15:30Z<br></p><p>metadata.myDateField $eq 2020-11-05</p>                                          | Time component is optional. Must be provided in ISO 8601 format.       |

### Additional information

* Metadata filtering is not case sensitive
* Metadata filter expressions are additive and can be used any number of times by providing the `metadata` query string more than once
* Metadata filter expressions can be used in conjunction with any other query string parameter that an endpoint makes available. &#x20;
* Metadata filtering can use the dot notation format to search for data stored in a nested structure.

## Hypermedia

Our APIs are **REST level 3**[ ](https://restfulapi.net/richardson-maturity-model/)and implement [hypermedia controls](https://restfulapi.net/richardson-maturity-model/) to improve the developer experience of using our platform. Hypermedia makes our APIs self documenting, easier to use and aids discovery. We adopt the [HAL hypertext application language](http://stateless.co/hal_specification.html) to serve as our message format.

### Links

Each `GET` response provides a uniform interface to present links to demonstrate **which** data is related and **how** that data can be retrieved. This is particularly useful for APIs that present complex systems of interrelated data, such as ours.

&#x20;Each resource, including [collection resources](/api/api-documentation#pagination), include a `_links` collection to present related data. The responses `_links` dictionary will include a **key** to represent the type of relationship and a **value** to represent the location where the related resources can be obtained from.

The **condensed** `GET /contact/{id}` payload example below demonstrates how relationships are presented:

```
{
  "id": "OXF18000001",
  "created": "2018-02-12T09:45:01.0000000Z",
  "modified": "2019-06-23T12:30:12.0000000Z",
  "title": "Mr",
  "forename": "John",
  "surname": "Smith",
  "dateOfBirth": "1992-08-12",
  "homePhone": "01234 567890",
  "mobilePhone": "07890 123456",
  "email": "example@email.com",
  "officeIds": [
    "OXF"
  ],
  "negotiatorIds": [
    "JAS"
  ],
  "_eTag": ""33a64df551425fcc55e4d42a148795d9f25f89d4"",
  "_links": {
    "self": {
      "href": "/contacts/OXF18000001"
    },
    "documents": {
      "href": "/documents/?ownerType=contact&ownerId=OXF18000001"
    },
    "identityChecks": {
      "href": "/identityChecks/?contactId=OXF18000001"
    },
    "offices": {
      "href": "/offices/?id=OXF"
    },
    "negotiators": {
      "href": "/negotiators/?id=JAS"
    }
  },
  "_embedded": null
}
```

In the example above, the presence of the `identityChecks` **key** indicates that there is a related resource available. The **value** contains the service location and query string parameters required to retrieve the related identity check resources.

### Embedding data

Many of our GET APIs provide the ability to compose requests that automatically **embed related data** in their responses. This is a convenient tool that reduces the number of round trips your application needs to make to our Platform. Using this mechanism can result in improved application performance with less API interaction code required.

If your application requires data from one or more related resource(s) (indicated by a link), you can simply specify the name of the related resource in the `embed` parameter and our APIs will do the rest. So long as the related data exists, it is returned to your app in the correct resource(s) `_embedded` data collection.

{% hint style="info" %}
This mechanism allows your application to make fewer round trips to the server by allowing our APIs to make requests on your applications behalf. Any request triggered by the embed mechanism will still contribute to your usage statistics in the same way as if they were directly issued from your application. See the [Billing Example](#billing-example) for further information
{% endhint %}

You can embed as many related data sources in a request as your application requires. Our [interactive API explorer](https://developers.reapit.cloud/swagger) provides a user interface which demonstrates the available `embed` parameter options for each API.

#### Example

`GET /contacts/OXF18000001/?embed=offices&embed=negotiators`

The request above illustrates the means of requesting that related office and negotiator resources are included with the response from the contacts API. The condensed response below demonstrates how these related resources are returned within the contacts payload in the `_embedded` attribute.

```
{
  "id": "OXF18000001",
  "title": "Mr",
  "forename": "John",
  "surname": "Smith",
  "officeIds": [
    "OXF"
  ],
  "negotiatorIds": [
    "JAS"
  ],
  
  <rest of contacts payload>
  
  "_links": {
    "self": {
      "href": "/contacts/OXF18000001"
    },
    "offices": {
      "href": "/offices/?id=OXF"
    },
    "negotiators": {
      "href": "/negotiators/?id=JAS"
    }
  },
  "_embedded": {
    "offices" : [
      {
        "id": "OXF",
        "name": "Oxford",
        "manager": "David Brown",
        "address": {
          "buildingName": "",
          "buildingNumber": "1a",
          "line1": "Wellington Square",
          "line2": "Brownhaven",
          "line3": "Oxford",
          "line4": "",
          "postcode": "OX1 2JD"
        },
        
        <rest of offices payload>
      }
    ],
    "negotiators" : [
      {
        "id": "JAS",
        "name": "John Smith",
        "jobTitle": "Senior Negotiator",
        "active": true,
        "officeId": "OXF",
        "email": "drew.mcculloch@reapitestates.net",
        
        <rest of negotiators payload>
      }
    ],
  }
}
```

#### Billing Example

It can be difficult to understand how using the embed mechanism affects your usage and overall bill. As mentioned previously, requests made using this feature are billed as though you made the request yourself. All embed operations use the maximum page size of 100 resources per page to limit the number of background API calls.&#x20;

As an example, considering the following request:

`GET https://platform.reapit.cloud/properties?embed=images&pageSize=50`

If the above request returns 50 properties and each property has a total of 15 images, your usage is calculated as follows:

1x request to properties endpoint

(50 properties \* 15 images per property) / 100 = 8 requests to the property images endpoint as there are 7 full pages, and one partial page of images&#x20;

Total of 9 billable calls


# Webhooks

Technical guidance for working with webhooks for real time event notifications

## Introduction

Webhooks allow you set up an endpoint in your own application to receive programmatical notifications from the Foundations Platform about changes to our customers data as it happens.

Rather than requiring you to pull information via our APIs, webhooks will **push** information to your endpoint. When one of those events is triggered (eg. a new offer is added), our Platform will send this notification as an HTTP `POST` request to the endpoint(s) you configure.

Applications that use webhooks benefit from greater efficiency, reduced costs and the ability to respond to customer driven events in real-time.

## Getting started

### Registering your app

The first step to start receiving webhooks is to register your app within our AppMarket. You don't need to list the application at this stage, but note that some [subscription topics](#subscription-topics) require that your app is granted an associated scope. Please see our [developer portal documentation](/developer-portal) for more information on submitting an app.

### Provide an endpoint

You must provide an endpoint to receive the payload the Platform will send to your app. The endpoint should:

* Be a publicly available valid URI that:
  * Uses the `https` scheme
  * Accepts `POST` requests
  * Accepts a request body with an `application-json` content type

{% hint style="info" %}
**You can use a third party service** to quickly get to grips with webhooks. Services like [RequestBin](https://www.requestbin.com) and [Webhook.site](https://webhook.site) instantly setup a secure URL to receive the `POST` request on your behalf and provide a UI to review what data has been sent.
{% endhint %}

### Securing your endpoint

**Cryptographic Signing**

Asymmetric request signing with a public/private key pair has now been introduced and should be used over the legacy method above, which will become obsolete at some point in the future.

When a new webhook is setup in the [DeveloperPortal](https://developers.reapit.cloud/webhooks/new), a public/private key pair will be generated and stored for the app that the webhook is associated with. The keys are associated to the app, rather than the webhook itself, so if you have two webhooks for the same app, they will be signed with the same key.

As each event is prepared to be sent to your endpoint, it will be signed using the private key which is stored securely and only visible to the Platform Webhooks services. Once the message reaches you, you can verify it has come from the Reapit Platform by using the public key to check it's authenticity. To do this, complete the following steps

1. Read the `X-Signature` header from the request. This will be in the following format:\
   \
   `s:keyId:timestamp:signature`\
   \
   Full example:\
   \
   `s:98da2881-0540-48db-8ffa-45d7003f1412:1650934596:LLD5mr9ynFEvjz8dVmwO4vNmEva32ZV6TjAcPzdIDO93Jhc82EhysiQPcw9ZdlbCcCUjDsaeHZUsFEMUVKbGBg`<br>
2. Retrieve the public key for your app by using one of the following methods:\
   \
   A) Use the `Public Key` option in the DeveloperPortal to retrieve the key for your app or\
   B) Make a call to `GET https://platform.reapit.cloud/webhooks/signing/{id}` where {id} is the id obtained from the X-Signature header (segment 2)\
   \
   Data from this endpoint will be returned in the following format:<br>

   ```
   {
     "keys": [
       {
         "kid": "08da3720-99e7-42c3-8531-58bdc8f32ecf",
         "crv": "Ed25519",
         "x": "ijz3_2n1gmlfhqAa2XH_5uYmcL2L2VHb1IqDbRDLBnU"
       }
     ]
   }
   ```

   \
   Calls to this endpoint must include the Authorization header containing a valid Bearer token. It is only possible to retrieve keys associated to the calling app when accessing the key programmatically.<br>
3. Decode the `x` value from the results using the Base64 URL scheme (if using method A above, this is the value displayed to you in the DeveloperPortal)
4. Combine the timestamp (segment 3) from the `X-Signature` header and the webhook message body (do not include a separation character)
5. Verify the signature (segment 4 of the `X-Signature` header) using the Ed25519 curve, using the public key and a combination of the timestamp/message body as above.

There are various packages available for many popular programming languages that allow you to easily verify signatures generated using the Ed25519 curve. Whilst this algorithm is less widely used than RSA, it is considered more secure hence it's use in the Platform. The code examples below can be used as a reference point, but should not be considered production ready code:

{% tabs %}
{% tab title="NodeJS with Express" %}
The following example uses Node JS with Express, Node Forge and Body Parser npm packages

```javascript
const express = require('express');
const crypto = require('node-forge');
const bodyParser = require('body-parser');

// Configure Express
const app = express();
const port = 5000;

// Be sure to read the raw request body, rather than
// using a JSON pre-processor/JSON.stringify()
app.use(bodyParser.raw({ inflate: true, type: 'application/json' }));

// Setup POST handler
app.post('/', function (req, res) {
    const ED25519 = crypto.pki.ed25519;

    // Read the X-Signature header
    const sigHeader = req.header("x-signature");
    const sigParts = sigHeader.split(":");
    
    // Read the signature segments
    const keyId = sigParts[1];
    const timestamp = sigParts[2];
    const signature = sigParts[3];

    // The message to verify is a concatenation of the timestamp (from the X-Signature header)
    // and the raw request body, with no delimiting characters
    const msgToVerify = `${timestamp}${req.body.toString()}`;

    // Retrieve the public key from the respective endpoint
    // or store OUTSIDE your code. This is an example only
    const publicKeyBase64 = "ijz3_2n1gmlfhqAa2XH_5uYmcL2L2VHb1IqDbRDLBnU";

    // Verify the signature
    const verified = ED25519.verify({
        message: msgToVerify,
        encoding: "utf8",
        signature: Buffer.from(signature, "base64"),
        publicKey: Buffer.from(publicKeyBase64, "base64")
    });

    if (verified) {
        console.log("Signature is valid");

        // Continue to process webhook
    }
    else {
        console.log("Signature is invalid");
    }

    res.send("Webhook processing complete");
});

// Start the server
app.listen(port, () => {
    console.log(`Now listening on port ${port}`);
}); 
```

{% endtab %}

{% tab title=".NET Core" %}
The following example uses C# .NET Core with the BouncyCastle.NETCore NuGet package<br>

```csharp
using System;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.WebUtilities;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Primitives;
using Org.BouncyCastle.Crypto.Parameters;
using Org.BouncyCastle.Crypto.Signers;

namespace WebhookHandlerExample.Controllers
{
    [ApiController]
    [Route("/")]
    public class WebhookHandlerController : ControllerBase
    {
        private readonly ILogger<WebhookHandlerController> logger;

        public WebhookHandlerController(ILogger<WebhookHandlerController> logger)
        {
            this.logger = logger ?? throw new ArgumentNullException(nameof(logger));
        }

        [HttpPost]
        public async Task<IActionResult> PostHandler([FromBody] dynamic body)
        {
            if (Request.Headers.TryGetValue("X-Signature", out StringValues signatureHeader))
            {
                string[] sigParts = signatureHeader.First().Split(":");

                // Read the signature segments
                var keyId = sigParts[1];
                var timestamp = sigParts[2];
                var signature = sigParts[3];

                // The message to verify is a concatenation of the timestamp (from the X-Signature header)
                // and the raw request body, with no delimiting characters
                var msgToVerify = $"{timestamp}{body}";

                // Retrieve the public key from the respective endpoint
                // or store OUTSIDE your code. This is an example only
                var publicKeyBase64 = "ijz3_2n1gmlfhqAa2XH_5uYmcL2L2VHb1IqDbRDLBnU";

                CryptographyService cryptoService = new CryptographyService();

                bool verified = cryptoService.VerifySignature(msgToVerify, publicKeyBase64, signature);

                if (verified)
                {
                    this.logger.LogInformation("Signature is valid");

                    // Continue to process webhook
                }
                else
                {
                    this.logger.LogError("Signature is invalid");
                }

                return Ok("Webhook processing complete");
            }

            return Ok("No signature was found in the message header collection");
          
        }
    }

    internal class CryptographyService
    {
        /// <summary>
        /// Verifies the specified signature against the public key supplied
        /// </summary>
        /// <param name="message">The message used to generate the isngautre</param>
        /// <param name="encodedPublicKey">The encoded public key</param>
        /// <param name="signature">The signature to verify</param>
        /// <returns>True if the signature is valid, else false</returns>
        public bool VerifySignature(string message, string encodedPublicKey, string signature)
        {
            byte[] decodedPublicKey = WebEncoders.Base64UrlDecode(encodedPublicKey);
            byte[] messageBytes = Encoding.UTF8.GetBytes(message);
            byte[] signatureBytes = WebEncoders.Base64UrlDecode(signature);

            // Setup validator using Ed25519 curve
            var keyParams = new Ed25519PublicKeyParameters(decodedPublicKey, 0);

            var validator = new Ed25519Signer();
            validator.Init(false, keyParams);
            validator.BlockUpdate(messageBytes, 0, messageBytes.Length);

            bool isValidSignature = validator.VerifySignature(signatureBytes);

            return isValidSignature;
        }
    }
}
```

{% endtab %}
{% endtabs %}

## Managing webhooks in the user interface

We offer a user interface to allow you to manage webhooks in a simple and straightforward way. You're able to create, update and remove webhooks for all of your applications in a single place.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FCJcdiBhMPLz22QUYuJxD%2FWebhooks%201.jpg?alt=media&amp;token=d84e7ad8-d21e-47ab-aeec-6b673d3f197a" alt=""><figcaption></figcaption></figure>

### Creating a webhook

First, select the application that you want to create a webhook for. You'll then be given the option to 'Add New Webhook', as above. The modal below allows you to [input the endpoint](#provide-an-endpoint) where information should be pushed.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FEdM4dOqxsjrHauMlglLy%2FWebhooks%202.jpg?alt=media&amp;token=84828827-5e42-4666-ad75-31eb6eb54d44" alt=""><figcaption></figcaption></figure>

Our webhooks system is designed to flexibly work with how your application is built and deployed. If you wish, you can set up a single endpoint to catch all **topics** for all **customers**. Alternatively, you may wish to set up a different webhook subscription per topic or per customer.

{% hint style="info" %}
If you are using AWS API Gateway as the entrypoint for your event handler, please note that you cannot use the AWS DNS namespace (in the format https\://{api-id}.execute-api.{region}.{amazonaws}.com/) for your webhook URL due to the way some of the internal routing at Reapit is configured. To work around this, simply add a Custom Domain to your API Gateway, and use that in your webhook configuration instead
{% endhint %}

### Subscribe to topics

As part of creating a new webhook, you need to specify which of the available **topics** (type of event) that your application needs to respond to. If any application makes a change to a customers data that corresponds to a topic that your app is listening for, you'll receive a notification to describe the event.

Data changes from any application will result in a notification being sent to your endpoint(s), including:

* [Reapit Agency Cloud](https://www.reapit.com/agency-cloud)
* [Reapit Property Cloud](https://www.reapit.com/property-cloud/)
* Any other Reapit AppMarket application

For example, if a new offer is added in our AgencyCloud CRM and your application has a webhook set up containing the **offers.created** topic, your endpoint will be sent a specific, descriptive payload containing the full details of the new offer.

{% hint style="success" %}
**We recommend** registering your webhooks in an inactive state and using the **Ping** function. This allows you to test that your endpoint works as expected before opting to receive live customer updates.
{% endhint %}

We currently support the following topics, but this will increase over time. Please note that you will only be presented topics if your application has been assigned the associated scope.

### Available topics

> Webhook payload types are available from `@reapit/foundations-ts-definitions` [see here for more info](https://foundations-documentation.reapit.cloud/app-development/foundations-ts-defintions#webhook-types)

If you have a requirement to target very specific events in a customer's system, you may wish to look at [building your own event filter](#building-event-filters) to build on the default topic capability.

| Topic                                     | Description                                                                                                                                                                                                                                                                                | Required scopes       |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- |
| **application.install\***                 | Occurs when a customer installs an application in the AppMarket                                                                                                                                                                                                                            | None                  |
| **application.uninstall\***               | Occurs when a customer uninstalls an application in the AppMarket                                                                                                                                                                                                                          | None                  |
| **applicants.created**                    | Occurs when a new [applicant](https://foundations-documentation.reapit.cloud/platform-glossary#applicant) is created                                                                                                                                                                       | `applicants.read`     |
| **applicants.modified**                   | Occurs when an existing [applicant](https://foundations-documentation.reapit.cloud/platform-glossary#applicant) is modified, or any of the associated [contacts](https://foundations-documentation.reapit.cloud/platform-glossary#contact) are modified                                    | `applicants.read`     |
| **appointments.cancelled**                | Occurs when a new [appointment ](/platform-glossary#appointment)is created as cancelled, or an existing appointment is cancelled                                                                                                                                                           | `appointments.read`   |
| **appointments.confirmed**                | Occurs when an [appointment ](/platform-glossary#appointment)is created or modified and all required parties have confirmed attendance                                                                                                                                                     | `appointments.read`   |
| **appointments.created**                  | Occurs when a new [appointment](https://foundations-documentation.reapit.cloud/platform-glossary#appointment) is created                                                                                                                                                                   | `appointments.read`   |
| **appointments.modified**                 | Occurs when an existing [appointment](https://foundations-documentation.reapit.cloud/platform-glossary#appointment) is modified                                                                                                                                                            | `appointments.read`   |
| **companies.created**                     | Occurs when a new [company](https://foundations-documentation.reapit.cloud/platform-glossary#company) is created                                                                                                                                                                           | `companies.read`      |
| **companies.modified**                    | Occurs when an existing [company](https://foundations-documentation.reapit.cloud/platform-glossary#company) is modified                                                                                                                                                                    | `companies.read`      |
| **contacts.created**                      | Occurs when a new [contact](https://foundations-documentation.reapit.cloud/platform-glossary#contact) is created                                                                                                                                                                           | `contacts.read`       |
| **contacts.landlorddetails.updated**      | Occurs when an agent updates a landlord Making Tax Digital consent status                                                                                                                                                                                                                  | `contacts.read`       |
| **contacts.modified**                     | Occurs when an existing [contact](https://foundations-documentation.reapit.cloud/platform-glossary#contact) is modified                                                                                                                                                                    | `contacts.read`       |
| **contacts.optedout**                     | Occurs when a new [contact ](/platform-glossary#contact)is created with marketing consent set to deny, or the marketing consent state of an existing contact is changed to deny                                                                                                            | `contacts.read`       |
| **conveyancing.modified**                 | Occurs when an existing [conveyancing ](/platform-glossary#conveyancing)(sales progression) entity is modified                                                                                                                                                                             | `conveyancing.read`   |
| **documents.created**                     | Occurs when a new [document ](/platform-glossary#document)is created                                                                                                                                                                                                                       | `documents.read`      |
| **documents.modified**                    | Occurs when an existing [document](/platform-glossary#document) is modified                                                                                                                                                                                                                | `documents.read`      |
| **enquiries.accepted**                    | Occurs when an existing [enquiry](/platform-glossary#enquiry) has a status change to added                                                                                                                                                                                                 | `enquiries.read`      |
| **enquiries.created**                     | Occurs when a new [enquiry ](/platform-glossary#enquiry)is created                                                                                                                                                                                                                         | `enquiries.read`      |
| **enquiries.modified**                    | Occurs when an existing [enquiry](/platform-glossary#enquiry) is modified                                                                                                                                                                                                                  | `enquiries.read`      |
| **enquiries.rejected**                    | Occurs when an existing [enquiry](/platform-glossary#enquiry) has a status change to rejected                                                                                                                                                                                              | `enquiries.read`      |
| **identitychecks.created**                | Occurs when a new [identity check](https://foundations-documentation.reapit.cloud/platform-glossary#identity-check) is created against an existing [contact](https://foundations-documentation.reapit.cloud/platform-glossary#contact)                                                     | `identitychecks.read` |
| **identitychecks.modified**               | Occurs when an existing [identity check](https://foundations-documentation.reapit.cloud/platform-glossary#identity-check) is modified                                                                                                                                                      | `identitychecks.read` |
| **landlords.created**                     | Occurs when a new [landlord](https://foundations-documentation.reapit.cloud/platform-glossary#landlord) is created                                                                                                                                                                         | `landlords.read`      |
| **landlords.modified**                    | Occurs when an existing [landlord](https://foundations-documentation.reapit.cloud/platform-glossary#landlord) is modified, or any of the associated [contacts](https://foundations-documentation.reapit.cloud/platform-glossary#contact) are modified                                      | `landlords.read`      |
| **offers.accepted**                       | Occurs when a new [offer ](/platform-glossary#offer)is created in an accepted state, or the status of an existing offer is changed to accepted                                                                                                                                             | `offers.read`         |
| **offers.created**                        | Occurs when a new [offer](https://foundations-documentation.reapit.cloud/platform-glossary#offer) is created                                                                                                                                                                               | `offers.read`         |
| **offers.modified**                       | Occurs when an existing [offer](https://foundations-documentation.reapit.cloud/platform-glossary#offer) is modified                                                                                                                                                                        | `offers.read`         |
| **offers.rejected**                       | Occurs when a new [offer ](/platform-glossary#offer)is created in a withdrawn state, or the status of an existing offer is changed to withdrawn                                                                                                                                            | `offers.read`         |
| **offers.withdrawn**                      | Occurs when a new [offer ](/platform-glossary#offer)is created in a rejected state, or the status of an existing offer is changed to rejected                                                                                                                                              | `offers.read`         |
| **offices.created**                       | Occurs when a new [office](https://foundations-documentation.reapit.cloud/platform-glossary#office) is created                                                                                                                                                                             | `offices.read`        |
| **offices.modified**                      | Occurs when an existing [office](https://foundations-documentation.reapit.cloud/platform-glossary#office) is modified                                                                                                                                                                      | `offices.read`        |
| **properties.created**                    | Occurs when a new [property](https://foundations-documentation.reapit.cloud/platform-glossary#property) is created                                                                                                                                                                         | `properties.read`     |
| **properties.modified**                   | Occurs when an existing [property](https://foundations-documentation.reapit.cloud/platform-glossary#property) is modified                                                                                                                                                                  | `properties.read`     |
| **properties.selling.askingpricechanged** | Occurs when the asking price of an existing sales [property](/platform-glossary#property) is changed                                                                                                                                                                                       | `properties.read`     |
| **properties.selling.completed**          | Occurs when a new sales [property ](/platform-glossary#property)is created with a status of completed, or an existing sales property's status is changed to completed                                                                                                                      | `properties.read`     |
| **properties.selling.exchanged**          | Occurs when a new sales [property ](/platform-glossary#property)is created with a status of exchanged, or an existing sales property's status is changed to exchanged                                                                                                                      | `properties.read`     |
| **properties.selling.withdrawn**          | Occurs when a new sales [property ](/platform-glossary#property)is created with a status of withdrawn, or an existing sales property's status is changed to withdrawn                                                                                                                      | `properties.read`     |
| **properties.selling.instructed**         | Occurs when a new sales [property ](/platform-glossary#property)is created with a status of forSale or forSaleUnavailable, or an existing sales property's status is changed to forSale or forSaleUnavailable, and the previous status was one of preAppraisal, valuation or paidValuation | `properties.read`     |
| **properties.selling.lostinstruction**    | Occurs when a new sales [property ](/platform-glossary#property)is created in a lost instruction state, or an existing sales property's lost instruction data has been set for the first time                                                                                              | `properties.read`     |
| **properties.selling.underoffer**         | Occurs when a new sales [property ](/platform-glossary#property)is created with a status of underOffer or underOfferUnavailable, or an existing sales property's status is changed to underOffer or underOfferUnavailable                                                                  | `properties.read`     |
| **propertyimages.created**                | Occurs when a new [property image](/platform-glossary#property-image) has been created                                                                                                                                                                                                     | `properties.read`     |
| **propertyimages.modified**               | Occurs when an existing [property image](/platform-glossary#property-image) has been modified                                                                                                                                                                                              | `properties.read`     |
| **referrals.created**                     | Occurs when a new [referral ](/platform-glossary#referral)has been created                                                                                                                                                                                                                 | `referrals.read`      |
| **referrals.modified**                    | Occurs when an existing [referral ](/platform-glossary#referral)has been modified                                                                                                                                                                                                          | `referrals.read`      |
| **tenancies.created**                     | Occurs when a new [tenancy ](/platform-glossary#tenancy)has been created                                                                                                                                                                                                                   | `tenancies.read`      |
| **tenancies.modified**                    | Occurs when an existing [tenancy ](/platform-glossary#tenancy)has been modified                                                                                                                                                                                                            | `tenancies.write`     |
| **vendors.created**                       | Occurs when [vendor](https://foundations-documentation.reapit.cloud/platform-glossary#vendor) information has been associated with a sales property for the first time                                                                                                                     | `vendors.read`        |
| **vendors.modified**                      | Occurs when vendor information is modified or any of the associated [vendor](https://foundations-documentation.reapit.cloud/platform-glossary#vendor) contacts are modified                                                                                                                | `vendors.read`        |
| **worksorders.cancelled**                 | Occurs when a new [works order](/platform-glossary#works-order) is created in a cancelled state, or the status of an existing works order is changed to cancelled                                                                                                                          | `worksorders.read`    |
| **worksorders.complete**                  | Occurs when a new [works order](/platform-glossary#works-order) is created in a complete state, or the status of an existing works order is changed to complete                                                                                                                            | `worksorders.read`    |
| **worksorders.modified**                  | Occurs when an existing [works order](https://foundations-documentation.reapit.cloud/platform-glossary#works-order) is modified                                                                                                                                                            | `worksorders.read`    |
| **worksorders.raised**                    | Occurs when a new [works order](/platform-glossary#works-order) is created in a raised state, or the status of an existing works order is changed to raised                                                                                                                                | `worksorders.read`    |

{% hint style="info" %}
The application.install and application.uninstall webhook events include identifiers for your app in the payload. Please note that *applicationId* corresponds to the Authentication Client Id and *internalAppId* corresponds to the App Id displayed on your App Listing in the Developer Portal
{% endhint %}

### Subscribe to customers

You must configure the customer(s) that your webhook will respond to events for. Only customers who have installed your listed application will appear here.

* Specify one or more customers to receive only event originating from those customers
* Specify 'SBOX' to listen to events triggered from our sandbox (useful for testing)
* Leave this field blank to respond to events for all customers who have installed your application. You will immediately receive events for new customers who install your application without any configuration change required. This does not include sandbox events.

### Building event filters

There are several scenarios where the list of available topics results in a large number of irrelevant events being submitted to your endpoint. In response to a high frequency of requests of additional topics, or more granular filtering capabilities, it is possible to attach one or more event schema filters to your webhooks. This is an advanced feature that allows you to build on top of the default topic availability and target specific events. Please note that this is still in beta testing and not generally available

Webhook event filters are based on the [JSON Schema specification](https://json-schema.org/) and, put simply, a schema is used to validate the content of an event from our customer's systems which will only be sent to your endpoint in the event that validation is successful. This mechanism gives you the ability to define specific rules, for example if you want to target specific appointment types when listening to appointments.created and/or appointments.modified topics. An event filter is tied to a single specific topic so it is not necessary to check the topic id as part of the filter, however if can be good practice to include this, as is shown in the Starter Template. The tabs below provide some examples of event filters that can be used as a starting point.

It is possible to stack event filters to keep each individual filter quite lightweight. For example, if you wanted to build a filter that ensured that an appointment was of valuation type AND associated to one of a defined list of negotiator ids, this could be achieved by creating two separate filters (one for each rule) or a single filter with both rules applied. All filters must pass validation for the event to be sent to your endpoint

{% tabs %}
{% tab title="Starter Template" %}

```javascript
{
    "$schema": "https://json-schema.org/draft/2019-09/schema",
    "description": "Filter Starter Template",
    "type": "object",
    "properties": {
        "new": {
        },
        "topicId": {
            "type": "string",
            "oneOf": [
                {
                    "pattern": "appointments.modified"
                },
                {
                    "pattern": "appointments.created"
                }
            ]
        }
    },
    "required": [
        "topicId",
        "new"
    ]
}
```

{% endtab %}

{% tab title="Specific Appointment Types" %}
The following schema will target appointments with a typeId of VL (valuation). Note that whilst the topicId validation is done against both appointments.modified AND appointments.created events, the filter can only be applied to a single topic, and so would need to be configured twice, once for each topic

```javascript
{
    "$schema": "https://json-schema.org/draft/2019-09/schema",
    "description": "Valuation Appointments",
    "type": "object",
    "properties": {
        "new": {
            "type": "object",
            "properties": {
                "typeId": {
                    "type": "string",
                    "oneOf": [
                        {
                            "pattern": "VL"
                        }
                    ]
                }
            },
            "required": [
                "typeId"
            ]
        },
        "topicId": {
            "type": "string",
            "oneOf": [
                {
                    "pattern": "appointments.modified"
                },
                {
                    "pattern": "appointments.created"
                }
            ]
        }
    },
    "required": [
        "topicId"
    ]
}
```

{% endtab %}

{% tab title="New Instructions Above Price" %}
The following schema will target modified properties that have just been instructed with an asking price of 500,000 or greater. This might be used to specifically target high value properties for a more luxury property portal.

```javascript
{
    "$schema": "https://json-schema.org/draft/2019-09/schema",
    "description": "Instructions above 500,000",
    "type": "object",
    "properties": {
        "new": {
            "type": "object",
            "properties": {
                "selling": {
                    "type": "object",
                    "properties": {
                        "price": {
                            "type": "number",
                            "minimum": 500000
                        },
                        "status": {
                            "type": "string",
                            "oneOf": [
                                {
                                    "pattern": "^forSale.*"
                                }
                            ]
                        }
                    },
                    "required": [
                        "price",
                        "status"
                    ]
                }
            },
            "required": [
                "selling"
            ]
        },
        "diff": {
            "type": "object",
            "properties": {
                "selling": {
                    "type": "object",
                    "properties": {
                        "price": {
                            "type": "array",
                            "items": [
                                {
                                    "type": "number"
                                },
                                {
                                    "type": "number",
                                    "minimum": 500000
                                }
                            ]
                        },
                        "status": {
                            "type": "array",
                            "items": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "string",
                                    "oneOf": [
                                        {
                                            "pattern": "^forSale.*"
                                        }
                                    ]
                                }
                            ]
                        }
                    },
                    "required": [
                        "status"
                    ]
                }
            },
            "required": [
                "selling"
            ]
        }
    },
    "anyOf": [
        {
            "required": [
                "new"
            ]
        },
        {
            "required": [
                "new",
                "diff"
            ]
        }
    ]
}
```

{% endtab %}

{% tab title="Changes to Latitude or Longitude" %}
The following schema detects changes to either the latitude or longitude on a property resource. This might used by systems that generate map or geospatial data based on property information in a customers' database

```
{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "description": "Changes to latitude or longitude",
  "type": "object",
  "properties": {
    "diff": {
      "type": "object",
      "properties": {
        "address": {
          "type": "object",
          "properties": {
            "geolocation": {
              "type": "object",
              "properties": {
                "latitude": { "type": "array" },
                "longitude": { "type": "array" }
              },
              "anyOf": [
                { "required": [ "latitude" ] },
                { "required": [ "longitude"] }
              ]
            }
          },
          "required": [ "geolocation" ]
        }
      },
      "required": [ "address" ]
    }
  },
  "required": [ "diff" ]
}
```

{% endtab %}
{% endtabs %}

Once your event schema has been built, post it to the appropriate resthooks endpoint. If you wish to test your filter against a given event once it has been saved, the test endpoint can be used to validate your filter against the specified event payload, which you can take from the *Ping* webhooks function, or by using a real event already being received by your endpoint

{% hint style="warning" %}
When using event filters, it is important to keep in mind that certain events will no longer be sent to you. As the diff is generated for each specific event (rather than being based on the last version you received as a consumer) you will likely encounter scenarios where it is necessary to use the `new` object to understand all changes to a resource since the last time you received an update
{% endhint %}

### Including semi-structured data in webhook events

The Foundations REST APIs allow semi-structured - known to customers as extra fields - data to be optionally included in responses and this data can also now be included in webhook payloads. This can be set up through the [Webhooks management section](https://developers.reapit.cloud/webhooks/manage) of the DeveloperPortal.

When editing a webhook, semi structured fields can be optionally include as part of the configuration. If using this facility, it's likely you will already be aware that you can access these fields, and as with the APIs it's necessary for permission to be granted to these fields before you can use them, and an appropriate error message will be displayed if you attempt to configure a webhook with fields that are not permitted. To include semi-structured fields in webhook events, simply add each field you wish to include and have access to in the appropriate section of the configuration window, and click `Update`

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F5VOwWyUCABNOvZzIVFeG%2FWebhooks-3a.jpg?alt=media&amp;token=0424e533-fd9a-490a-9920-901f5e15fa89" alt=""><figcaption></figcaption></figure>

Event payloads will now contain the selected fields, in the `new`, `old`, and `diff` objects where applicable. Note that when a field is not set in the database, it will not be returned at all which matches the behaviour of the APIs.

{% hint style="info" %}
When a webhook is configured for multiple customers, you must have been granted permission to the semi structured field(s) being configured for all customers. An error will be presented if this requirement is not met. In this scenario, either request access to the field for the additional customers, or consider splitting your webhook into multiple hook configurations
{% endhint %}

### Optional webhook behaviour

By default, webhooks will not be emitted when only the entity's eTag and modified timestamp has changed. If you would prefer to receive notifications in this situation, please use the **Ignore notifications where only the eTag has been modified** toggle option when configuring your webhook

{% hint style="info" %}
**To test your webhook end to end with real data**, use the sandbox database available to you in the Developer Portal. Set up a webhook to listen to 'SBOX' events and make changes to the sandbox using our APIs or Interactive API Explorer.
{% endhint %}

## Managing webhooks using REST API

We also provide a REST API to allow webhooks to be programmatically created for the customer/application that your access token has been issued on behalf of. Please see the swagger documentation for technical details on how to integrate.

## Receiving events

### Example payload

We use a consistent schema to describe any event that we broadcast in a descriptive and self-contained way. The notifications we emit indicate that an **event has happened** - but additionally and where appropriate - we provide details about the actual data change that has occurred. This allows your application to ascertain **granular details about the event** without needing additional API calls.

Below is an example of what a **contacts.modified** webhook event might look like

```
{
  "SendAttempts": 1,
  "eventId": "9e7e4181-6210-49ea-abf5-d5ce16d23647",
  "entityId": "RPT20000029",
  "customerId": "webhook-test",
  "eventTime": "2020-05-13T09:33:16.8811358Z",
  "topicId": "contacts.modified",
  "new": {
    "id": "RPT20000029",
    "created": "2020-05-13T09:32:24Z",
    "modified": "2020-05-13T09:33:10Z",
    "title": "Mr",
    "forename": "John",
    "surname": "Smith",
    "dateOfBirth": null,
    "active": true,
    "marketingConsent": "notAsked",
    "identityCheck": "unchecked",
    "source": null,
    "homePhone": null,
    "workPhone": null,
    "mobilePhone": "07123 456789",
    "email": "john.smith@reapitestates.net",
    "primaryAddress": {
      "type": "primary",
      "buildingName": "",
      "buildingNumber": "12",
      "line1": "High Street",
      "line2": "Clacton-On-Sea",
      "line3": "Essex",
      "line4": "",
      "postcode": "CO15 1AE",
      "countryId": "GB"
    },
    "secondaryAddress": null,
    "workAddress": null,
    "officeIds": ["RPT"],
    "negotiatorIds": ["RPT"],
    "_eTag": "\"4DF107A6EB05D792EEAFDF1432F6E275\""
  },
  "old": {
    "id": "RPT20000029",
    "created": "2020-05-13T09:32:24Z",
    "modified": null,
    "title": "Mr",
    "forename": "John",
    "surname": "Smith",
    "dateOfBirth": null,
    "active": true,
    "marketingConsent": "notAsked",
    "identityCheck": "unchecked",
    "source": null,
    "homePhone": null,
    "workPhone": null,
    "mobilePhone": null,
    "email": "john.smith@reapitestates.net",
    "primaryAddress": {
      "type": "primary",
      "buildingName": "",
      "buildingNumber": "1",
      "line1": "High Street",
      "line2": "Clacton-On-Sea",
      "line3": "Essex",
      "line4": "",
      "postcode": "CO15 1AE",
      "countryId": "GB"
    },
    "secondaryAddress": null,
    "workAddress": null,
    "officeIds": ["RPT"],
    "negotiatorIds": ["RPT"],
    "_eTag": "\"65D680519E9762519D203891A694B85B\""
  },
  "diff": {
    "modified": [null, "2020-05-13T09:33:10Z"],
    "mobilePhone": [null, "07123 456789"],
    "primaryAddress": {
      "buildingNumber": ["1", "12"]
    },
    "_eTag": ["\"65D680519E9762519D203891A694B85B\"", "\"4DF107A6EB05D792EEAFDF1432F6E275\""]
  }
}
```

### Payload schema

The following table outlines the purpose of each property in the payload

| Property       | Description                                                                                                                                                                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SendAttempts` | The number of attempts it took to successfully deliver the message. Please see [failure handling](#failure-handling-and-exponential-backoff) section regarding retry policy with exponential backoff                                                 |
| `eventId`      | A unique identifier for the event. Some events will trigger multiple notifications (for example if the name of a contact changes, you'll also receive a notification for each of their associated roles. These will share the same event identifier) |
| `entityId`     | If applicable, the unique identifier of the entity that the event is associated to. Please note that by itself this is *not* a globally unique identifier. Uniqueness can be achieved by also including the `customerId`                             |
| `customerId`   | The unique identifier of the Reapit customer whom the data event is associated with                                                                                                                                                                  |
| `eventTime`    | The UTC date and time the event was emitted from our Platform                                                                                                                                                                                        |
| `topicId`      | The topic the event is associated with. See the list outlined in the [Subscription topics ](#subscription-topics)section                                                                                                                             |
| `new`          | The new version of the entity, if applicable - this property will be null if a user has deleted or archived the entity.                                                                                                                              |
| `old`          | The old version of the entity, if applicable - this property will be null in the event of a *.created* event.                                                                                                                                        |
| `diff`         | A diff outlining the exact changes between the new/old payloads. The diff is only populated for *.modified* events where both `new`/`old` representations of the entity are available.                                                               |

The content of the `new`, `old`, and `diff` properties in the webhook event payload use the same schema that the respective API endpoints use. For example, if the payload received has a `topicId` of `contacts.modified` then these payload properties will use the same schema as the `GET /contacts` API endpoints

Please note that metadata specific to your app/integration is not currently included in webhook event payloads

### Testing

When you have an endpoint configured, you can test it by using the **Ping** function. This will send a test event with an example payload to the URL stored against the webhook for the selected topic. You will only be able to select topics that are applicable to the webhook being tested.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FMFbcbVMgoMd1fQ0C4pzb%2FWebhook%203.png?alt=media\&token=dd6c7a72-761b-4b58-ad13-3b636f5e26e5)

The user interface will show a success or failure based on the response back from the endpoint. In the event of a success response, you will have received the example payload to the configured endpoint.

We also recommend testing your webhooks using our sandbox environment before applying them to customers.

{% hint style="info" %}
**All events submitted from the Ping function** use example data and will have a `customerId` of 'webhook-test' and an `entityId` of '9e7e4181-6210-49ea-abf5-d5ce16d23647'. Receiving services need to handle this appropriately and not treat the payload as production event
{% endhint %}

### Failure handling and exponential backoff

As with any integrated system, there's always a possibility of the endpoint we try to send a webhook notification to being unavailable at certain periods. For this reason a retry policy with exponential backoff has been built so that small periods of downtime do not result in messages not being delivered to you.

Where we fail to deliver a webhook on the first attempt, we will retry up to 5 times at the following intervals (6 delivery attempts in total):

| Delivery attempt | Delivery delay (seconds/minutes)                                                                                              |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| 2                | At least 60s (1m) after the first delivery attempt                                                                            |
| 3                | At least 120s (2m) after the second delivery attempt                                                                          |
| 4                | At least 300s (5m) after the third delivery attempt                                                                           |
| 5                | At least 600s (10m) after the fourth delivery attempt                                                                         |
| 6                | At least 900s (15m) after the fifth delivery attempt. No more attempts to deliver the message will be made after this attempt |

The number of attempts it took to deliver the message is available in the payload. See the [Example payload](#example-payload) for more information.

Please note that we will not retry to send messages that were not delivered on the first attempt in the following scenarios:

* Where the webhook event is associated to Sandbox data
* Where the response code we received from your configured endpoint was 4XX. This is indicative of a misconfigured webhook or authentication problem on the target system

It is considered good practice to process webhook events asynchronously, meaning your endpoint should respond quickly (typically with a 202 Accepted response) *before* invoking any processing logic. If a response from your endpoint is not received in a timely fashion (typically around 10 seconds), the event will go into the retry queue as described above. This can inflate webhook consumption which is included in monthly invoicing and so it is in your best interest to adhere to this practice. The 10 second limit is dynamic based on throughput from our system but will not drop below 5 seconds.

### Webhook source IP addresses (allowlisting)

When Reapit dispatches webhooks, requests originate from the following public source IP addresses:

* `18.133.192.77`
* `18.133.96.95`
* `18.132.113.124`

If your infrastructure uses IP allowlisting (for example, WAF, firewall, API gateway, or reverse proxy rules), permit inbound traffic from all of the above addresses to ensure reliable webhook delivery.

#### Operational note

These are static Elastic IP addresses used for webhook egress in `eu-west-2` (across multiple availability zones).\
Future changes to Reapit IP addresses will be documented here and communicated in advance where possible.

## Additional information

* Events are generated in near real-time and though extremely unlikely, we do not guarantee that you will only get a single notification for an event.
* We do not guarantee that webhooks will be sent in the exact order that the events occurred. You can use the `eventTime` to determine when each event occurred.
* Webhooks originated requests contribute to developer analytics and billing in the same way as regular API requests do


# GraphQL

GraphQL Implementation of the Foundations API

The Reapit GraphQL service is a GraphQL implementation of the Foundations API. It is a proxy service that sits on top of the Reapit Foundations Platform API which means both share the same domain model. The service exists as a convenience for developers to build web applications quickly and with minimal boilerplate, rather than an alternative standalone platform.

{% hint style="success" %}
Whilst the service is beta, because the aim of the project is to be schema compliant with the REST platform API, you can rely on no breaking changes to the schema itself
{% endhint %}

We have been using the service internally in production at Reapit - it powers the Geo Diary App, which is currently the most installed Reapit AppMarket application. Having completed this initial internal Beta, we are now excited to release it publicly for the first time.

### Basic Usage & Authentication

The GraphQL production  endpoint is `https://graphql.reapit.cloud/graphql`

Visiting this Url in your browser will load the GraphQL [playground](https://www.apollographql.com/docs/apollo-server/testing/graphql-playground/) where you can experiment with the service. If you are not familiar with Playground, it is an API explorer, like Swagger, but for GraphQL.

{% hint style="info" %}
You will need to authenticate any request made to the GraphQL service using Reapit Connect. Currently we only support the Authorization Code flow, not machine-to-machine Client Credentials. The scopes for the clientId that generates your tokens must map 1:1 to the downstream platform endpoints queries by GraphQL.
{% endhint %}

There are two required headers in the service as per below, you will need to obtain your `accessToken` and `idToken` from your Reapit Connect session as normal. See the [developer portal](/developer-portal#5-get-your-client-id), [Reapit Connect](/api/reapit-connect) and [Connect Session](/app-development/connect-session) sections of these docs for details on how to obtain these tokens.

```javascript
{
  "authorization": "<<idToken>>",
  "reapit-connect-token": "<<accessToken>>"
}
```

These headers need to be added to the http headers section of the playground for you to interact with the service, or to your GraphQL client of choice's fetcher. Internally we use Apollo Client to interact with the service - [see documentation on this here](https://www.apollographql.com/docs/tutorial/client/).

{% hint style="warning" %}
Because an idToken is required for authentication, the GraphQL service is not suitable for developers using the Client Credentials OAuth flow.
{% endhint %}

### Errors

Because the service is a platform proxy, it is very likely that errors from the GraphQL service are downstream platform issues rather than errors thrown by the service itself. For downstream errors, the service will return a 200 with an errors object in the payload. You should inspect this errors list for details of any failures downstream, even if the GraphQL service itself was able to respond correctly.

If the service itself throws an exception, it will be in the 4xx and 5xx scopes as normal. 401 errors are the most common - these are thrown by our API gateway owing to an invalid or missing `idToken`. See the basic usage section on how to set up your headers above.&#x20;

### Billing

No additional charges are applied for using the GraphQL service over the Foundations REST API. Since the service is a proxy, your consumption charges will be on the basis of the downstream API calls made by GraphQL service to the corresponding REST services. The normal fair usage and consumption rules apply.

### Known Limitations

* The service is already working in production with live customers, powering the Reapit Geo Diary app however, naturally with beta services there may be some issues. If you find a problem with the GraphQL service, please [open an issue here](https://github.com/reapit/foundations/issues/new?assignees=\&labels=bug%2C+needs-triage%2C+graphql-server\&template=bug_report.md\&title=) and we will look at it as soon as possible.
* The objective of the project is to offer the an identical schema to the Foundations API, with no extension, modification or deviation. Objects returned from the service should map 1:1 to those seen in the [developer portal swagger document](https://developers.reapit.cloud/swagger).  There may however be some delay between when a property is updated in the main platform. If you find any inconsistencies between the platform API and the service, again please report as an issue - it is likely that the platform has updated and the service is yet to follow.
* The service is lacking two services that exist in the Platform Schema - Meta Data and Meta Data Schema. Owing to the strongly typed nature of GraphQL it is not possible to query arbitrary JSON structures that vary from developer to developer. This is likely to remain a limitation of the service going forward.


# Reapit Connect

How to manage authentication of Reapit users with our hosted identity solution

##

{% hint style="warning" %}
From August 2024, it is essential that early Platform integrators ensure their identity token validation routines are updated. Please refer to [Using identity tokens](#using-identity-tokens) for more information
{% endhint %}

## Overview

Reapit Connect is our hosted identity solution designed to allow applications to securely authenticate Reapit users against a single, trusted identity. Backed by our [OpenID Connect](https://openid.net/connect/faq/) compliant system, it is quick and easy to build applications that adhere to best security practices and extend an excellent experience to your users.

**Building your application with Reapit Connect is our recommended way to interact with our Platform.**

## Why use Reapit Connect

### Simplicity

Reapit Connect removes the overhead of having to build and maintain a user credential directory for your app. Instead, users can be securely authenticated against a single, trusted Reapit identity.

### **Security**

Our identity provision is an implementation of OpenId Connect, the defacto industry standard for authentication and authorisation for web and mobile applications. Simply put, you don't need to worry about securely capturing or storing user credentials - we do that part for you.

### Single sign on

Reapit Connect supports single sign on (SSO) to allow authenticated sessions to be shared between any application using Reapit Connect to manage its authentication. The experience of interacting with your application is streamlined as users aren't re-prompted for their credentials.

### Cross platform

You can use Reapit Connect to authenticate users regardless of your front or back end technologies. Reapit Connect is agnostic of technology and integration is as simple as a redirect to our hosted login screen and a subsequent REST API call.

### Trust

Your users will be presented with a unified login screen from a brand they already know and trust. They will receive the same user experience as they do from other Reapit applications and of those that exist in our AppMarket.

## AppMarket integration

### Registering your application

Registering your app in our AppMarket is the first step for it to be able to interact with Reapit customer data.

Our [application submission page](https://marketplace.reapit.cloud/developer/submit-app) will capture information about your application, including the details required for integration with Reapit Connect.

* Select **Authenticate with Reapit Connect** as your required authentication flow *\*\**
* Provide one or more **redirect URLs** and a **logout URL** to define the acceptable URLs that Reapit Connect is permitted to redirect back to after a successful authentication or logout

Once you have successfully registered, you will be issued with a client id. You can obtain this by clicking your app in the [My Apps](https://marketplace.reapit.cloud/developer/apps) area of our developer portal.

### Customer installation

In order for Reapit Connect to authenticate your application on a users behalf, the user must belong to a Reapit customer that has opted to allow your application access to their data.

Customer administrators are able to control your applications access by choosing to install from our AppMarket. As part of this process, they will grant your application with any permissions (scopes) it requires to interact with Foundations API endpoints.

{% hint style="info" %}
**You can test Reapit Connect** with our [sandbox environment](/api/api-documentation#sandbox-mode) which does not require the customer installation step. Simply provide your developer portal credentials when Reapit Connect prompts for a username and password.
{% endhint %}

## Authentication flow

OAuth 2.0 is an authorization framework that we use to allow a user to grant limited access to resources in our Foundations platform without having to expose their credentials.

We use the [Authorization Code Grant](https://developer.okta.com/blog/2018/04/10/oauth-authorization-code-grant-type) *\*\**&#x66;low to authenticate, which is broken down into the following steps.

* Your application redirects the user to our Reapit Connect in the browser
* Reapit Connect presents the user with a login screen to capture their credentials
* Reapit Connect will direct the browser back to your application with an authorization code in the query string
* Your application exchanges the authorization code for tokens with a REST API call &#x20;

### Direct user to Reapit Connect

To initiate a login, your application should redirect users to our authorize endpoint:

`https://connect.reapit.cloud/authorize?response_type=code&client_id=<client id>&redirect_uri=<redirect url>&state=<state>`

| Parameter       | Description                                                                                                                                        |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `response_type` | The type of authentication flow that Reapit Connect should initiate. At present, this must be set to **code**                                      |
| `client_id`     | The unique client id that was issued to your application after registration                                                                        |
| `redirect_uri`  | The URL to redirect back to once the user has been authenticated. This must **exactly match** one of the URL's you provide during app registration |
| `state`         | Optional parameter to pass state to our hosted login screen. Upon successful login, it will be returned back to you.                               |

### Present login form

The user will be presented with a Reapit branded login screen where they are required to input their email and continue. At the next step, they can also initiate password recovery for their Reapit identity from this form.

This step will be automatically skipped if the user has an authenticated session with Reapit Connect. The user will immediately be redirected back to your app.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FEvDo8m5fRYahbvWZGbAp%2Fimage.png?alt=media&amp;token=12d2d9f5-f789-4629-a786-08b1ed425f42" alt=""><figcaption></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FIJO8rjt9uA2fjswtnehC%2Fimage.png?alt=media&amp;token=c10c8c49-1081-4e3c-9376-34c560e40a87" alt=""><figcaption></figcaption></figure>

### Redirect back to your app

If the user provides valid credentials, Reapit Connect will redirect back to your application using the `redirect_uri` that was provided when [directing the user to Reapit Connect](/api/reapit-connect#direct-user-to-reapit-connect).

A `code` parameter will be appended to the redirected URL, as well as any `state` you passed through to the authorize endpoint.

`https://your_redirect_url?code=<code>&state=<state>`

{% hint style="success" %}
**Reapit Connect** will only redirect to URLs that were added during app registration. This is a security measure to prevent malicious users attempting to impersonate your application.
{% endhint %}

### Exchange code for tokens

Once your application has successfully guided the user through the OAuth flow, you can extract the authorization code from the redirected URL. You are then able to use this code to exchange for JWT tokens for proof of authentication and access for Foundations resources. You can only attempt to exchange authorization codes once and they will expire 10 minutes after they have been issued.

To make the exchange, send a `POST` request to the endpoint below with Content-type set to `application/x-www-form-urlencoded`:

`https://connect.reapit.cloud/token`

| Request payload | Description                                                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `client_id`     | The unique client id that was issued to your application after registration                                                     |
| `code`          | The authorization code returned to you in URL                                                                                   |
| `grant_type`    | Must be set to `authorization_code`                                                                                             |
| `redirect_uri`  | The redirect URL that was submitted when [directing user to Reapit Connect ](/api/reapit-connect#direct-user-to-reapit-connect) |

If your request is properly formed and valid, you'll receive a response similar to below.

```
HTTP/1.1 200 OK
Content-Type: application/json

{ 
 "access_token" : "eyJz9sdfsdfsdfsd", 
 "refresh_token" : "dn43ud8uj32nk2je", 
 "id_token" : "dmcxd329ujdmkemkd349r",
 "token_type" : "Bearer", 
 "expires_in" : 3600
}
```

## Making authenticated requests

If the user successfully logged in and your application performed the code exchange, you will receive a JSON payload containing a series of tamper proof [JWT tokens](https://tools.ietf.org/html/rfc7519):

| Response payload | Description                                                |
| ---------------- | ---------------------------------------------------------- |
| `access_token`   | Token to grant access to protected Foundations resources   |
| `id_token`       | Token containing claims about the users identity.          |
| `refresh_token`  | Token that can be issued to get a new id and access token. |
| `expires_in`     | The number of seconds that the access token is valid for   |
| `token_type`     | The type of tokens issued. Will always be set to `bearer`  |

### Using access tokens

Access tokens (also known as bearer tokens) are designed to provide your application with access to protected resources on the users behalf.

You can access Foundations API endpoints by including the access token as an `Authorization` header in all requests your application issues, subject to the scopes that your application requested during registration.

### Using identity tokens

Identity tokens are intended to provide proof of authentication with Reapit Connect. Your application should decode and [validate ](https://connect2id.com/blog/how-to-validate-an-openid-connect-id-token)the id token that it has been issued. There are a variety of [third party libraries](https://jwt.io/#libraries-io) to help accomplish this and **the token should not be trusted until validated**.

When validating your id token, you will need the production well known public keys - these are publicly accessible online. You should build the URL to the published JWKs using the token issuer, but only *after* validating the issuer of the token. Valid issuers of Reapit Connect tokens are:

* <https://connect.reapit.cloud>
* <https://cognito-idp.eu-west-2.amazonaws.com/${cognitoPoolId}>

{% hint style="warning" %}
On or after 1st August 2024 tokens will begin to be issued by <https://connect.reapit.cloud>. If you integrated with our Platform before May 2024, you may have a single hard coded URL in your token validation routine, which will be <https://cognito-idp.eu-west-2.amazonaws.com/eu-west-2_eQ7dreNzJ/.well-known/jwks.json>.
{% endhint %}

Once you have validated the issuer, you can then go on to fetch the JWKs and continue with token validation. An example of how you might do this is shown below

```typescript
import decode from 'jwt-decode'
const decodedToken = decode(token)

const issuer = decodedToken.iss;

const issuerWhitelist = [`https://cognito-idp.eu-west-2.amazonaws.com/${cognitoPoolId}`, 'https://connect.reapit.cloud/']

if (!issuerWhitelist.includes(issuer)) {
  // Issuer is not Reapit Connect, token is invalid so no need to fetch the well known keys.
  throw new Error('invalid issuer')
}

const wellKnownKeys = const url = `${issuer}/.well-known/jwks.json`;

// Fetch the well known keys then continue to validate token as normal
// ...
```

Our [Connect Session](/app-development/connect-session) JS module decodes and verifies the id token for you (if you are using a client side application). We have patched all versions of the Connect Session library back to v2.x. Ideally, you should upgrade to the latest version of the library however if you encounter compatibility issues after May 2024, upgrading to the latest version of your current major version (ie v2.3.1 if running v2.3.0) will suffice,

Once decoded, your application can inspect the claims that the id token includes. Claims provide information about the users identity such as the customer they work for, their email address and name which your application can make use of.

You can also issue a `GET` request to the following endpoint to get information on the user. Be sure to include your access token:

`https://connect.reapit.cloud/oauth2/userInfo`

### Using refresh tokens

Access tokens issued from Reapit Connect will expire after 60 minutes. Refresh tokens provide your application with a means of retrieving a new set of tokens without requiring an interaction from the user.&#x20;

Applications using the authorisation code grant (typically client side applications) now have refresh token rotation enabled. This means a refresh tokens can only be used once, and a fresh refresh token will be returned from the token endpoint each time a fresh access token is requested. The connect-session library handles this as part of the `ReapitConnectBrowserSession` class. If your application manages it's own Reapit Connect session, ensure logic is in place to update the session's refresh token when using this endpoint.

To use a refresh token, issue a `POST` request to the endpoint below with Content-type set to `application/x-www-form-urlencoded`:

`https://connect.reapit.cloud/token`

| Request payload | Description                                                                 |
| --------------- | --------------------------------------------------------------------------- |
| `client_id`     | The unique client id that was issued to your application after registration |
| `refresh_token` | The refresh token                                                           |
| `grant_type`    | Must be set to `refresh_token`                                              |

{% hint style="warning" %}
For recommendations on how to safely store and interact with tokens, please see our web integration module[ ](/app-development/web#cognito-auth)[Connect Session](/app-development/connect-session)
{% endhint %}


# Desktop API

An API to interact between the Reapit AgencyCloud CRM and a AppMarket Web Application

{% hint style="info" %}
To obtain a copy of Reapit's AgencyCloud CRM (Developer Edition), please visit the '[Desktop](https://developers.reapit.cloud/desktop)' page within the Developers Portal. NOTE Reapit does not provide technical support for Developer Edition.
{% endhint %}

{% hint style="warning" %}
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.&#x20;
{% endhint %}

### Overview

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.

### Debugging your App

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. &#x20;

![Remote debugging button on the app ribbon bar](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MDEtxeIjMu7cYcdvYRz%2F-MDEuQXECoDKv5A8g1N7%2Fimage.png?alt=media\&token=e3bfb722-065e-45cc-87d6-e29716f51fff)

Clicking this button will launch a separate window which hosts the developer tools:

![Remote debugging via the developer tools window](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MDEtxeIjMu7cYcdvYRz%2F-MDEulQxKGF0GB6dJxQR%2Fimage.png?alt=media\&token=61ec9559-e7c9-497c-88c8-85fb1a5a0657)

### URL Scheme

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.

### Format

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.

## Property

### Load Property

Opens the property edit screen for the property with specified id

```
agencycloud://properties/{id}
```

### Perform Matching

Performs a property to applicant match for the applicant with specified id

```
agencycloud://properties/{id}/match
```

### Load Journal

Opens the journal screen for the specified property

```
agencycloud://properties/{id}/journal
```

### Load Offers

Opens the offers screen for the specified property

```
agencycloud://properties/{id}/offers
```

### Property Search

Opens advanced search screen in property mode and runs a search with provided parameters. At least one parameter is required.

```
agencycloud://properties?address=MK43&mode=s
```

| 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 | <p>The marketing mode of the properties to search for:</p><ul><li>s or sales</li><li>l or lettings</li></ul>              | 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       |

## Applicants

### Load Applicant

Opens the applicant edit screen for the applicant with specified id

```
agencycloud://applicants/{id}
```

### Perform Matching

Performs a applicant to applicant match for the applicant with specified id

```
agencycloud://applicants/{id}/match
```

### Load Journal

Opens the journal screen for the specified applicant

```
agencycloud://applicants/{id}/journal
```

### Applicant Search

Opens advanced search screen in applicant mode and runs a search with provided parameters. At least one parameter is required.

```
agencycloud://applicants?name=smith&mode=lettings
```

| 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 | <p>The marketing mode of the properties to search for:</p><ul><li>s or sales</li><li>l or lettings</li></ul>              | 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       |

## Appointments

### Load Diary

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.

```
agencycloud://appointments?dateFrom=2019-12-25&dateTo=2019-12-26
```

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

## Contacts

### Contact Search

Opens advanced search screen in contact mode and runs a search with provided parameters. At least one parameter is required.

```
agencycloud://contacts?name=smith
```

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

### Load Contact

Opens the contact edit screen for the contact with specified id

```
agencycloud://contacts/{id}
```

### Load Journal

Opens the journal screen for the specified contact

```
agencycloud://contacts/{id}/journal
```

## Works Orders

### Load Works Orders

Opens the specific works order screen

```
agencycloud://worksorders/{id} 
```

### Search Works Order

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.

```
agencycloud://worksorders?address={abc}&supplier={def}&status={ghi}&desc={jkl}
```

## Process

From version 12.122.0 there will also be a resource called **process** which will have two sub processes:

* webpage
* email

### Webpage

This will allow you to launch a webpage in the local default browser.  An example would be:

```
agencycloud://process/webpage?url=https://www.reapit.com
```

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.

### E-mail

This will allow you to launch the users default e-mail client and send to an address.  An example would be:

```
agencycloud://process/email?address=help@reapit.com
```

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.

## AgencyCloud Interaction API

### Overview

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.

### Desktop Types

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&#x20;
* Outbound - Landline
* Outbound - Mobile&#x20;

From version 12.142.0 the following will also be available:

* Match Output&#x20;

From version 12.152.3 the following will also be available:

* Diary

From version 12.153+ the following will also be available:&#x20;

* Pre Tenancy Checks&#x20;
* 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

## Types

### Property

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:

```
{ "prpCode": "ABC200123" }
```

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

![Property apps launch point](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M4DE_60VGu3NYFgwNin%2F-M4DJJDU4RDc7ogaFUPN%2Fimage.png?alt=media\&token=46a88e1d-8164-4f2b-93c5-8beca7a797a9)

### Applicant

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:

```
{ "appCode": "ABC200123" }
```

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

![Applicant apps launch point](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M4DE_60VGu3NYFgwNin%2F-M4DJorWu1LtqoW-bgul%2Fimage.png?alt=media\&token=1e1e727f-e715-43f1-82c5-97deec814dd5)

### Id Check

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:

```
{ "cntCode": "ABC20012345" }
```

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

![Id Check button in AgencyCloud](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M4DE_60VGu3NYFgwNin%2F-M4DHB5cyEv3PyS9MbdK%2Fimage.png?alt=media\&token=c0a82650-ef3e-42c0-b039-aec02cd0d3ad)

### Property Marketing Information

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:

```
{ "prpCode": "ABC201023" }
```

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

![Property Marketing app launch point ](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M7ITAgemNSIJAvsXNLF%2F-M7ITa8EKgnlNzw618wA%2Fimage.png?alt=media\&token=6a89c3b7-bc11-4a71-869b-16c472c66e3a)

### Vendor Marketing Report

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:

```
{ "prpCode": "ABC201023" }
```

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

![Vendor Marketing App launch point](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M7ITAgemNSIJAvsXNLF%2F-M7IUzueSycbiA04CYS-%2Fimage.png?alt=media\&token=5df34256-a079-44d8-9446-92c1a4e8cea1)

### Property Detail Generation

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:

```
{ "prpCode": "ABC201023" }
```

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

![Details generator app launch point ](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M4DE_60VGu3NYFgwNin%2F-M4DNlZKHJebKFlwnaP7%2Fimage.png?alt=media\&token=bde95321-9bef-4cab-af87-3258068a0882)

### Applicant Export

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:

```
{ "appCode": "ABC201023" }
```

<table data-header-hidden><thead><tr><th>Parameter</th><th width="403">Type</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Required</td></tr><tr><td>appCode</td><td>string</td><td>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).</td><td>Yes</td></tr></tbody></table>

An application of this type would be triggered in two ways from AgencyCloud:

1. Upon first save of the applicant
2. As an option when clicking Print on the applicant screen:

![Applicant Export launch point](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M7ITAgemNSIJAvsXNLF%2F-M7IVtWJZ3_8m7rPJAj3%2Fimage.png?alt=media\&token=98365950-0376-4b1e-a379-c0cb5ec2c155)

### Landlord

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:

```
{ "lldCode": "ABC200123" }
```

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

![Apps button on landlord screen (when lettings accounts is turned off)](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MC78Bifs4xYU4a08yqo%2F-MC7BIsDOQm_sQUKZ2NW%2Fimage.png?alt=media\&token=7758e187-b6a5-409d-a065-273401762cb5)

![Apps button on landlord screen (when lettings accounts is turned on) ](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MC78Bifs4xYU4a08yqo%2F-MC7BYvYrPyzzwoMvYPX%2Fimage.png?alt=media\&token=0d1e16f0-0a98-427a-97ce-0e92698d09e5)

### Contact

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:

```
{ "cntCode": "ABC20012345" }
```

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

![Apps button on the contact screen](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MC78Bifs4xYU4a08yqo%2F-MC7C1L37VXMf8SDKJ3Y%2Fimage.png?alt=media\&token=d3368281-2e3b-4d78-9d5c-4bf458e9e7af)

### Company

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:

```
{ "cmpCode": "ABC20012345" }
```

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

![Apps button on the company screen](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MC78Bifs4xYU4a08yqo%2F-MC7DV4iDyv6w-4cTg4J%2Fimage.png?alt=media\&token=7899f89d-e06c-412f-8b9b-345a95a0ee35)

### Tenancy

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:

```
{ "tenCode": "ABC200123" }
```

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

![Apps button on tenancy screen](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MC78Bifs4xYU4a08yqo%2F-MC7FMnpuuKPqmwh8fKx%2Fimage.png?alt=media\&token=d347dc31-6057-4843-9228-f43b1d07fb47)

### Offer

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:

```
{ "offerCode": "ABC200123" }
```

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

![Apps button on the offer screen](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MC78Bifs4xYU4a08yqo%2F-MC7Ezw1RTviaZtAL--l%2Fimage.png?alt=media\&token=30209bfe-348c-408e-9696-015b96f70094)

### Sales Progression

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:

```
{ "prpCode": "ABC201023" }
```

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

![Sales progression button on the offers screen](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MC78Bifs4xYU4a08yqo%2F-MC7GWPX5eHFA9AatSGq%2Fimage.png?alt=media\&token=f1a03e55-1520-4d94-8fda-66d428e41b42)

### Chain Management

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:

```
{ "prpCode": "ABC201023" }
```

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

![Chain button on the offers screen](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MC78Bifs4xYU4a08yqo%2F-MC7GeP22Bw12yGP-3-A%2Fimage.png?alt=media\&token=d653cc55-c60f-4459-ac81-ab119c33ccdf)

### Match Output

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:

```
'{"NegCode":"RTR","Matches":[{"OutputType":"PrpToAppMatch","SourceCode":"BCK160024","Results":["RPT210019"]}]}'
```

| 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:&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FILhfz57fQezEnDxWjhB5%2FMatchOutput.jpg?alt=media\&token=500a94bf-129d-4a02-adac-f0b6a36c7518)

### Diary

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'}

```
{ "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      |

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FM7KaTo4UXF5b4CViwtTK%2FDiaryAPI.png?alt=media&amp;token=514b0472-bb6f-4f74-954e-5d6188d28940" alt=""><figcaption></figcaption></figure>

### Pre Tenancy Checks

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:

```
{ "tenCode": "ABC200123" }
```

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

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FR2LaeeRbkvZm1mnRVHgi%2FPTenancyCheck.jpg?alt=media&amp;token=fe0eeedc-f6f6-4958-9b4e-27b9416c146a" alt=""><figcaption></figcaption></figure>

### **Works Orders**

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:&#x20;

```
{ "prpCode": "ABC201023" }
```

<table data-header-hidden><thead><tr><th>Parameter</th><th width="280">Type</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Required</td></tr><tr><td>prpCode</td><td>string</td><td>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).</td><td>Yes</td></tr></tbody></table>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FQdr1YCyiXXXA0UdB2nTw%2FWO1.png?alt=media&amp;token=4f8ac047-91ad-4fca-a2dd-2c6f449e3597" alt=""><figcaption></figcaption></figure>

You can also launch the app from an existing works order and the globals dictionary will contain the below key when launched by AgencyCloud:

```
{woCode: 'MKT22000195'}
```

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

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FgmTbhTJ8tMk7cGg1K6YN%2FWO2.png?alt=media&amp;token=6f8a2b62-eaa7-4fbb-ab1a-a0d50b2bab6d" alt=""><figcaption></figcaption></figure>

### Referral

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'}`

&#x20;

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

&#x20;

&#x20;

#### Setup

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.

#### Step 1 - Installation:

The agent should first install your app from the AppMarket and after installation, restart AgencyCloud

#### Step 2 – Setting up the Referral in AgencyCloud:

Open the ‘Setup Referrals/Leads’ section under configuration:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FAtI3XM1DqGFYB54sgKYV%2FRT01.png?alt=media&amp;token=8358f2d4-7c22-4fec-a22a-b0fcc9fce986" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F4A0H2nG5Wzo9m7hWWdd4%2FRT02.png?alt=media&amp;token=f14426dc-f475-4d00-ab5b-e19341f57b3e" alt=""><figcaption></figcaption></figure>

Once the setup is saved, the new referral option should appear on the chosen screen. For example, on the Applicant screen 'Referral Example':

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FdnZl2h7sZa9BWgVYF8nG%2FRT03.png?alt=media&amp;token=6e13c9d0-7991-463b-b59e-867d8cb304df" alt=""><figcaption></figcaption></figure>

#### Process

When a user clicks on the  referral, it will prompt them to ‘Create New Referral’:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FACEYRR4jet7VbssYa6Ih%2FRT04.png?alt=media&amp;token=02d52dab-0acd-4684-9097-348f8743507f" alt=""><figcaption></figcaption></figure>

&#x20;

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…’:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FiAlvqSkorTmsbJBP6jsn%2FRT05.png?alt=media&amp;token=69319a17-319e-4da4-9842-3f174d7fe38f" alt=""><figcaption></figcaption></figure>

### Renewal Negotiation Check

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:

```
{ "renewalCode": "ABC200123" }
```

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

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FCvrcBGcvyK43VXeuAMpk%2FRenewalChecks.jpg?alt=media&amp;token=1db6259a-4ae0-4228-8ac8-9fe40a45fbcc" alt=""><figcaption><p>'Checks' section on a Renewal Negotiation in AgencyCloud</p></figcaption></figure>

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.

### Property Images

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:&#x20;

The below key when launched by AgencyCloud:&#x20;

```
{ "prpCode": "ABC201023" }
```

<table data-header-hidden><thead><tr><th>Parameter</th><th width="280">Type</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Required</td></tr><tr><td>prpCode</td><td>string</td><td>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).</td><td>Yes</td></tr></tbody></table>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F0Jxyge7u2ZGUqy2u5XE9%2FProperty%20Image.jpg?alt=media&amp;token=edea2197-a872-461c-9d5d-f561a27a331c" alt=""><figcaption><p>'Apps' option on the Property Images screen in Agency Cloud</p></figcaption></figure>

### **Property Licensing**

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:&#x20;

```
{ "prpCode": "ABC201023" }
```

<table data-header-hidden><thead><tr><th>Parameter</th><th width="280">Type</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td>Parameter</td><td>Type</td><td>Description</td><td>Required</td></tr><tr><td>prpCode</td><td>string</td><td>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).</td><td>Yes</td></tr></tbody></table>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FdXQf1VrkuuE8JahInWLI%2FLicensing.jpg?alt=media&amp;token=b032a596-ad77-4562-9a15-97963a582106" alt=""><figcaption><p>Licensing optin in AgencyCloud</p></figcaption></figure>


# Notifications

Real time event delivery to Reapit products from your applications

The Notifications API allows developers running apps with the `notifications.*.write` scopes to push certain events back through our Platform for delivery to users of Reapit products in real-time. For the beta programme, the only supported scope is`notifications.telephony.write` - the purpose of this mechanism is primarily to replace legacy TAPI support in the AgencyCloud CRM, but there are plans to expand it's use cases in the future.

### How it works

When a developer pushes an event through the Notifications API, it flows through a pipeline that understands where that event should be delivered. When a user logs into a Reapit product, a real-time connection is opened to the Notifications backend which allows bi-directional real-time communication. The events are pushed through these channels and handled by each of the Reapit products independently.

The API itself that is consumed by developers uses an envelope and message (payload) approach to allow the JSON contract to remain fluid so that different event types can be supported. It's important that anybody utilising the endpoint understands the different notification types and how that affects the payload that the API will expect. If the payload is not as expected, API validation routines will reject the event.

### What is supported

The beta programme allows third party telephony providers to push telephony events through to end users of Reapit products. This enables invocation of certain pieces of product specific functionality, such as screen popping when a new call comes in directly inside AgencyCloud.

### Notification payload

{% hint style="warning" %}
Always refer to the Swagger documentation published in the Reapit DeveloperPortal for the most up to date JSON contracts
{% endhint %}

The payload pushed to `POST /notifications` can be thought of as a letter. It has an envelope - which has some basic information about the type of content and where it should be delivered - and a payload, the actual message.

```json
{
  "type": "telephony",
  "subType": "missedCall",
  "products": [
    "AgencyCloud"
  ],
  "targets": {
    "negotiatorId": [
      "ADV"
    ]
  },
  "payload": {}
}
```

The combination of `type` and `subType` tells the system what kind of `payload` to expect.  The incoming data will be validated to ensure the expected payload has been provided, otherwise a validation error will be returned to the caller.

The `targets` object allows the caller to specify where the event should be sent to. Currently this supports one or more `negotiatorId` values. When multiple targets are provided, the system uses a fan-out mechanism to distribute the same event to each recipient. To be able to deliver notifications correctly, the app will need to understand and contain mappings back to users in Reapit products. To do this, request the `negotiators.read` scope, and use the `GET /negotiators` endpoint to fetch user information.

### Notification Types

The following notification types are currently supported. Please note that examples will eventually be available on our Swagger documentation which will supersede this page, however an update to Open API 3 is required before this can be supported

In all payloads, the `id` property can optionally be used to correlate chained events from the source system. For example, the `id` for an `incomingCall` and `answeredCall` event could be the same value to notify our system that the two events are related.

<table><thead><tr><th width="131">Type</th><th width="147">SubType</th><th>Payload Example</th><th>Usage Notes</th></tr></thead><tbody><tr><td>telephony</td><td>incomingCall</td><td>{ <br>    "id": "ax2uyio8p",<br>    "created": "2023-11-01T10:28:00",<br>    "callerId": "07123 456789", <br>    "destinationId": "01234 567890", <br>    "huntGroup": false <br>}</td><td>Providing the <code>huntGroup</code> flag allows some Reapit products to alter how the incoming notification is displayed, however the field is optional</td></tr><tr><td>telephony</td><td>answeredCall</td><td>{ <br>   "id": "ax2uyio8p", <br>   "created": "2023-11-01T10:28:00",<br>    "callerId": "07123 456789", <br>    "destinationId": "01234 567890", <br>    "huntGroup": false, <br>    "answeredById": "TST" <br>}</td><td>Providing the <code>answeredById</code> property is optional, however when a call is delivered to a hunt group, it allows some Reapit products to adjust how notifications are display when one user from the group answers the call. The <code>answeredById</code> should be a valid negotiator id</td></tr><tr><td>telephony</td><td>endedCall</td><td>{ <br>    "id": "ax2uyio8p", <br>    "created": "2023-11-01T10:28:00", <br>    "callerId": "07123 456789", <br>    "destinationId": "01234 567890", <br>    "huntGroup": false, <br>    "answeredById": "TST" <br>}</td><td></td></tr><tr><td>telephony</td><td>missedCall</td><td>{ <br>    "id": "ax2uyio8p", <br>    "created": "2023-11-01T10:28:00", <br>    "callerId": "07123 456789", <br>    "destinationId": "01234 567890", <br>    "huntGroup": false <br>}</td><td>Missed calls are not delivered in real-time and are instead polled by our products</td></tr></tbody></table>

### Testing

To test the Notifications API in our sandbox environment, you’ll need to have a active Developer Edition subscription (please [click here](https://developers.reapit.cloud/desktop) to subscribe) and a dedicated negotiator ID.

Once you have a Developer Edition subscription, please [click here](mailto:partners@reapit.com?subject=Notifications%20API%20Testing\&body=Please%20provide%20the%20email%20addresses%20below%20you%20wish%20to%20use%20for%20testing%20the%20Notifications%20API%20in%20our%20sandbox%20environment.%20We%20will%20then%20create%20dedicated%20negotiator%20ID's%20for%20each%20email%20and%20confirm%20when%20completed.%20%20) to email the team and include the email addresses you want to use for testing. We will reply and confirm via email, the dedicated negotiator ID’s.

For notifications to display within Reapit for a customer, it requires configuration to be enabled with the Reapit CRM. Please ask the customer to log a ticket with support [here](https://reapitsupport.refined.site/login), requesting notifications are enabled.

### Enabling notifications

Reapit clients must complete a [Standard Configuration Request](https://reapitsupport.refined.site/portal/1?createRequest=true\&portalId=1\&requestTypeId=87) before notifications can be configured in their system. Before the configuration request is processed, notifications will not appear.

Configuration requests can take up to 3 working days to process.

Company level configuration is best practice. When notifications are enabled all TAPI functionality will stop.

### Click-to-dial settings

Click-to-dial is a configurable option in the CRM that must be requested.&#x20;

Enabling notifications and click-to-dial configuration requests can be made simultaneously by clients using the Standard Configuration Request.

The desired app must be set as the default `URL: Tel protocol`  on the agent's device to launch the app when a telephone number is dialled in the CRM.


# Developer Portal

A step-by-step guide to getting started in the developer portal

We want getting started with the Developer Portal to be as frictionless as possible. There is a lot of detail in the documentation for advanced concepts but to get started in as little as 5 mins with an authenticated AppMarket app, you just need to follow these steps:

### 1. Login to the Portal

You will receive an email with a link to the developer portal and temporary login credentials. The app will redirect you to the [Reapit Connect](/api/reapit-connect) login screen and then back to the authenticated portal.&#x20;

The first screen you will see is a the 'About Foundations' page. You will only see this at the first login:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FFyaSIuorXx8Gx5kOhQts%2Fimage.png?alt=media&amp;token=6e7b57c5-d3fe-41b8-99ed-c3996e23441d" alt=""><figcaption></figcaption></figure>

Also on this page you will have the option to 'View Docs' and to 'Create App'.&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FOzAp1wMhQIaHyrs2GrCe%2Fimage.png?alt=media&amp;token=6fb858c2-18f8-45d7-adc7-0d8cc83a860a" alt=""><figcaption></figcaption></figure>

When you are in the portal, navigate to the API tab on the left hand side menu.

### 2. Choose an API

Assuming you have an idea of the data types / entities you are interested in, ensure that the endpoints you need are available in the platform by "trying out" the API explorer.&#x20;

For the purposes of this example my app will need Applicant data. Don't worry if you find you need other endpoints later, you can add them at any time.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FwBxur7odb0MqcO99jWfe%2Fimage.png?alt=media&amp;token=634b22e3-fe93-4cca-a19f-1baecf25bc4c" alt=""><figcaption></figcaption></figure>

### 3. Register an app

The next step is to register an app. We understand you won't have any code yet, this is all about setting up a client to work with the API. Firstly click on the "Create App" button on the apps page from step 1. This will load a wizard asking you to select from the options the type of app or integration you are building.&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FtTp0P5OvcW5ajih609eh%2Fimage.png?alt=media&amp;token=de948019-4f49-4f91-a268-135ced9df7ce" alt=""><figcaption></figcaption></figure>

Depending on your use case you will be presented with various options. For this example, we will be selecting the option for 'AgencyCloud Functionality'. You will see on the right-hand side all information relating to this selection, helpful documentation and links.&#x20;

The next step is to provide routes for our OAuth service Reapit Connect to redirect back to your app. You can add production routes later but for now, we will add localhost for development.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FGckUWktWgZJmqdnFJqoQ%2Fimage.png?alt=media&amp;token=f7118e66-dea0-4c2c-9900-23d53054ebd5" alt=""><figcaption></figcaption></figure>

You will be then asked to select permissions that map directly to OAuth Scopes, and also the endpoints you selected at stage two of this guide.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fffe5Gbc1CFAS6kfzddWh%2Fimage.png?alt=media&amp;token=8e909b47-e7bd-46f5-b0dd-f444b1dc8e57" alt=""><figcaption></figcaption></figure>

On completion of this step, you will be taken to your App Details page which will provide you with your App Client Id. You will need this for authenticating via Reapit Connect OAuth.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FWOTcc42GNl7lEoGjLut7%2Fimage.png?alt=media&amp;token=5c8f97de-3b00-4df0-b2c6-1d69c4210a48" alt=""><figcaption></figcaption></figure>

Clicking on 'Edit Details' on the left hand-side will present you with more information about your app, where to amend your app details. permissions etc. Please note, the app name is pre-populated based on your company name and can be changed at any stage.&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FEoL9qnFjKkBZxf8ClsnT%2Fimage.png?alt=media&amp;token=f8cbd258-6864-4b51-8a21-4d490687b95a" alt=""><figcaption></figcaption></figure>

### 4. Populate your app listing (optional)

The previous section of this guide gives us enough detail to allow you to authenticate against our APIs and for you to be productive on the platform. When your app is in development, you will however want to get it ready to be listed in the AppMarket. To do this you will need to provide some additional information.

From the 'App Details' Page below, select "Edit App" and select 'AppMarket Listing':

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FG4Mw0YIlMB1L6oPzVvR1%2Fimage.png?alt=media&amp;token=8d7a2ca2-9a9a-475b-881c-29a67318e651" alt=""><figcaption></figcaption></figure>

You will be asked in the first section to provide details that populate your app listing, tell us how to launch your app and how your customers should contact you for support. As you go through the form we will ask for images such as an icon, featured image and screenshots. Fore more information on the requirements, please [click here](/listing-your-app/app-listing-review).

### Other Sections

Based on our selection from the wizard, will may  see a tab for 'Reapit CRM Integration' and a toggle if you wish to integrate with the AgencyCloud CRM and if so, what page you would like to integrate with. This will allow your app to be launched as a screen direct from AgencyCloud by a user. It is an optional step and is in addition to being able to launch from the top level "apps" menu in the CRM. More on this behaviour in the [Desktop](/api/desktop-api#desktop-types) docs.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FkgP2lOkYaqNHJUIlUs81%2Fimage.png?alt=media&amp;token=aa58b013-0d78-4c83-bb5c-15937eb6c8f6" alt=""><figcaption></figcaption></figure>

You will also then see the 'Authentication' tab, as this example is a user facing integration this section will allow you to use our hosted authentication service, [Reapit Connect](/api/reapit-connect#overview). As part of this flow, you need will need to register one or more call back URLs and a log out URL to allow Reapit Connect to direct traffic back to your application in a secure way.

If you are developing a **server-side machine to machine** application such as a feed to another system, the tab will not be visible. You can find details on how this flow works in our [platform documentation](/api/api-documentation#authentication).

The next tab is 'Permissions', here you can select any additional permissions (OAuth scopes) you need for your app to work.&#x20;

Here you can also set the visibility of your app using the 'Private Apps' toggle. This is used if you wanted to restrict the AppMarket listing to a single or limited sub-set of clients, for example if you are building some private in-house tooling.&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FkGnQjxCCONig2GUQPDTt%2Fimage.png?alt=media&amp;token=7804a224-3b87-4147-9096-34a01dceb91a" alt=""><figcaption></figcaption></figure>

Finally, one you have completed the relevant details, simply click 'Save Changes' on the left-hand side.

It is important to note, the app is not live yet. You can check the status of your app at any stage by going to 'About Listings' and click on 'Check Status'.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FMrjOzmbOip0Ovo0fN8tJ%2Fimage.png?alt=media&amp;token=7462d115-d6ca-4548-8120-8a12bba4d6be" alt=""><figcaption></figcaption></figure>

The check status button is a very quick and easy way to see the current status of your app, what information is missing, your AppMarket status and to see if have any changes that require saving.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FrGMEYOa3vFf68BGjEVAB%2Fimage.png?alt=media&amp;token=2ad2519f-1fd1-40e6-bc80-c2603467b093" alt=""><figcaption></figcaption></figure>

The process for submitting your app for review is the same as before. Simply check the status of your app and once all checks have been completed (see example below):

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FhG8qu91x0K8go1xWkMis%2Fimage.png?alt=media&amp;token=b9c5d25b-ad99-415f-a50a-ae4e3b362826" alt=""><figcaption></figcaption></figure>

A button on the left-hand side will appear ‘Submit Review’. This will create a revision to our Admin team.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FrYm5z0OMeTM1BL8HLaV6%2Fimage.png?alt=media&amp;token=37e80b1c-6357-4bb1-a701-887710644e36" alt=""><figcaption></figcaption></figure>

Once your app has been approved (please [click here](/listing-your-app) for more information on the reviewal process) the button will change to present the option to ‘Delist’ your app.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F4ZfSWRK4PqoDjNaghZdD%2Fimage.png?alt=media&amp;token=5dbe1ff6-c712-45ef-8d21-fd43bc510b54" alt=""><figcaption></figcaption></figure>

### 5. Get your Client Id

From the 'App Details' page, you will need to obtain your application's client id to authenticate your new app.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FWOTcc42GNl7lEoGjLut7%2Fimage.png?alt=media&amp;token=5c8f97de-3b00-4df0-b2c6-1d69c4210a48" alt=""><figcaption></figcaption></figure>

Please note, if you have selected "Client Credentials" as your authentication flow, you will also see your client secret also, on this page.

### 6. **Write some code!**

The first step with your application will be to authenticate it against our Platform APIs. To do this you will need to use our authentication service [Reapit Connec](/api/reapit-connect)t which supports the OAuth protocol. To make this easier on the client side, we have some JavaScript helpers you might find useful in our [Connect Session](/app-development/connect-session) module, however, if you are familiar with OAuth, you can just roll your own.

### 7. Scaffolding an app (optional)

Even if you don't use React or intend to write your own React app from scratch, it is worth scaffolding an app with our new Create React App Template as initial playground, until you feel comfortable working with the platform. You can get full [documentation on this step here.](/app-development/create-react-app-template)

### 8. A word on hosting...

Whilst marketplace apps are "submitted", "listed" and "installed" by clients, they are still hosted by you, the developer. This is both to ensure the integrity of your IP / source code, and so that you maintain control over your deployment pipelines.

Optional hosting as a service is something we are looking at in detail for future iterations of the platform however it is not on our immediate roadmap. You should continue to use your existing web hosting platform for your app and just submit the launch uri on the submit app form as above.&#x20;

### 9. Organisation

To complete your Organisation information, click on ‘Settings’ and select ‘Organisation’\
\
&#x20;You will then be required to fill in the following information:

* Company Name
* Telephone Number
* Website Address
* VAT/Company Reg and or National Insurance Number
* About Us – The section will be displayed on any app listing in the AppMarket in addition to information about the app.&#x20;
* Company Address

In order to list your App, please see the guidelines within the '[Listing your App](/listing-your-app)' section&#x20;


# Listing your App

Listing your app in the Reapit AppMarket

{% hint style="info" %}
The review process from start to finish can typically take up to 60 business days (12 weeks). Please allow plenty of time as we often have a backlog of apps and integrations to review.
{% endhint %}

When you are ready to list your app in the Reapit AppMarket, either publicly or as a private app, it will first need to be submitted for approval. For Reapit AppMarket apps, please see information on additional testing [here](/whats-new#additional-testing). The approval process is started when you select the 'Submit for Approval' check box and 'Submit'

Our Partnership team will be notified and will carry out the necessary checks. This includes but is not limited to content for your app listing, UI compliance (if building an application that is launched within the Reapit desktop), authentication and permissions/scopes as well as architecture and security.&#x20;

There are other guidelines that also need to be followed, please refer to '[Schedule 3](/developer-terms-and-conditions#schedule-3-developer-obligations)' of Reapit's Developer Terms and Conditions and make sure to read them carefully.

Please see below the steps to follow to submit your app for approval:&#x20;

### 1. First, make sure your app listing is ready

Description, Images, Icon, Screenshots & Bullet points etc. Remember that the content you add to your app will be one of the first things a Reapit agent will see when viewing apps in the Reapit AppMarket.&#x20;

To help with ensuring you are ready, have a look at our guide on adding your content [here](/listing-your-app/app-listing-review)

### 2. Submit for Approval

When you are ready to submit your app for review, you will see the 'Submit Review' option appear on the left-hand navigation. It will only be visible if you have completed all the revenant information.  If you are unsure, you can alway check the status of your app by going to 'Edit Details' & 'Check Status'.&#x20;

After submitting your app the Partnerships team we will be notified.&#x20;

Depending on your app or integration and its complexity, the review process from start to finish can typically take up to 60 business days (12 weeks). However, there are circumstances in which this may not apply.

<img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F4hng54KYkREr1lYOCoXv%2FScreenshot%202026-01-05%20at%2012.15.12.png?alt=media&amp;token=ac07ac52-52c9-4875-82fe-05c63455c329" alt="" width="215">

&#x20;

To make it easier to understand, we have put together the following as a guide:

**Publicly listed: App or Integration**

Review time: 60 business days (12 weeks)

&#x20;

**Privately listed: App or Integration**

Review Time: 5 business days (1 week)

If your app is launchable within the Reapit desktop or has a Client facing user interface, we will ask you to set your app to private, using Customer ID 'RES-GRTA’. We can then install your app as an external client (still using sandbox data). This step will give us the ability to test and view the following:

#### Apps - launchable inside of Reapit desktop

* Authentication\
  Ensuring an agent is not required to login with additional credentials or is presented with an additional login screen. Must use Reapit Connect.&#x20;
* Onboarding\
  Understanding the flow for existing and new users.
* Branding\
  We will look at your use of Elements, our UI Library, ensuring you have built the integration according to our branding guidelines
* Functionality \
  Using the app in accordance with the service it is providing
* Permissions\
  Must use the Platform API and be using the permissions requested&#x20;

#### Integrations&#x20;

For integrations, after installing, we will require a test and production user account to login into your website/app so our admin team can test its functionality. This will provide us with the ability to check:

* Authentication\
  If you have implemented Reapit Connect ‘Sign in with Reapit’ on your website, we will test with our user account to ensure that it is functional
* Onboarding\
  Understanding the flow for existing and new users
* Functionality\
  Using your website or app in accordance with the service it is providing

There are also other guidelines that need to be followed, please refer to '[Schedule 3](/developer-terms-and-conditions#schedule-3-developer-obligations)' of the Reapit Developer Terms and Conditions.&#x20;

### 3. Submission Declined

If the request to publish your app has been declined, you will be informed of the reason via email. Sometimes, it could just be as simple as providing clearer images or that you may be missing some vital contact information.&#x20;

### 4. Submission Approved

As soon as your app has been approved, it will be available in the Reapit AppMarket and you will be informed via email automatically. If it has been set to Private for testing, simply remove ‘RES-GRTA’ from the Private section and re submit.&#x20;

For more information about the requirements for listing an app in the AppMarket, please refer to the [Reapit Developer Terms and Conditions](/developer-terms-and-conditions).&#x20;

If any changes are required you will be contacted by a member of the team.

Once your listing has been approved, you will receive an email confirming your app has been approved and will be set to a status of 'Listed'.  You app will then be listed in the Reapit AppMarket ready for client installation.&#x20;

### 5. Need help?&#x20;

If you have questions about listing your app the approval process, you can contact the Partnerships team at <partners@reapit.com> &#x20;

Please refer to our [Partner Business Service Catalogue](https://www.reapit.com/legal/terms-and-conditions/reapit-partner-business-service-catalogue) for our response and resolution times.&#x20;


# App Permissions

External developers (Partners) are required to contact the Reapit Partnerships team (<partners@reapit.com>) before any app revision is submitted for access to new permissions. Please refer to the [Reapit Partner Business Service Catalogue](https://www.reapit.com/legal/terms-and-conditions/reapit-partner-business-service-catalogue) for response times.&#x20;

The Partnerships team will request additional information regarding the new permission, such as the business purpose, what info will be used from the new permission, how it fits into your product process, how you will use the data etc.&#x20;

Once approved by the Partnerships team, the following process will need to be followed;&#x20;

#### **Step 1:**

Add the new permissions and click ‘Create Revision’.

#### **Step 2:**

A modal will appear presenting you with the option to ‘Send Requests’. If you choose to send the requests, an email will be sent to the person that installed your app.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FpO73dzUqrSLCXDgcgSkp%2Fimage.png?alt=media&amp;token=d89afe22-2f2d-4c7a-8a3c-07a18f22748b" alt=""><figcaption></figcaption></figure>

Every customer who has installed your app must agree to the new permission before our team can approve your revision.&#x20;

You can track this process on the ‘App Consents’ page or reach out to your customer to expedite their response to our message.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FdgeDByLgt7mpcNZ2pp84%2FConsents.jpg?alt=media&amp;token=a41f2ed0-119f-4211-b29b-18a3c53a4bcc" alt=""><figcaption></figcaption></figure>

If you decide not to send the requests, our Partnerships team will send the requests on your behalf.&#x20;

Please see an example email the customer will receive:

“Dear ‘CUSTOMER ORGANISATION’,

An App you have installed from the AppMarket ‘YOUR APP NAME’ has requested the following additional permissions to your data:

PERMISSION

To agree to the requested data, please click accept below where you’ll be redirected to the AppMarket. If you are unsure of this request or you have questions, please contact 'YOUR EMAIL ADDRESS’ for more information.

ACCEPT

Kind regards

Reapit Ltd”

Please note, the email address for the customer to contact will be your own email address should they wish to discuss the requested permissions.&#x20;

#### **Step 3:**

The customer will be redirected to the AppMarket and will be need to ‘Accept’ the request. This is to ensure data security.

#### **Step 4:**

The admin team will be able to monitor the status of each request and once you have received approval from all customers, we will approve your request.&#x20;


# App Listing Review

To prevent delays in reviewing your app or integration, please ensure you have completed the following information and checks before submitting your app for review:

* [Icon](#icon)
* [Featured Image](#featured-image)
* [Summary](#summary)
* [Description](#description)
* [Images](#images)
* [About Developer](#about-developer)
* [Desktop Integration Types](#desktop-integration-types)
* [Permissions](#permissions)

### Icon

**Size**: 96px x 96px

The app icon is the first opportunity to communicate, along with the app summary, what you are offering. We recommend keeping the logo simple but should be recognisable and understandable. The icon will be placed on a white tile and grey background so ideally avoid text, screenshots or photos.

Your company icon will be shown on the left hand side of your app listing in the AppMarket.

![Example Icon (TouchRight Software)](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MDUwGPk93EWsZo2xaF4%2F-MDV8GtXvRVwmQC00_IR%2FTouchRight-Software-icon%5B1%5D.png?alt=media\&token=21e613b9-124d-4e4f-a519-9e63c6db7a38)

### **Featured Image**

**Size**: 495px x 222px

The featured image will appear at the top of your listing page as the first graphic representation of your app before any screenshots. It may also be used for external marketing as well as within the AppMarket under our ‘Recommended Apps’ or ‘Featured Apps’.

The featured image should be more of a graphic/advert style, no screenshots of the application. Ideally it should convey your app’s value proposition.

![Example Featured Image (Goodlord)](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MDUwGPk93EWsZo2xaF4%2F-MDUwdgQXHT92dfgRF86%2FOh-Goodlord-Ltd-screen1ImageUrl.png?alt=media\&token=8a5b53cf-dfec-40ae-a757-21f6ae391140)

&#x20;&#x20;

### **Summary**

**Character Limit:** 150

The summary is a short description about your app and will be one of the first things shown in the AppMarket before a user clicks through for more information.

Users should be able to clearly see what your app is about when browsing. You have a maximum of 150 character to utilise which will be displayed on both the app tiles and on your app listing.

### **Description**

**Character Limit:** 20,000 (special characters are included in the character limit)

The next step after a user discovers your app in the AppMarket, is to read more about it.

Creating a detailed and accurate description of your app is what will give users the full understanding of what your app has to offer. Appealing enough to encourage users to install.

The focus should be on conveying the value of your app/integration and should work alongside the images you provide.

A great way to think about how to format your description is to picture yourself as the user and what would appeal to you about your application, what problem exists and the solution it provides.

We also request that you include a section for key features (a short bulleted list on the benefits of the app/integration)

The description field also supports external links.

&#x20;

### Images

**Size**: 598px x 457px

You have the option of uploading 4 screenshots on your app listing and we require a minimum of 2.

Whilst screenshots give the user the ability to see your app in action, you can create the screenshots to include text to highlight the important features. Really maximise the space and visual impact of your app listing.

2 screenshots are placed directly under the ‘Summary’ and the other 2 are placed below the ‘Description’.

![Example Screenshot (GEO Diary)](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FjI5ebRItzmWbN9bTogoC%2Fimage%20\(13\).png?alt=media\&token=2e3c6929-3071-4431-9a76-07ce55bbb47c)

### About Developer

**Character Limit:** 250

**Field Location:** <https://developers.reapit.cloud/settings/organisation> (Admin's only)

The ‘About Developer’ section is specific to your organisation and not set at app listing level. Therefore, you should add information in this section to share with users’ details about you as an organisation.

### Desktop Integration Types

Desktop Integration Types or Agency Cloud Integration Types are only to be used for apps that’s launch inside of AgencyCloud and are not required or should not be used if you have developed an integration.

For more information on Integration types and our Desktop API, please visit <https://foundations-documentation.reapit.cloud/api/desktop-api> or watch our video here <https://www.youtube.com/watch?v=E1df4fThSdw>

### Permissions

Please ensure that you have only selected the permissions that your app/integration is using.

We will test/check the requirement for each permission to ensure you are actively using them. If you have selected permissions that you are not using, your app maybe declined until they have been updated.&#x20;


# App Development

A guide to building web applications for the Reapit AppMarket

At Reapit we want to make it as easy as possible to get started building apps against our platform APIs. For this reason we have open sourced a lot of the tooling we use internally for App Development for our App Partners to use.

As you will have read in the [developer portal guide](/developer-portal), for developers familiar with React a great place to get started is the Create React App Template, which extends Facebook's CRA scripts with Reapit tooling.

If you are planning to build a AppMarket App that is launched from the AgencyCloud CRM, we ask that you adhere to our interactive Style Guide [Elements](/app-development/elements). This is distributed as an NPM package with components for React users and a stylesheet for Non React users.

We understand that authenticating your app using [Reapit Connect](/api/reapit-connect) single sign on can be a pain point and to smooth this process over, we have built a low dependency, framework agnostic auth package on NPM, [Connect Session](/app-development/connect-session). This exports Vanilla JS, NodeJS and React versions and handles all redirecting, caching and refreshing of your session.&#x20;

In addition, we export up to date [TypeScript definitions](/app-development/foundations-ts-defintions) of the Platform API, with [Web Component](/app-development/web) widgets to extend any site with Reapit functionality coming very soon.


# Developer Guidelines

This guide is intended to provide basic guidelines on the delivery of projects for the Reapit Foundations Platform as a Service (PAAS).

## General

* Production applications to be written in TypeScript. JavaScript only to be used for scripting, config files and throw-away rapid prototyping.
* TypeScript definitions for platform endpoints should be imported from <https://foundations-documentation.reapit.cloud/app-development/foundations-ts-defintions>&#x20;
* Use of “any”, “unknown”, and inferred types should be avoided in the codebase.
* Code should be explicit in typing for future maintainers and be type-checked at compile time with the TSC.&#x20;
* Babel TypeScript should be avoided as it offers no type checking.
* Modern ES6+ standards to be used throughout, enforced with ESLint. ESLint config should extend the TypeScript ESLint recommended settings.
* Code should be formatted using Prettier, with a standard config.
* Automated testing essential on all production applications. Either unit tests written in Jest or functional end to end tests in Cypress. Other well supported test frameworks are also acceptable.&#x20;
* Unit test coverage basic metric is at least 80% coverage lines, statements, and functions.
* Functional tests where used, should cover all core user journeys as defined in the client supplied product definition.
* Code should be deployed using CI/CD pipelines that run tests, lint and compile the code prior to merging and deployment.
* Github Actions, Circle CI, Azure Devops, or any other well supported CI/CD provider are acceptable.
* Code should be deployed to a cloud provider offering industry standard security and reliability e.g. AWS, GCP, Azure or Heroku.
* Infrastructure must be shipped “as code”, using solutions like CloudFormation, Serverless Framework and Terraform.
* It must be possible for all infra to be programmatically destroyed and rebuilt without manual configuration steps.
* Env files, API keys and other semi-confidential application specific config like client ids must be stored in a secure remote location e.g. AWS SSM Parameter Store.
* Do not assume that a Reapit entity `id` is globally unique across the Reapit platform. Integrations that aggregate data from multiple customer databases should always include customer and entity type context when identifying records. Read more about this [here](/api/api-documentation#entity-references-and-data-uniqueness).&#x20;

## Front End

* Front end applications to be bult in React primarily.
* If there is an SEO requirement for a project, NextJS and Gatsby are acceptable choices for SSR.&#x20;
* React code should be primarily functional, only using OO paradigms like classes when entirely necessary.
* State management should use React Context / Hooks API for smaller projects and Redux if the project is large.&#x20;
* Consider using GraphQL / Apollo both state management and data fetching using our dedicated service <https://foundations-documentation.reapit.cloud/api/graphql>&#x20;
* Authentication in the front end must use the Reapit Connect OAuth flow and must validate id tokens on authentication.&#x20;
* No access or id tokens should be cached outside of memory (local storage, cookies) and the user session must not last longer than a browser session.&#x20;
* It is highly recommended to use <https://foundations-documentation.reapit.cloud/app-development/connect-session> to manage
* Reapit Elements must be used as the primary UI library and styleguide for all Reapit AppMarket project.
* No other UI frameworks should be used (Material UI, Tailwind etc), to ensure visual consistency with Elements.&#x20;
* Vanilla CSS, SASS or a well-supported CSS in JS library are all acceptable for small visual tweaks not available in Elements
* All modern browsers should be supported (Chrome, Edge, Firefox, Safari). Minimum Chromium version is 69.

## Back End

* Node Services can use either functional or OO paradigms. This should be consistent on a project-by-project basis and not mixed in the same project.
* Express should be used for simple to medium complexity RESTful NodeJS services.
* Cloud functions are an acceptable alternative to Express for micro services. Can also be used with Express.
* For more complex services, other frameworks like NestJS can be considered, but musy be well supported and have a solid long term support.
* Low cost pay as you use, serverless solutions should be used for infra eg Lambda, Dynamo and Aroura over “always on” containers and DBs.&#x20;
* If using Node to serve client side applications, Reapit Connect must be used to authenticate as per Client Side React applications.

## Technical Test

*The below test is intended to assess suitability for candidates applying to work on the Reapit Foundations Platform*&#x20;

Task: To render a list of Properties from the Foundations API, using the Reapit Elements UI library Table. Following the steps below will give you the solution - if you spend plenty of time reading the documentation carefully, the code itself should take no more than an hour.

1. Register for the developer portal here: <https://developers.reapit.cloud/register>
2. When you have followed the registration flow and have logged in, navigate to the docs page here and follow the steps here to register an app and obtain a client id: <https://developers.reapit.cloud/api-docs/developer-portal> When asked for permissions, you will need Read Properties and Write Properties only.
3. Next scaffold an application using our Create React App template here: <https://developers.reapit.cloud/api-docs/app-development/create-react-app-template>&#x20;
4. In your text editor, add your client id and user pool id to the reapit-config.json file as per the documentation in the previous step and start the Webpack dev server.
5. Log into your scaffolded app using your developer portal credentials - you will see a welcome screen and in the console, you will see logged out an example of data being fetched from the platform API.
6. Replace the fetched data with an API call to the GET /properties endpoint here <https://developers.reapit.cloud/swagger> you should apply a marketingMode filter of “selling” to your query.
7. Render this data on the page in a Table using the React version of our Table component here: <https://elements.reapit.cloud/?path=/docs/table--react-shorthand-usage>. Add a Title to the page “Properties for Sale”. There is an example Table laid out in the CRA scaffold app.
8. Add a form to the table slide down component that updates the property address fields. On submit, the form should update the API and the table should refresh with the updated property info. There is an example form in the CRA template, you are free to add any third party form library you like. TIP: take time to read about [etags and the if-match header here.](https://foundations-documentation.reapit.cloud/api/api-documentation#optimistic-concurrency)<br>

Good luck!


# Usage Guidelines

Getting the most out of our Platform

To ensure your application is a good tenant and provides the best experience to our customers, please adhere to the following usage and architectural guidelines when interacting with our platform

## Rate limits

We apply rate limits on the API calls an application can make within a given time period. If this limit is exceeded, your app will be throttled, and API requests will fail with a 429 Too Many Requests response.&#x20;

* 20 requests can be sent per second
* 5 maximum concurrent requests at any time per customer&#x20;
* 250,000 maximum requests per day&#x20;

To best adhere to these limits, we recommend that your application maintains no more than 5 API interaction threads and awaits completion of previous requests before submitting new ones.

## Appropriate usage

### Our REST APIs are intended for:

* Retrieval of data in real-time as and when your application requires it
* Storage of data as a transactional, operational data store for your application&#x20;

### Our REST APIs should NOT be used for:

* Bulk extraction of data into third party applications, databases, or data warehouses to support business intelligence (BI), data mining, and other decision support applications&#x20;
* Automated or scheduled routines to acquire data without a requirement to immediately process it for your applications use case (this does not include webhooks)&#x20;
* Load or volume testing of your application using sandbox or customer data&#x20;

Applications that do not use our APIs appropriately will be removed from the AppMarket.

## Being a responsible tenant

### Creating entities&#x20;

You should perform a uniqueness check before adding a contact or contact centric entity (applicant, landlord, etc) to avoid data duplication.&#x20;

Where possible, email address is usually the best way of finding a pre-existing entity. We understand that results may vary depending on data input, but our customers would appreciate your app taking this step.

### Updating entities

Our customers data is accessed by multiple different applications concurrently. We have built mechanisms to protect data integrity during update operations

To minimise the footprint of your application, where update operations use the `PATCH` verb, only include the fields that your application wishes to change in the payload.&#x20;

From time to time, you may receive a `412` status code implying that an update has been attempted using a stale version of the entity. Your application should handle this situation replaying your change set over the top of a refreshed version of the entity and re-submitting your `PATCH` request.


# Elements

Reapit Elements is a React component library for building digital experiences that feel native to our platform.

### What is Elements?

Elements is a React component library that implements Reapit's Design System. Reapit's own products use Elements extensively and if you are building a React app that integrates with one, it enables you to deliver an experience that looks and feels native to our platform.

{% columns %}
{% column width="50%" %}
{% embed url="<https://design.reapit.cloud>" %}
Elements Design System documentation
{% endembed %}
{% endcolumn %}

{% column width="50%" %}
{% embed url="<https://elements.reapit.cloud>" %}
Elements component library Storybook
{% endembed %}
{% endcolumn %}
{% endcolumns %}

{% hint style="info" %}
v5 represents a significant rewrite. In many cases, v4 components are still available, though deprecated, so you can incrementally adopt their replacements. Codemods are available for those that have been fully removed. The [changelog](https://elements.reapit.com.au/?path=/docs/changelog--docs#500) is available, as well as a dedicated [v5 migration guide](https://elements.reapit.com.au/?path=/docs/v5-migration--docs).
{% endhint %}

### MCP servers

The Design System and component library documentation are both available via MCP. The Getting Started guide provides details on how to provide access to your agents.

### v4 maintenance mode

With the release of v5, Elements v4 has entered maintenance mode. Support is now limited to security patches and regressions.

v4 will remain in maintenance mode until the next major release. It will then become end-of-life.

The deprecated v4 components still available in v5 are planned for removal at the next major release. Consumers are encouraged to migrate to their replacements. Codemods will be provided where feasible to aid in this work.

### Migrating from earlier versions

{% hint style="danger" %}
Elements v1, v2 and v3 are all end-of-life and no longer supported. Consumers still using those versions are encouraged to upgrade to v5.
{% endhint %}

The v3 to v4 migrate migration guide is available in [the v4 docs](https://v4.elements.reapit.com.au/?path=/docs/introduction--docs) and the full set of changes can be seen in the [v4 changelog.](https://v4.elements.reapit.com.au/?path=/docs/change-log--docs)

The v1/v2 to v3 migration involves many breaking changes. See the [v2 to v3 migration guide](https://elements.dev.paas.reapit.cloud/?path=/docs/introduction--docs#migrating-from-v2) for more information.


# Vite Template

A Vite Template to get you immediately started with Reapit Foundations

{% hint style="warning" %}
Stay tuned! We are in the process of migrating the Vite template to Elements v5.
{% endhint %}

{% hint style="info" %}
Even if you aren't going to build a React app, we still suggest scaffolding an application with the Vite template as an example of how to get the best out of Reapit Elements.
{% endhint %}

The fastest way to get started building a Reapit AppMarket App is with our [Foundations Vite Template](https://github.com/reapit/foundations-react-vite-template). Out of the box you will have an app that:

* Is authenticated against our Platform API using Reapit Connect and Connect Session
* Has the Elements UI library installed and out the box, it ships a fully working end-to-end Reapit contact look up and edit app, demonstrating how to get started with the platform as well as suggested UI layouts and patterns
* Has a login, log out, private protected routes, primary and secondary navigation.
* Includes TypeScript Platform Type Definitions, and Unit Tests.
* Includes Github Actions pipelines for pull request validation and production deployment.
* Comes bundled with AWS CDK scripts to enable you to deploy to your own AWS environment with virtually zero configuration.
* For a quick start development environment, you can deploy to our [Infra as a Service (IaaS)](/app-development/iaas) - contact us for beta access.

{% hint style="info" %}
For a demo deployed to our Infra as a Service (IaaS), [visit here.](https://handsome-zipper.iaas.paas.reapit.cloud/) You can use your developer credentials to log in with Reapit Connect.
{% endhint %}

### Getting Started

First, if you don't have a Reapit Connect client id yet, will need to obtain one [here](https://developers.reapit.cloud/apps/new).

If you are creating a fresh client id or already have one but want to see the full functionality of the template, you will need to add the following scopes to your app `read contacts`, `write contacts`, `read negotiators` & `read offices` - you can always remove these scopes later if you don't need them.

Ensure also you have set `http://localhost:8080` as a redirect uri and `http://localhost:8080/login` as a logout uri in your app settings in the [developer portal](https://developers.reapit.cloud/apps).

The output app will create a simple CRUD contacts app to demonstrate the features of the platform.

#### Prerequisites

* Node.js 18+
* Yarn 1+

First, run;

```
npx degit reapit/foundations-react-vite-template <<Your App Name>>
```

Then;

```
git init
```

And;

```
yarn
```

Add your `CONNECT_CLIENT_ID` to the `.env.example` file at the root of the project and rename it to `.env`.

Finally

```
yarn start
```

Each package has the following commands that can be run using yarn:

* `yarn start` will start a dev server at localhost:8080 with typechecking and linting enabled
* `yarn build` will build an app for production
* `yarn test` will run the Jest tests in watch mode
* `yarn test:ci` will run the Jest tests without watch and with coverage for use in CI environments
* `yarn lint` will run eslint and prettier accross the project
* `yarn check` will use tsc to type check the project
* `yarn upgrade:deps` will load a CLI to that allows you to update dependencies to their latest versions

### CI/CD and Releases

#### Development & PRs

When raising a PR, the dedicated Github action workflow will run tests, linting, typechecking and build tasks against all packages that changed since `main`.


# Create React App Template

A Create React App Template to get you immediately started with Reapit Foundations

Since Facebook have taken the decision to no longer support the Create React App project, we have in turn deprecated our template. In it's place, we have provided a Vite Template repo that fulfils the same purpose and gives you some additional features and functionality.&#x20;

See the [dedicated page ](/app-development/vite-template)in these docs for more.


# Connect Session

An NPM package to simplify OAuth with Reapit Connect

We are aware that managing OAuth flows can be tricky, especially redirecting, keeping sessions refreshed and cached. To make this process easier, we have built the Connect Session module for any JavaScript app.

To get started run `yarn add @reapit/connect-session`

Then follow the steps for either browsers, React or NodeJS below.

### Basic Browser Usage

The module is intended to be browser framework agnostic although we ship a React Hook for React users (see below).

For all users, in a file at the root of the source of your project, first instantiate and export the `ReapitConnectBrowserSession` class.

The constructor accepts 5 parameters, of which two are optional, see comments below. The  production `connectUserPoolId` is `eu-west-2_eQ7dreNzJ` .

```typescript
import { ReapitConnectBrowserSession } from '@reapit/connect-session'

// You should instantiate the class once only as a singleton as the module manages it's own state
export const reapitConnectBrowserSession = new ReapitConnectBrowserSession({
  // The client id of your application, obtained from Reapit Developer Portal
  connectClientId: 'SOME_CLIENT_ID',
  // The url to the Reapit Connect instance. While in beta this is the below URL but will need to be context aware in full prod/
  connectOAuthUrl: 'https://connect.reapit.cloud',
  // OAuth UserPoolId - refer to the foundations documentation to obtain this for the correct environment
  connectUserPoolId: 'SOME_USER_POOL_ID',
  // The relative path you want to re-direct in your application after a successful login. You will have supplied this when you registered your app.
  // Defaults to '' or the root of your project if not supplied
  connectLoginRedirectPath: '/some-redirect-path',
  // The relative path you want to re-direct in your application after a successful logout. You will have supplied this when you registered your app.
  // Defaults to '/login' if not supplied
  connectLogoutRedirectPath: '/some-login-path',
  // The time in ms before your session times out when a user is inactive. 
  // Defaults to 10800000 - 3hrs
  connectApplicationTimeout: 10800000
})
```

The instantiated class can then be used in your code. It exports the following methods:

```typescript
import { reapitConnectBrowserSession } from './path-to-your-module'

// The definition of the reapitConnectBrowserSession
interface ReapitConnectSession {
  // The accessToken is the `Bearer <<token>>` you need to authenticate against the platform API.
  accessToken: string
  // Refresh token is provided as a convenience - in practice the module handle's refreshing and caching of your session out the box
  refreshToken: string
  // Id token is provided as a convenience - the parsed output is below in the loginIdentity object below
  idToken: string
  loginIdentity: {
    email: string
    name: string
    developerId: string | null
    clientId: string | null
    adminId: string | null
    userCode: string | null
    groups: string[]
    orgName: string | null
    orgId: string | null
    offGroupIds: string | null
    offGrouping: boolean
    offGroupName: string | null
    officeId: string | null
  }
}

// Returns a promise containing your reapitSession object as per the interface above
reapitConnectBrowserSession.connectSession().then((reapitSession: ReapitConnectSession) => reapitSession)

// Handles redirect to authorization endpoint - in most cases, I don't need to call in my app as handled by the module
// but made public in case I want to override the redirect URI I specified in the constructor
reapitConnectBrowserSession.connectAuthorizeRedirect(redirectUri: string)

// Handles redirect to logout - defaults to constructor login uri but I can override if I like.
reapitConnectBrowserSession.connectLogoutRedirect(redirectUri: string)

// Handles redirect to login - defaults to constructor redirect uri but I can override if I like.
reapitConnectBrowserSession.connectLoginRedirect(redirectUri: string)

// A convenience getter to check if my app has been loaded inside RPS / Desktop / Agency Cloud
reapitConnectBrowserSession.connectIsDesktop

// A convenience getter to check if my app has a valid session
reapitConnectBrowserSession.connectHasSession

// Allows the current session in memory to be cleared programatically.
// Useful if you want to trigger a refresh of your session from a refresh token in
// session storage.
reapitConnectBrowserSession.connectClearSession
```

### React Usage

In addition to the basic browser API, we export a React Hook to use in your React Components.

To leverage the Hook, first instantiate the class as per above. Then, around the Routes you wish to protect with Reapit Connect authentication, simply return when the session is not present as below:

```typescript
// import the instantiated class, the hook and the provider
import { useReapitConnect } from '@reapit/connect-session'
import { reapitConnectBrowserSession } from './connect-session'

export const PrivateRouteWrapper: React.FC = ({ children }) => {
  // Call the hook to retun a session object
  const { connectSession } = useReapitConnect(reapitConnectBrowserSession)

  // The session object implements the same interface as the browser class with the exception that the connectSession promise is handled wrapped in a useEffect hook and so is just an objecy or null. Here I return null from the component while I am fetching a session
  if (!connectSession) {
    return null
  }

  // I now have a session I can render my App
  return (
    <AppNavContainer>
      <Menu />
    </AppNavContainer>
  )
}
```

Then in my React child components, I have access to the session values and methods eg:

```typescript
import { useReapitConnect } from '@reapit/connect-session'
import { reapitConnectBrowserSession } from './connect-session'

export const SomeComponent: React.FC = () => {
  const { connectSession, connectLogoutRedirect } = useReapitConnect(reapitConnectBrowserSession)
  const handleLogout = () => connectLogoutRedirect('/custom-login-path') // Optional path param

  return (
    <CustomFetchComponent connectSession={connectSession}>
      <Button onClick={handleLogout}>I am a logout button!</Button>
    </CustomFetchComponent>
  )
}
```

### Sign In With Reapit Button

Perhaps the simplest way to authenticate on the client side is to embed the "Sign In With Reapit Button" on your page. This is not exported from the NPM package as it is distributed via a CDN however, you can see [full documentation here.](/app-development/web#sign-in-with-reapit)

### Node Usage

For server side usage, we also export a Node module with a stripped down API that simply returns a promise from a `connectAccessToken` method. For a basic and slightly contrived example, see the simple Express app below:

```typescript
import 'isomorphic-fetch'
import express, { Router, Request, Response } from 'express'
import bodyParser from 'body-parser'
import cors from 'cors'
import { ReapitConnectServerSession, ReapitConnectServerSessionInitializers } from '@reapit/connect-session'
import config from './config.json'

const router = Router()

const { connectClientId, connectClientSecret, connectOAuthUrl, connectUserPoolId } = config as ReapitConnectServerSessionInitializers

const reapitConnectSession = new ReapitConnectServerSession({
  connectClientId,
  connectClientSecret,
  connectOAuthUrl,
})

router.get('/get-access-token', async (req: Request, res: Response) => {
  const accessToken = await reapitConnectSession.connectAccessToken()
  // Do some stuff with my access token here, will just return it to the user as an example
  res.status(200)
  res.send(accessToken)
  res.end()
})

const app = express()

app.use(cors())
app.use(bodyParser.urlencoded({ extended: true }))
app.use(bodyParser.json())
app.use('/', router)

app.listen('3000', () => {
  console.log('App is listening on 3000')
})
```

As per the browser usage, you will need to instantiate the class with your initialisers, in this case `connectClientId`, `connectOAuthUrl` (in the same way as the browser module), but with the addition of the `connectClientSecret` you obtain from your app listing page.

The module will fetch and refresh your session as the token expires, caching it in session storage to minimise calls to Reapit Connect token endpoint. After closing a tab, the session cache is not persisted.


# Foundations TS Defintions

TypeScript definition files for the Reapit Foundations API

Develop in TypeScript against the Reapit Foundations Platform with confidence

If you are using TypeScript (and we recommend you do!), for your front end or NodeJS project, we provide full type definitions for the API documented in the [API explorer](https://github.com/reapit/foundations-documentation/tree/db0718c9be27b7760dfae34e69518806acf0e855/developer/swagger/README.md).

We generate these types from the Swagger contracts direct with a daily CRON job, so you can be sure that when the API changes, your types will be updated too. This allows for a much closer alignment between front and back end development, with compile time feedback on definition changes. Ultimately this should lead to more robust applications.

{% hint style="warning" %}
The definitions are updated automatically when the API changes. As such, it is recommended strongly that you match by date stamp the correct version of the definitions to the API version you are using in your headers.
{% endhint %}

### Usage:

For the latest version;

`yarn add @reapit/foundations-ts-definitions`

Then import the required type into your code with ES6 Modules or CommonJS. The naming maps directly to the model names in the API Explorer in the developer portal.

```javascript
import { AppModel } from '@reapit/foundations-ts-definitions'

// Or

const { AppModel } = require('@reapit/foundations-ts-definitions')
```

### Webhook types

Webhook event payloads are generic, however the types can be infered by the topicId. Here are some examples of how to use the webhook types

```ts
import {
  ReapitWebhookPayloadType,
  ReapitWebhookTopicEnum,
  ReapitWebhookApplicantCreatedEvent,
} from '@reapit/foundations-ts-definitions'

export const webhookEventHandler = (event: ReapitWebookPayloadType) => {
  switch (event.topicId) {
    case ReapitWebhookTopicEnum.APPLICANTS_CREATED:
      handleApplicantCreated(event) // event is of infered type ReapitWebhookApplicantCreatedEvent
      break
    default:
      console.log(event.new) // event.new is of infered type any
  }
}

const handleApplicantCreated = (event: ReapitWebhookApplicantCreatedEvent) => {
  console.log(event.new) // new is of inferred type ApplicantModel
}
```


# Login With Reapit

A singular component to enable auth with reapit

The login With Reapit button is a singular stand alone component which can be utilised in any project on it's own. The component is written with Svelte which compiles Vanilla JS, CSS and HTML so are framework agnostic and be used with any other front end tech of your choosing.

### The Sign In With Reapit Button

The button leverages the Connect Session to handle the OAuth flow and returns a session object in a callback you provide.

<div align="center"><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MlUmLJGBy1oKS-otsJd%2F-MlV2kKtaqIJl5CBFa8D%2FScreenshot%202021-10-08%20at%2014.19.11.png?alt=media&amp;token=9276830a-b3fc-4676-b528-30f56758e34a" alt="Sign in With Reapit button"></div>

The Component is a single script provided by NPM package, you instantiate with a target div, your client credentials as per the browser API and pass in a callback to receive your session object. As per the NPM module, all caching, redirection and refreshing is taken care of by the package. When you have a session, the button will change function to be a logout which will clear your cache and end your session in Reapit Connect.

### Agreeing to Permissions

When clicking the Sign In With Reapit button, a dialog window will appear with the following details

<div align="center"><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MlUmLJGBy1oKS-otsJd%2F-MlV2sohzbZuxN7SCXFU%2FScreenshot%202021-10-08%20at%2014.19.03.png?alt=media&amp;token=fc2b4096-c968-44be-99b0-15155b11823c" alt="Agree to terms and permissions dialog"></div>

#### Yarn

Use the script tag below in your code base to use the ReapitConnectComponent.

```markup
yarn add @reapit/login-with-reapit
```

#### NPM

Install the `login-with-reapit` package using npm.

```bash
npm i --save @reapit/login-with-reapit
```

Below is an example of how to use the `ReapitConnectComponent` . In the connectHasSessionCallback function we fetch a list of appointments from the Platform API to demonstrate the full flow. The  production `connectUserPoolId` is `eu-west-2_eQ7dreNzJ`.

### Single HTML page example

```javascript
<div id="reapit-connect-component"></div>

<script
  type="text/javascript"
  src="./node_modules/@reapit/login-with-reapit/public/dist/login-with-reapit.js"
></script>

<script>
  const connectHasSessionCallback = (reapitConnectBrowserSession) => {
    reapitConnectBrowserSession.connectSession().then(session => {
      console.log('Session is', session)
      fetch('https://platform.reapit.cloud/appointments', {
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${session.accessToken}`,
          'api-version': '2020-01-31'
        }
      })
      .then(res => res.json())
      .then(appointments => console.log('Appointments are', appointments))
    })
  }

  reapitConnectComponent && reapitConnectComponent({
    connectClientId: '<<clientId here>>>',
    connectUserPoolId: '<<userpool id here>>',
    connectOAuthUrl: 'https://connect.reapit.cloud',
    connectLoginRedirectPath: '',
    connectLogoutRedirectPath: '/login',
    rootElement: '#reapit-connect-component',
    connectHasSessionCallback,
    companyName: 'My Company',
  })
</script>
```

### ES6+ example

```javascript
import { reapitConnectComponent } from '@reapit/login-with-reapit'


const connectHasSessionCallback = (reapitConnectBrowserSession) => {
  reapitConnectBrowserSession.connectSession().then(session => {
    console.log('Session is', session)
    fetch('https://platform.reapit.cloud/appointments', {
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${session.accessToken}`,
        'api-version': '2020-01-31'
      }
    })
    .then(res => res.json())
    .then(appointments => console.log('Appointments are', appointments))
  })
}

reapitConnectComponent && reapitConnectComponent({
  connectClientId: '<<clientId here>>>',
  connectUserPoolId: '<<userpool id here>>',
  connectOAuthUrl: 'https://connect.reapit.cloud',
  connectLoginRedirectPath: '',
  connectLogoutRedirectPath: '/login',
  rootElement: '#reapit-connect-component',
  connectHasSessionCallback,
  companyName: 'My Company',
})
```

### rootElement

The `rootElement` property can be passed either query string, DOM element or shadow DOM element.

```javascript
reapitConnectComponent && reapitConnectComponent({
  connectClientId: '<<clientId here>>>',
  connectUserPoolId: '<<userpool id here>>',
  connectOAuthUrl: 'https://connect.reapit.cloud',
  connectLoginRedirectPath: '',
  connectLogoutRedirectPath: '/login',
  rootElement: document.getElementById('reapit-connect-component'),
  connectHasSessionCallback,
  companyName: 'My Company',
})
```


# Contributing

A guide to how to work with Reapit open source packages

## Intro

At Reapit, we have made a company wide commitment to open sourcing as much source code as possible. There a number of reasons for this decision but with regard to the Foundations project these are principally;

* Approach - we want our partners to see how we go about building things internally, to give you insight into how your own integrations may work.
* Transparency - we want our partners to see what we are building, our future roadmap and progress against project milestones.
* Tooling - we want to share the tools we use internally to build AppMarket applications with our partners so they can get the benefits of quick-to-market efficient development.

All our code is in a [mono-repo on Github](https://github.com/reapit/foundations), along with our project [Kanban board](https://github.com/reapit/foundations/projects) and an open [issues page.](https://github.com/reapit/foundations/issues) Most people will want to use this as a resource alongside their own project, as living code as documentation but if you do want to contribute to a project, fork and extend an app or fix a bug, we welcome pull requests from all.

If you do want to work with the project, it is important to note there are certain configurations that are not committed to Github for security and environment reasons. Should you need to get access to a local configuration file, please contact us on the developer live chat in the Developer Portal > Help section.

## Getting Started

### Pre-requisites

To get started working with Foundations, you will first need to have [Git](https://git-scm.com/), [NodeJS](https://nodejs.org/en/) and [Yarn](https://yarnpkg.com/) installed globally on your local machine. Currently, we use `yarn@2.4.x` and `node@14.x.x` internally however, other versions may well work for you.

For a clean build, then follow the steps below;

1. Clone the repo: `git clone git@github.com:reapit/foundations.git`
2. CD into the root of the project: `cd foundations`
3. Install dependencies `yarn`
4. Either: Obtain developer AWS Access Keys from a Reapit Admin and add to your bash profile as per instructions [here](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-shared.html) then run `yarn conf-all` to pull in remote configs from AWS Parameter Store
5. Or: rename `config.example.json` file (where relevant) for the package you are working on - see Environment and Config below for more details on this.
6. Add an NPM token scoped to at least private read to your bash / zsh profile in the format of `export NPMTOKEN="<<your_token>>"`. You can obtain one of these from any of the Reapit Platform Applications team.

### Environment & Config

Each of our applications that has environment specific or non secret configuration (API Endpoints, API keys, OAuth client ids, environment variables etc), has a `config.json` at the root of the package folder. These files are stored in AWS Parameter Store and are are either pulled at compile time and set on the server by the CI for Node projects, or for client side applications, injected at runtime into a `window.reapit.config` object.

Any secret config (that cannot be leaked publicly), we set in Github's secrets manager so we can reference in the CI only.

Internally we manage the non confidential config using our Config Manager [see here](https://github.com/reapit/foundations/tree/master/packages/config-manager) for info on how to do this yourself. If you are working internally on the project, you should follow these steps.

An example of the base config file is at the root of each relevant project (not all packages have a config), and named as `config.example.json`. If you are trying to build the apps yourself, you can rename this, place in the root directory, and add a values as required.

Typically you will need a `connectClientId`(this is the client id, you can see in the app detail modal when you have submitted your app), `connectOAuthUrl` and `connectUserPoolId` , as a minimum to make the app functional for development. These variables are used to populate the [Connect Session Module](/app-development/connect-session) that we use to manage the OAuth Flow in [Reapit Connect](/api/reapit-connect).

### Working with the Mono Repo & Yarn Workspaces

We use [Yarn 2.x (Yarn Berry), Workspaces](https://yarnpkg.com/cli/workspace) functionality to manage package and dependencies. If you are used to working with Yarn 1.x there are a number of fundamental differences to the API in v2. The main practical change is the way Yarn now moves all dependencies to the root node\_modules directory and loads them from a `.yarn/cache` directory at the root of the project.

This caching ensures much faster local and CI builds as well as more deterministic behaviour and some useful new features like [Interactive Upgrading ](https://yarnpkg.com/cli/upgrade-interactive)and [Workspace Management tools](https://yarnpkg.com/cli/workspaces/foreach).

Workspace packages are defined in the packages array in the root package.json of the project. When adding a new package to the repo you will need to it to this array for yarn to treat it as a workspace. Similarly, if you want to remove it from the project or disable it from the workspaces workflow, you should remove from this array.

From the root of the project, you can run Workspace commands on individual packages in the following format:

`yarn workspace <<packagename>> run <<command_name>>`

eg&#x20;

`yarn workspace developer-portal run start`

To run yarn specific commands you can use the following syntax:

`yarn workspace <<packagename>> <<yarn_command>> <<options>>`

eg

`yarn workspace developer-portal add react --dev`

You can of course just CD into a package directory and work in there as per any other JS/TS project.

We have worked to normalise our development workflows so that the majority of packages export the same predictable commands for building and running in both development and production modes.

Given that you are in a package directory you can run the following commands:

`yarn start` will get you up and running in dev mode - for web apps this will be a Webpack dev server at `localhost:8080`and for Node apps Serverless Offline at `localhost:3000`

`yarn test` will run unit tests in watch mode for the project - you can add add additional flags as per the Jest CLI API eg `--watch=false --ci --coverage` for running in a CI environment.

`yarn build` will bundle the code for production

`yarn lint` will lint the project, typically using ESLint

`yarn release` will release your app to a deployed environment in AWS, typically using [Serverless framework](https://www.serverless.com/) and by default to dev. If you want to deploy to production, add the `--stage prod` flag to this command.

`yarn publish` will publish the package to NPM, by default to the private registry unless the `--access public` flag is added.

All commands are always provided but where not relevant to the package they will just print to console `...skipping...`

If you want to run the same command on each package you can do this at the root of the project using the `yarn test-all / build-all / lint-all / conf-all commands.` These use the `yarn workspaces forEach` command to perform the same command on each package in the repo.

### Shared Scripts & Types

You will notice there are no dependencies at the root of the workspace and that many of the packages depend on each other. This is by design - packages should know about their own dependencies to allow maximum flexibility to upgrade packages independently. Packages that depend on other packages within the repo can reference each other using the `"@reapit/config-manager": "workspace:packages/config-manager"` syntax in your package.json.

Yarn will do the heavy lifting of resolving dependencies by package and we can use commands like `yarn dedupe` and `yarn upgrade-interactive` to keep things sane on a project wide basis.

Furthermore because yarn 2 has no `node_modules/.bin` directory, any executable from the yarn cli MUST be in scope in the individual package eg `webpack` and `jest`.&#x20;

To keep some centralised configuration for our scripts we have a package `@reapit/ts-scripts` that exports our global WebPack and Jest configs. Each package then imports them individually and can add any "special sauce" as required. The same applies to `ts-config` files which again inherit from the base at the root of the project.

Similarly, we have centralised our `@types/**` modules in a single `@reapit/ts-types` module to avoid type duplications eg 2 version of the React types that can cause compile time issues. We also have an internally generated types package `@reapit/foundations-ts-definitions` that contains the definitions for the API platform itself. These are auto generated from the Swagger definitions via a nightly cron job. [See here.](/app-development/foundations-ts-defintions)

## Workflow

### Github Issues & Projects

The starting point for any development work is to raise or assign a [Github Issue](https://github.com/reapit/foundations/issues) to yourself. The issue should be a descriptive as necessary for a future developer to understand or for a tester to properly validate.

We use labels heavily to categorise issues. Each issue should have either `bug` `feature` or `chore` added based on the type of work required. It should also have either a `back-end` label for API issues or `front-end` label for web / node application issue and where relevant, a label for services it will effect for example `marketplace` or `elements`.

{% hint style="info" %}
Raising an issue does not guarantee that we will work on it. In many cases we will ask for more information and in some cases we may close an issue if it does not fit with our roadmap. In all cases, we will update the ticket with an outcome so please keep an eye on it for updates.
{% endhint %}

When raising an issue, you should add a project to the ticket, either[ Back End Backlog](https://github.com/reapit/foundations/projects/6) or [Front End Kanban](https://github.com/reapit/foundations/projects/1). This will alert one of our Product Owners that the issue requires investigation and they will move it into one of our development streams if it is accepted and ranked by priority.

See the dedicated [Development Requests ](broken://pages/-MTzCNhRuWxZfj5frdpW)in these docs for more information on our product processes.&#x20;

{% hint style="warning" %}
Ensure a triage project is added to your issue to make sure we process it as quickly as possible
{% endhint %}

In all cases, the more information you can give us, the better. For features, please be descriptive about the expected / intended behaviour. For bugs, please give us detailed steps to replicate including device, environment and app / page / component / endpoint where relevant.

### Version Control

When working on the project, we ask that contributors follow a basic git flow, with `master` as the base branch;

* Branch names are in the convention of `feat/description-of-issue` `fix/description-of-issue` or `chore/description-of-issue` mapping to the common issue types we use in Github issues.
* Commits should also follow this pattern in the convention `fix: what I changed` `feat: what I changed` or `chore: what I changed` . It is helpful but not essential to include the issue number you are working on in your commit messages eg `fix: #123 what I changed`.
* To merge back into the base branch, raise a pull request against `master`. All checks should pass and at least two approvers are necessary to merge into base.
* Keep your branch up to date at all times with the base branch by `rebase` only, to keep the tree clean.
* On merging to base, use `squash and merge`, to keep the tree clean and to make rolling back changes easy.

### Github Actions, Serverless, AWS & Releases

All of our cloud infrastructure is in AWS. For releasing our code, we leverage [Serverless Framework](https://www.serverless.com/) where possible for it's convenience and clean, declarative code as infra approach. Under the hood it uses CloudFormation to spin up and tear down the infrastructure we need in AWS.

Anyone not familiar with Serverless and AWS Services should do some reading at this stage but the infra we use is declared for each project in a `serverless.yml` file at the root of each package. This is where you will add and remove required resources as required.&#x20;

For web applications, this typically means an S3 bucket with Cloudfront CDN on the front end and a DNS record in Route53. For Node services, typically we use Lambda, S3, DynamoDB, Cloudwatch and API Gateway. A basic template for deploying the various flavours of application is included in the apps generated by our app scaffolder.

When you are happy with your infra, you can either run `serverless deploy` locally to push to a development environment. On the CI this is mapped to the `yarn release` command. If you need to tear down your infra, you can do this using the `serverless remove` command. In all cases you will need to have the relevant [AWS credentials in your bash / zsh profile. ](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-shared.html)

We use [Github Actions](https://help.github.com/en/actions) for all our Continuous integration pipelines. You can see the various workflows being executed in [live time here](https://github.com/reapit/foundations/actions) and the [source files here](https://github.com/reapit/foundations/tree/master/.github).

The basic flow for all projects is that;

* **Build PR:** Build task runs to ensure the branch is sound.
* **Test PR:** Test, and lint tasks run to verify a PR. Runs in parallel with Build PR.
* **Release Dev:** Triggered on the successful merge of a PR, builds the project and releases to the relevant dev environment.
* **Release Prod:** Triggered by tagging a release in Github, again, test, build and lint tasks run and the `release-prod` task runs to deploy the relevant tagged project. The release tag should be raised [here](https://github.com/reapit/foundations/releases) and be in the format `<<package>>_v<<version-number>>` to trigger the production workflow.  Will release a single package to production and if relevant, publish to NPM>

### Definition of Done

As per the previous sections, all work on the project is performed against the spec as per a Github Issue ticket. A Github issue is considered ready to be moved to the `done` column only when the following checklist has been completed.

* The complete acceptance criteria or task list on the Issue ticket has been fulfilled. To be verified by a PO if appropriate.
* The feature has appropriate unit and end to end tests.
* The feature has been verified as working by a QA if appropriate.
* All tests and checks on Github are passing.
* The feature is up to date with the base branch.
* The feature has had at least one peer reviewer and that they have approved the feature for release.
* The feature has been merged and deployed into the master branch and it has successfully deployed to the development environment.

## Code Style & Conventions

### Linting & Formatting

The vast majority of base code style is enforced by [ESLint](https://eslint.org/) with sensible community presets from [TSLint](https://palantir.github.io/tslint/) rules, and [Prettier](https://prettier.io/). The linter runs in a pre-commit hook on staged files with an auto-fix flag set to address any trivial issues.

If you want to run the lint command manually, you can do this from the root of the project by executing `yarn lint-all.`

In addition to the lint rules, please also where possible, stick to the contribution guidelines below. These rules should be kept in mind when reviewing Pull Requests.

### Code Guidelines

* The codebase is almost exclusively written in [TypeScript](https://www.typescriptlang.org/), with the exception of some node scripts that handle deployment and tooling. This decision was taken because of the level of robustness and scalability of the language over vanilla JS and we ask that contributors favour TypeScript where possible for future development.
* Code should be functional in style rather than Object Orientated or Imperative unless there are no clean alternatives.
  * Use pure functions where possible to make them testable and modular.
  * Avoid mutating variables and the `let` keyword.
  * React Components should be stateless functional components where possible.
  * Avoid classes and stateful modules where possible.
  * Avoid React lifecycle hooks.
  * Keep all state in Redux and business logic as pure functions of Redux State.
  * The above rules can be relaxed for test scripts.
* React components should be templates, free of logic. This is because we aim to re-use code in the future in React Native Applications so by keeping the React layer as purely presentational.
* Presentational logic helpers should live in a utils file in the same folder as your component so they can be re-used agnostic of the template.
* Use Redux connect for nested components for better performance and reduced re-rendering over `prop drilling`. Use `React.memo` for the same reason and selectors if appropriate.
* Type-safe everything! Use `any` and `unknown` types only when there is no alternative - try to avoid `implicit any` - types should be documentation as code for the project. We can relax this as a convenience in test scripts.
* Where possible use auto generated types from Swagger documentation or GraphQL definitions to ensure shared contracts with front and back end. These auto-generated types live in the main types folder.
* Styled Components or CSS / Sass Modules are used for styling in all cases where a third party library (eg Bulma) is not used.
* Styled Components & CSS / Sass Modules where they are generic should be kept out of the main components folder - they should live in the main styles folder to reduce duplication.
* The styles project should make extensive use of variables and mix-ins for things like colours, layouts, font sizes, line heights and so on. This ensures re-usablility and maintainability.
* Where possible, use `rems or ems` over `px` as a unit for layout.
* Maintain where it makes sense to do so the separation of concerns laid out in the initial scaffold seen in the [React App Boilerplate](https://github.com/reapit/react-app) here. There are many TS projects in the company and they should all follow a broadly familiar structure and architecture.
* Make extensive use of the constants files for significant strings and other re-usable constant variables used in the app.
* When adding third party libraries to the project consider carefully the following;
  * Is this a trivial package we can easily write in house? If so, take the time to roll your own.
  * Is this library well supported, under active development and widely used in the community? If not, do not use.
  * Do we use a similar but different library for the same task elsewhere in the company? If so, use this library for developer familiarity and consistency.
  * Will this library impact significantly performance or bundle size eg Lodash or Moment? If so, consider carefully if it is necessary or if there is a better alternative.
* We have two kinds of tests; Unit tests with Jest and e2e tests with Cypress. For all new features an appropriate level of test coverage is an implicit part of the feature definition.
* For unit tests, the expectation is;
  * All functions / methods, especially utilities have i.o. tests, with internal conditional logic and edge cases tested.
  * All React templates have at least a snapshot, and any calls to action are tested to call their handlers with correct params.
  * Redux actions, reducers and sagas have test coverage for all cases.
  * Styled components do not require tests unless necessary, likewise constants and build scripts.
  * Tests should live in the same folder as their source in a `__tests__` folder.&#x20;
  * Mocks and stubs should also follow the same `__mocks__` & `__stubs__` pattern.
* For e2e tests, the expectation is;
  * Happy path user journeys are all tested through the app.
  * Calls to action are all tested, verifying an appropriate change in the state of the application is observed.
  * The page object model for selectors and methods is used to ensure re-usability.
  * The tests should not be excessive or flaky to ensure they do not block dev workflow.
* File naming should be `kebab-case` for `.js(x), .ts(x), .css` files, and indeed all files where possible. No use of capitals to avoid issues where Unix systems do not respect casing when a file name is changed.
* Exports from files can be either as variable or default exports, but please stick to naming the object before using `export default` to avoid anonymous module names in stack traces and React dev tools.

### Styling

We support two styling methods across our projects; [SASS with CSS Modules](https://sass-lang.com/) and [Linaria](https://github.com/callstack/linaria) (CSS in JS). For new projects we favour Linaria and are aiming to eventually deprecate / refactor our SASS from our projects.

By convention, we store any Linaria components that are specific to an individual component in a sub folder of that component called `__styles__` however, if a style is re-usable, generic or global to the project, please use the `src/styles` directory to reduce duplication.

For components that are genuinely generic across the estate, please take the time to add to the [Elements](/app-development/web#elements) project as a Storybook item so we can use it again. If you suspect you may be writing a common component from scratch, it is likely it will already exist in Elements so please take a look if there is anything that can be re-used or adapted with a modifier class.

Our overriding aim is to write as little CSS as possible and focus on re-usable components, both to save time and to develop a consistent look and feel across the estate.

### Testing

Our code has a lot of automated testing, mostly unit tests, although we have some E2E tests and this is something we will be expanding going forward. In the previous section you saw the commands exported from each of the projects to run the test suites so this section deals with some basic conventions for working with tests on the codebase.

We use [Jest](https://jestjs.io/) for our unit testing, with [Enzyme](https://airbnb.io/enzyme/) for rendering React components where relevant. If you are not familiar with these libraries, we would urge you to do some reading before getting started. Our goal is that each of our packages, where relevant, should have \~90% coverage of functions and lines. Whilst this target is an arbitrary value, the desired outcome is a high level of confidence in our CI / CD pipeline which means we can deploy straight to development and daily to production.

By convention, we keep our test scripts in a sub folder of the source code called `__tests__` with the same file name. Where we use mocks and stubs, as with tests, they live in the same folder of the source code with the same file name and sub folder convention `__stubs__` and `__mocks__` .

For React components as a bare minimum, we expect a snapshot of the shallow rendered component, with snapshots saving to the `__snapshots__` sub folder of the component.

End to end functional tests are all written using the excellent Cypress framework. Whilst it does not support cross browser testing for older browsers, we feel it is a decent tradeoff owing to the speed, developer experience and reliability of the tests over conventional Selenium / Webdriver tests.

Where relevant, files e2e test specs are placed in the `src/tests/cypress` folder of the package. We use the `Page Object Model` pattern, storing anything related to a specific page; selectors and actions, to make them more re-usable and modular.

When raising a pull request, please ensure that existing tests are passing locally and that where relevant, new tests are added to maintain our overall coverage levels.


# Website Development

A guide to assist website developers when working with the Foundation API

#### Quick Start

To get a property feed up and running within a couple of minutes, we suggest you first watch [this short video](https://www.youtube.com/watch?v=EJWB5u1ja_U) and visit our [code examples repo](https://github.com/reapit/foundations-code-examples) with a boilerplate example in Node.

It is important to note though, these guides are intended to get you up and running as quickly as possible. You should optimise your implementation to minimise API consumption charges and to give the best UX for your customers.

{% hint style="info" %}
Fetching Properties from the API for each page render is not an efficient way of building a website on Foundations and can result in unnecessary API consumption charges
{% endhint %}

#### Suggested Architecture

In the code example, we fetch a list of properties on the fly. This is fine if you need the data to be the latest in our DB at the exact moment of execution however, practically for serving a website, it is expensive in terms of processing on the server, http round trips and financial cost by API calls.

So how do I build on the website feed example?

The simplest reasonable design pattern is as follows;

**1. Seed your application**

Fetch all properties and embedded property images in a paged response, and commit to a database of your choosing. The query will be paginated at a maximum of 100 so you will need to do this step in a few requests, depending on your client.

The following query will fetch all properties where;

* The selling status is `forSale` - you can specify other statuses as you wish eg `underOffer`
* The letting status is `toLet` and `tenancyCurrent` - as above, you can specify additional statuses
* The customer has specified `internetAdvertising` is true
* The page size is 100, and the page number is 1 - you will need to increment the page number until no more properties match your query
* Embed property images. This will return all property images associated to each property. You should store these in a separate location in your database.

```ts
'https://platform.reapit.cloud/properties?sellingStatus=forSale&lettingStatus=toLet&lettingStatus=tenancyCurrent&internetAdvertising=true&embed=images&pageSize=100&pageNumber=1'
```

When you have seeded your DB, you can use this data to serve your website, removing the need to make a round trip for the properties from our APIs each time, thus keeping your costs to a minimum.

**2. On a schedule, fetch the properties that change**

When you have your initial seed, you will need to update your data with any new or changed properties. This should be done with a scheduled job that queries both the properties and property images that change or are created, matching your filters.

The following query will fetch the properties where;

* The selling status, letting status, internet advertising and paging are as per the seed at stage 1
* Images **are not** embedded in the property as it would fetch all images regardless of whether they change or not
* The modified from date covers the last hour. This assumes that you will run your scheduled job every hour - you can adjust the timeframe based on how up to date you need your data to be however, more frequent fetching will result in greater cost.

```ts
'https://platform.reapit.cloud/properties?sellingStatus=forSale&lettingStatus=toLett&lettingStatus=tenancyCurrent&internetAdvertising=true&pageSize=100&pageNumber=1&modifiedFrom=2022-05-26T10:38:06.581Z'
```

The following query will fetch the property images where;

* The paging is as per the seed at stage 1
* The modified date from matches the last hour as per properties
* The `propertyId` values (represented as foo, bar & baz), are the ids of the properties in your DB. You should break the query into batches of 100 propertyIds at a time to avoid timeouts and use paging to return all images changed.

```ts
'https://platform.reapit.cloud/propertyImages?propertyId=foo&propertyId=bar&propertyId=baz&pageSize=100&pageNumber=1&modifiedFrom=2022-05-26T10:38:06.581Z'
```

In both cases, when you have received your updated properties, you should update the corresponding records in your database.

**3. Housekeeping**

Each day (or on a schedule of your choosing), we would recommend checking that your property data has not gone stale. This can be done by fetching each property by id in batches of 100 using the below query where the ids of the properties in your database are represented by foo, bar and baz.

```ts
'https://platform.reapit.cloud/properties?id=foo&id=bar&id=baz'
```

On fetching of this request, you should validate that the returned data is still valid i.e. it matches your `forSale`, `toLet` filters and so on. Records that are no longer valid should be remove from your database.

#### Estimating Charges

You will be billed monthly for using the foundations API on a consumption model, per API call. The cost per call is on a sliding scale, getting cheaper the more calls you make. [see here](https://foundations-documentation.reapit.cloud/developer-terms-and-conditions#schedule-2-fees) for details of these changes.

Consumption may vary significantly from customer to customer, depending on how they use Reapit Software however, we have attempted to give you an illustrative example, based on real world numbers from an SME Agent, with 8 offices.

{% hint style="warning" %}
**Actual costs will vary from customer to customer based on your product and implementation decisions**
{% endhint %}

Assuming you implement the architecture model above, the cost calculation will approximate as below;

**Month 1 seed calls**

```
p = initial seed of live properties for agent = 700
i = average number of images per property = 15
n = number of paged items per API call = 100

Calculation: ((p / n) + (p * i)) / n

Initial seed calls: (700 / 100) + ((700 * 15) / 100 = 112 API Calls
```

**Rolling monthly calls**

```
p = average number of properties in database = 700
i = average number of images changed per hour = 100 (30 actual, but anything up to 100 will be charged as 1 call if paging set to 100)
c = average number of properties changed per hour = 100 (30 actual, but anything up to 100 will be charged as 1 call if paging set to 100)
n = number of paged items per API call = 100
d = number of days in a month running scheduled job = 31
h = hours in day running scheduled job = 24


Calculation Scheduled Calls Per Month: ((c / n) + ((p / n) * (i / n)) * h ) * d
Calculation Monthly Housekeeping Calls: (p / n) * d

Scheduled Calls Per Month: ((100 / 100) + ((700 / 100) * (100 / 100)) * 24) * 31 = 5952 API Calls
Monthly Housekeeping Calls: (700 / 100) * 31 = 217 API Calls

Total Rolling Monthly Calls: 6169 API Calls
```

**Costs**

As per above, API calls are charged on a sliding scale and get cheaper the more calls you make.

Based on this example, basis 2 endpoints (properties and property images), you would be charged as follows:

```
1000 calls @ £0.01 = £10
1500 calls @ £0.008 = £12
2500 calls @ £0.006 = £15
1169 calls @ £0.005 = £5.85

Ongoing Total Calls: £42.85

Initial Seed Month 1: 112 calls @ 0.005 = £0.56
```

**Managing Costs**

As previously stated, we based these numbers on a real world example of an SME agent with 8 offices and around 700 properties on their website. Your use case may differ significantly and adjusting the variables will effect your calls and therefore costs significantly.

Before starting work on a website project, we urge developers to consider the ongoing costs incurred and how you can optimise your code to minimise these costs.

For example, we have assumed updating the website every hour, 24 hours a day, 7 days a week. You can halve you API calls by only updating 7am - 7pm during working hours, and further reduce them by not updating on a Sunday.

Perhaps you don't need the site to update every hour and every two hours is adequate. In this case, simply adjust your scheduled job and the date time range of the modifiedFrom filter.

Maybe you don't need 700 properties on your site, in this case, you can combine API filters or limit the number set for internet marketing inside AgencyCloud, with a corresponding impact on calls and cost.

Conversely, perhaps you need updates every 10 minutes, 24-7. In this case, we would urge you to consider if the overhead is represents value for money given the increase in incurred charges.


# IaaS

Infrastructure As A Service platform

### Introduction

Infrastructure As A Service (IaaS). The Reapit IaaS is a platform for Reapit customers to host their applications.

Reapit Developers can host their React applications (Node apps coming soon), on Reapit's hosting, saving your developers time in setting up these solutions themselves.

You will soon be able to build and deploy fully functional Reapit Apps both on the front end and back end offering full functionality of the Reapit Platform for any requirement.\
\
Think of Reapit IaaS as CI/CD pipeline for your Reapit applications that also includes hosting.

### Public Beta

The IaaS services are part of a public beta that needs to be enabled by one of our team for your Developer Organisation.  If you are interested in trialing this service, please drop us a line at [**iaasbeta@reapitfoundations.zendesk.com**](mailto:iaasbeta@reapitfoundations.zendesk.com) to join the waiting list.

We will be inviting developer organisations in slowly while we scale up the infrastructure required to power the service so please be aware, whilst we will confirm your interest right away, it may take some time to get you live.&#x20;

Please also be aware that whilst the service is free in Beta, charges will apply when the service goes to full production. We will advise you in advance of this prior to any charges being incurred.

### Features

#### Hosting

The Reapit IaaS Platform offers hosting for your JavaScript single page application in our AWS infrastructure. In future iterations, we will also support NodeJS.

#### Domain

Once you've created a pipeline using the Reapit IaaS Platform. The Pipeline will be assigned a sub domain on the Reapit cloud url in the format: `https://{sub-domain}.iaas.paas.reapit.cloud.`&#x20;

#### SSL Certificate

The domain supplied with your IaaS hosting will include an SSL Certificate making your application more secure. Enabling the `https` protocol.

#### Real time updates

The Reapit IaaS Platform offers real time updates on your Applications Deployments via the CLI or the Developer Portal.

#### Rollbacks and Version control

The Reapit IaaS Platform enables Reapit customers to control their deployments by redeploying previously deployed versions. Rollbacks and targeted version deployments can be trigger via the CLI. In future versions we will support this in the developer portal too.

#### Deploy from your repository&#x20;

#### Github

Install our Github App and grant the Github App permission to your desired repository and use your repository's commit push actions to handle your deployment triggers for you.

#### Bitbucket

Install our Bitbucket App/Plugin and grant the Bitbucket App/Plugin permission to your desired repository and use your repository's commit push action to handle your deployment triggers for you.

### Terminology

#### Pipeline

Pipelines are configurations used to deploy applications to our infrastructure. A pipeline can be created via the developer portal or via CLI.

#### Deployment

A pipeline Deployment is an individual deployment made using a pipeline. The pipeline holds all the configurations such as repository and hosting location. A Deployment is an individual process made to publish your given application to the configured hosting.

#### Release

A Release is almost synonymous with Deployment however Release can be used to describe the trigger of making a deployment such as Release zip and Release Repository commands found in the CLI.

#### CLI

The Command Line Interface tool will enable Reapit customers to create, build, configure, deploy, rollback and manage deployments to the Reapit IaaS Platform.\
\
The CLI tool can be downloaded by those with permission and installed. Once installed you'll need to obtain an api-key from the Reapit Foundations team for the CLI to be authenticated with the IaaS platform.

###


# Custom Domain

Custom domain configuration documentation.

IaaS (Infrastructure as a Service) is a Reapit internal tool for hosting and deploying single page web apps. The aim of IaaS is to provide engineering teams with a platform allowing apps to be deployed quickly without needing involvement from other teams.

Developers can host their React applications on Reapit infrastructure which negates the need to setup project specific infrastructure.

The guide below assumes you are familiar with the [Vite Starter Template](https://foundations-documentation.reapit.cloud/app-development/vite-template) for React

### Creating and Configuring a Pipeline (App) <a href="#creating-and-configuring-a-pipeline-app" id="creating-and-configuring-a-pipeline-app"></a>

**What is a Pipeline?**

Each application you want to deploy with IaaS has a pipeline. Think of this as a CI/CD runner for your app, that responds to events in GitHub, such as a pull request being merged. These events will trigger a deployment which contains four distinct stages:

1. Download Source - the source code is downloaded from GitHub to the IaaS runner environment.
2. Install - any dependencies are installed. As part of the pipeline configuration you specify which package manager you are using, and the IaaS runner will execute install for that package manager (ie `yarn install` when the package manager is set to Yarn)
3. Build - the project gets built. The IaaS runner will execute whatever build command you specify in the pipeline configuration for the chosen package manager (ie `yarn build`)
4. Deploy - the project gets deployed. The IaaS runner will take the built deployment bundle and host it on a dedicated domain which is a system generated web address. Custom domains can be associated to your IaaS environment so more friendly public URLs are available for us.

> IaaS is currently deployed to the eu-west-2 region. As it uses global Cloudfront, apps developed in other regions can still be deployed using this feature and will be served at the edge for low latency, but your pipeline needs to be configured in the Europe DeveloperPortal

**Pipeline Creation**

A pipeline requires a *Client Side App* to be created from the [DeveloperPortal](https://developers.reapit.cloud/). A newly created *Client Side App* will automatically trigger the creation of a pipeline which will have a status of *Pre Provisioned*, meaning that it’s ready for use.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FWYZVvEe8MS5KyxVhH6X4%2Fimage.png?alt=media&amp;token=ba4f7f7f-2d42-4e7f-8195-b03021877cd9" alt=""><figcaption></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F94rck7s1OZJ0yVlsUh2r%2Fimage.png?alt=media&amp;token=e4f3ef67-48ec-4d3e-b09d-6baf04fd66cd" alt=""><figcaption></figcaption></figure>

**Configure Pipeline**

Before configuring your pipeline, make sure the Reapit GitHub app is installed the repository or organisation you wish to use IaaS with. For information about how to do this, [click here](https://reapit.atlassian.net/wiki/spaces/FOUN/pages/2807955545/IaaS+Documentation#Installing-the-Reapit-Github-App-to-your-repository)

The Configure tab is used to link your IaaS pipeline to your GitHub repository, and setup the commands which will be executed by the IaaS runner environment.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fx0m5Vx6XgUwnOKX08u1j%2Fimage.png?alt=media&amp;token=243003b2-8e61-4a07-80ff-dc296bd5fb81" alt=""><figcaption></figcaption></figure>

The name of the pipeline will default to that of your app. As this is a system generated name, you may want to change this. It’s useful to ensure you can identify a pipeline from the main IaaS page, accessed from the top navigation menu in the DeveloperPortal

The deployment branch is the name of the branch in your GitHub repository that should invoke the IaaS pipeline runner when anything is pushed to that branch. Typically this will be main or master, but you may also have separate development or feature branches that you wish to deploy. Different environments (ie Development and Production) should use different apps in the DeveloperPortal which would have isolated pipelines with different *Deployment Branch* configurations.

Next, attach the pipeline to your GitHub repository by clicking the *GitHub Repository* field. A modal will appear that will allow you to sign into GitHub and select from the list of repositories you have access to. If you have access to repositories across different GitHub accounts - for example where you are a collaborator on an external repository - it will also be listed here.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fa3li6uqpl18FQ4uWCE4h%2Fimage.png?alt=media&amp;token=ba0b45ba-f719-41b5-95d5-f0b96188a157" alt=""><figcaption></figcaption></figure>

Clicking the *Login with GitHub to continue* button, you’ll be navigated to GitHub where you’ll be asked to select your the user you wish to authenticate with if you have multiple active sessions in your browser:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F7VO51DGk3rOlexoW0Yg0%2Fimage.png?alt=media&amp;token=27b2f05a-41cf-4797-b3fd-eff30ca8fba0" alt=""><figcaption></figcaption></figure>

Once you’re logged in, you’ll be navigated back to the pipeline you were configuring. The repository selection modal will appear again and show you the GitHub accounts available to your logged in user, based on where the Reapit GitHub app is installed:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FhdxXdxEIP6eaVGiSOM5n%2Fimage.png?alt=media&amp;token=f695993d-0128-4efa-9588-5bce2ef91fc5" alt=""><figcaption></figcaption></figure>

Once you’ve selected an installation, you’ll be able to select a repository attached to that installation.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FIlpqqOUBTAWBWuPPamS5%2Fimage.png?alt=media&amp;token=549d8c56-05c1-4d6e-8c9d-14254a9366a8" alt=""><figcaption></figcaption></figure>

Next, select the *Package Manager* that your project uses. Typically this is Yarn or Npm, and it’s recommended you configure the same package manager as you use locally for the project.

The build command defines the command that the IaaS pipeline will execute to build your deployable app bundle.

The build directory defines the directory where the IaaS pipeline will look for deployment assets that have been built as part of the build process.

Don’t forget to hit *Save Config* after you’ve finished configuring the pipeline.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FAiIQrxmAuhVelFtuPwJl%2Fimage.png?alt=media&amp;token=494e8e17-4946-478a-809b-956011a82d5f" alt=""><figcaption></figcaption></figure>

### Installing the Reapit Github App to your repository <a href="#installing-the-reapit-github-app-to-your-repository" id="installing-the-reapit-github-app-to-your-repository"></a>

**Reapit Internal users can skip this step as the app is installed Globally in our Enterprise tenant - if there are any issues with this, please contact an admin.**

Our [Github app](https://github.com/apps/reapit) is the glue between the IaaS system and GitHub. You can able to install it for all repositories or specific repositories in an account or organisation. On the app page on GitHub, if you have permission to do so, you’ll see a *Configure* button which will enable you to configure your repositories. Please note that the app is installed globally in the *reapit-global* enterprise organisation.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FFnPCIDbdC1R3h6DhA9pz%2Fimage.png?alt=media&amp;token=51418c97-921d-41e9-85ed-e70f9c2b7e73" alt=""><figcaption></figcaption></figure>

Once you’ve selected your installation you’ll be prompted with the app settings page where you’ll be able to find the repository access section. Here you’ll be able to configure which repositories the Reapit App has access to.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FAVsgoDPb3LE0Nd4qK2wC%2Fimage.png?alt=media&amp;token=59dd40f4-41e7-40f9-b728-8229353838d3" alt=""><figcaption></figcaption></figure>

> Within Reapit Github Organisations a relevant admin will be required to manage repository access.

### Customising DNS <a href="#customising-dns" id="customising-dns"></a>

When creating new pipelines, a system generated DNS name will be used when deploying your app for the first time. This is typically in the format *foo-bar.iaas.paas.reapit.cloud*. It’s likely you will want to customise this so that more friendly domain names can be used externally.

To setup a custom domain, use the *Custom DNS* tab which is available on the IaaS Pipeline page for your app in the DeveloperPortal. You can use external domains or the existing *reapit.cloud* domain. Please note that only employees with the Reapit Connect group membership `FoundationsDeveloperAdmin` can create custom DNS configurations. Administrators can promote users as required in the [DeveloperPortal](https://developers.reapit.cloud/settings/members).

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FGmzsqiPmVpoUZwFEoqrt%2Fimage.png?alt=media&amp;token=57731463-e77a-4d7e-b1b9-bc47b9d67bf3" alt=""><figcaption></figcaption></figure>

Clicking *Setup Custom DNS* will present the setup modal as shown below:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fq9DVynkBF3HobX86KEHt%2Fimage.png?alt=media&amp;token=cc104dcb-9b2a-4c2f-89d4-7d1d6e55a877" alt=""><figcaption></figcaption></figure>

Enter the custom domain you wish to use for your app and click *Next*. IaaS will start to provision SSL certificates and generate DNS records that need to be added to your DNS database. If you are configuring a `reapit.cloud` domain the creation of CNAME records will be handled for you. This process involves a PR to the DevOps team to setup the DNS records in the right namespace. Once this is done, the *Certificate Status* will change to *Verified*. Any other domain requires you to setup the records as described onscreen yourself.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FJRdjLLpKuM1bbX0SpxXP%2Fimage.png?alt=media&amp;token=ad54fac4-7264-411a-9de7-7a1b8afc9bde" alt=""><figcaption></figcaption></figure>

Once the *Certificate Status* changes to *Verified*. you will be able to reach your deploy app at your chosen domain.

### Demo <a href="#demo" id="demo"></a>

You can watch a demo of IaaS in action below

{% embed url="<https://youtu.be/nKeTaD-evzM>" %}

### FAQs <a href="#faqs" id="faqs"></a>

* Q: I’ve created a custom domain but need to change it. What should I do?\
  A: You will need to delete your pipeline completely. This process can take a number of minutes, after which you can setup a brand new one as needed
* Q: I’ve created a custom domain using `reapit.cloud` but the Certificate Status still says Unverified after a number of days. What should I do?\
  A: The certificate validation process requires certain DNS records to be present. Until the certificate validation process can access these records, it will not issue the certificate for your chosen domain. When using the `reapit.cloud` domain, the IaaS backend opens a pull request (PR) in the [UK DevOps GitHub repository](https://github.com/reapit-global/uk-devops-infrastructure-core-cdk) to setup the DNS records required by this process. It’s likely that this PR has not yet been merged and changes deployed. Once this happens, the certificate should validate so that your custom domain can be used
* Q: I cannot see the IaaS options in the DeveloperPortal. Why is this?\
  A: As the DeveloperPortal is used by both internal and external developers, access needs to be granted to your developer organisation. Most colleagues will already be part of an organisation that has access, but if not, please [click here ](mailto:appsupport@reapit.com?subject=IaaS%20Access%20Request\&body=Please%20can%20you%20give%20me%20access%20to%20IaaS.%20The%20email%20address%20I%20use%20to%20log%20into%20the%20DeveloperPortal%20is%20%5Byouremail%40reapit.com%5D.%20I%20am%20working%20with%20the%20%5BEnter%20Team%5D)to send an email.
* Q: My deployment keeps failing. Who should I contact?\
  A: When deployments are in progress, logs will become available on the *Deployments* tab. These can indicate problems with your build process. If you are unable to resolve the problem, please [click here](mailto:appsupport@reapit.com?subject=IaaS%20Deployment%20Problem\&body=I%20am%20having%20an%20issue%20with%20IaaS.%0D%0A%0D%0AThe%20issue%20is%20%5Binsert%20summary%5D%0D%0A%0D%0AApplication%20Details%3A%0D%0AAppId%3A%20%5Bapp%20id%20from%20DeveloperPortal%5D%0D%0APipeline%20Name%3A%20%5BName%20of%20IaaS%20pipeline%5D) to send an email


# Developer Portal (Beta)

Pipeline management within the Developer Portal

If you prefer a GUI to manage your deployments over a terminal based CLI, you can manage this from within the Developer Portal itself. When you have been enabled as part of the public beta, you will see both a top level navigation item `IaaS`, that gives you an overview dashboard of your pipelines, plus, each app has a Pipeline configuration page.

The first step to deploy an app is to visit the app detail page in the developer portal at `/apps/:id` If you are part of the beta and have pipelines enabled, you will see a new "Pipeline" menu item for your client side authenticated apps.

### Getting Started - Pre Existing Apps

For apps that pre-exist the IaaS service, this was not possible so you will see this screen:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FeV7v7LJ3mU5zNeAfOXh4%2Fimage.png?alt=media&amp;token=06c2c20e-6661-4492-b96c-12ffa7925d17" alt=""><figcaption></figcaption></figure>

From here you should hit "Create Pipeline" to take you to the new pipeline page.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FZ6MideQzQnpwhJ98TQhb%2Fimage.png?alt=media&amp;token=5ffb469f-5767-4570-9b47-e5a81df59a6d" alt=""><figcaption></figcaption></figure>

From here, you need to tell us about your application, the repo (we support Github and BitBucket), the main branch, the command in your package.json that builds the app and the directory your assets are output to.

On saving this config, you have pre-provisioned an app and you will return to the Pre provisioned app screen.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FRCXndcliGUtzKUmFAvq0%2Fimage.png?alt=media&amp;token=a0b27c72-3692-47ea-889f-5bdee1233fbd" alt=""><figcaption></figcaption></figure>

You should now hit "Provision", to build your initial infrastructure on our services. This can take a minute or two. You can also move on to the [Next Steps](#next-steps-all-apps) section below.

### Getting Started - New Apps

If you created a new application, we pre-provision a Pipeline for your application by default. Visiting the "Pipeline" tab you will see this page:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FsvJ2cag6a7DRk36IUDph%2Fimage.png?alt=media&amp;token=69f789ff-eec3-4b04-b00f-8ed5eb44766a" alt=""><figcaption></figcaption></figure>

Note the state of the application is "Pre provisioned". This means we have a shell pipeline and have reserved a domain name for your app in our infra.

{% hint style="info" %}
Please be aware, there is sometimes a slight delay between creating an app and the pipeline being available. We are actively working on a fix for this but as a workaround if you don't see the pipeline immediately, a page refresh will solve.&#x20;
{% endhint %}

The first step is to provision your app by hitting the "Provision" button. This will build your initial infrastructure on our services and can take a minute or two.&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FkCKPk9clWMKekhvm8dXU%2FScreenshot%202022-06-17%20at%2012.24.22.png?alt=media\&token=c9a88180-fe7f-49e2-9904-a623f3684530)

The next step is to configure your app by clicking on the "Configure" tab or the left hand side button.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F1Mlspo9YPNfTAXkIftXw%2FScreenshot%202022-06-17%20at%2012.27.41.png?alt=media\&token=39b2e6b2-5097-41d5-b31f-5420ed618c08)

On the configure screen, you need to tell us about your application, the repo (we support Github and BitBucket), the main branch, the command in your package.json that builds the app and the directory your assets are output to.&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Frn9B2jjUaTyzuFKAn6IP%2Fimage.png?alt=media&amp;token=2262f731-fbb6-4dc5-9eff-7bf1a8453526" alt=""><figcaption></figcaption></figure>

Hit save config and return to the deployments page. You can then move on to the [Next Steps](#next-steps-all-apps) section below.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F49rJJVpeS4UQ2sDNoOA1%2FScreenshot%202022-06-17%20at%2012.30.23.png?alt=media\&token=826d20c6-8be0-4447-8467-102efab0f744)

### Next Steps - All Apps

When you have done this, if your app is on Github, you will need to install our Github App from [this page](https://github.com/apps/reapit) following the steps to configure for your repo. This gives us the permission to pull from your repo and receive webhooks that inform us when you git push to your main branch.&#x20;

For Bitbucket the process is the same but you will need to install the [dedicated app here.](https://bitbucket.org/site/addons/authorize?addon_key=reapit)

{% hint style="info" %}
You should only install the Github / Bitbucket app for a single repo, not your whole organisation as it sets up a webhook on an app by app basis. If you delete your app or pipeline, and set up a new one for your repo, you need to uninstall and re-install the Github app each time.&#x20;
{% endhint %}

Having installed the app, you are ready to do your first build. Hit the "deploy" button.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fz92ocGmXf92pVDQ10imH%2FScreenshot%202022-06-17%20at%2012.32.06.png?alt=media\&token=2c8ce720-123e-4559-8f8f-8dcdab8eacc7)

The page will start to update in live time as we pull, build and deploy your code.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FToHE269h42vBpgOFy2lj%2FScreenshot%202022-06-17%20at%2012.34.28.png?alt=media\&token=f8452808-d17b-4471-b9f4-13bb81128f8a)

And that's it! On completion of all the steps, you can then visit your deployed application using the Location Link.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Ful4uqo53h4B262CcrYKS%2FScreenshot%202022-06-17%20at%2012.38.26.png?alt=media\&token=ab017aca-f65a-443e-a295-b983b606274c)

### Additional Features

#### Logs

You can view the logs of your deployment to check for any build errors. These are visible from the slide down in the deployments table you can see above. They will be in plain text form and will open in a new tab in your browser to download.

#### Pushing to master

When you have set up your pipeline, you can trigger a build by simply pushing to master (or your default branch). This is especially useful for setting up CI / CD pipelines with third party providers, if you want to trigger a build on Pull Requests, or if you need to do a local deployment without logging into the dev portal.

Deployments from the master branch are noted as 'Git pushed' in the deployments table.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F0g8sCtjmxzCiNGOvuwQK%2FScreenshot%202022-06-17%20at%2012.41.18.png?alt=media\&token=8e9fffef-1f44-40c7-8035-4f8c66b0ee76)

#### Deleting Pipelines

You can delete pipelines from the pipeline deployments page however, a couple of things to note.&#x20;

Firstly, it will tear down all of your current infra and delete the pipeline record. This means any testing or users that are relying on your deployment will not be able to access the url again. You can create a new pipeline but you can't specify the same location (url), as before.

Secondly, the command issues a request to delete the infra. This process is quite lengthy so you should check back after a few minutes to verify everything has been torn down. See below for an example of a pipeline in it's deletion state.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FtAAZlD216SxblLao8JdL%2FScreenshot%202022-06-17%20at%2012.44.29.png?alt=media\&token=1c28f136-64c3-4dc3-ad18-c94513655f80)

#### Environment Variables

You can add your Environment variables for your application here. If you supply any key value pair we will write them to the process.ENV object at compile time when building your app.

You can then reference them in your code with the line, where `FOO` is the key of your variable.

`process.env.FOO`

All variables are stored in a secure and encrypted format however, if you are building a web app environment variables are inherently insecure. As such, you should only store values that can be exposed on the client side.

Currently we do not surface your variables over an API when you have stored them for security reasons. If you need to confirm a variable value, we would advise updating it and re-deploying your app.

See below for the Environment Variables UI:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F5RCh65mDptL2nObLjShE%2Fimage.png?alt=media&amp;token=b6da69ae-4bf6-40c5-abfa-387b60634b04" alt=""><figcaption></figcaption></figure>

#### API Keys

API keys are used by the Reapit CLI to authenticate against our Pipeline endpoints. You don't need them unless you intent to use the CLI. For more on this see [Configuring the CLI here](/app-development/iaas/cli-beta#configure-the-cli)

### Pipeline Dashboard

From the top level nav you can also view the IaaS pipeline dashboard that gives you an overview of the current statuses of all your app pipelines. By expanding each row, you have quick links to the deployed app, your Pipeline config and the recent app deployments.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FPojUmq5Rv1LpW2ymKWcH%2FScreenshot%202022-06-16%20at%2016.05.15.png?alt=media\&token=6bc102a0-629c-441b-8ba8-d2a0b36663eb)

### Troubleshooting&#x20;

We will try to update this section regularly with frequently asked questions while we are in beta.

* **My deployment fails immediately after hitting deploy.**  First check you have the Github app installed. Then check you have installed for a single repo, not your whole organisation as it sets up a webhook on an app by app basis. If you delete your app or pipeline, and set up a new one for your repo, you need to uninstall and re-install the Github app each time. Secondly check your config is correct from the "Configure" tab, specifically the repo url. Any errors in the url will mean we can't find or build your app correctly.
* **My deployment fails at one of the build steps.** This is likely because of an issue building you app itself. Check the download logs button in the expandable pipeline table row for build errors and check if you can replicate locally. Also check your config to ensure the build directory, build task and package manager are correct. Any errors here can cause build issues.
* **My app deployed but I see a re-direct mismatch error when first clicking on the link.** We update your app re-direct uris when provisioning a pipeline however, if this fails you may need to update them manually to the location of your deployed app from the `apps/:id/edit` page,  authentication tab. Also, check the client id for your app is the correct one for your pipeline. Redirect URIs are specific to client ids so must match the data we hold on your app.


# CLI (Beta)

A Command Line Interface tool for interfacing with Reapit's IaaS platform

The Command Line Interface tool will enable Reapit customers to create, build, configure, deploy, rollback and manage deployments to the Reapit IaaS Platform.

### Installing

With NodeJS installed, use npm or yarn to install the Reapit CLI tool globally.

```bash
$ npm i -g @reapit/cli
```

### Configure the CLI

First visit the developer portal and load any app page. Visit the pipelines page, and on the left hand side click the "API Keys" button to open a modal window. Click "Create API Key" and copy the result to your clipboard. You can add multiple API keys from this view and delete them as required.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FfXsyXaSqJH8L7q5jqh5d%2FScreenshot%202022-06-17%20at%2012.46.49.png?alt=media\&token=a2875fc7-6a14-4784-abd7-24653a7f8ebd)

Once you've obtained an api-key. You can set this up with the Reapit Cli by running:

```bash
$ reapit config
```

This command will then prompt you for the input of your api-key

{% hint style="info" %}
When prompted about what type of config to make. Choose global for general projects. Project Reapit config is designed for multiple Reapit accounts.
{% endhint %}

Just to make sure you've got your api-key setup and ready to go, run the `reapit config` command again and choose `show` to see your currently set config.

### Bootstap React App

Get started building your react app as quickly as possible by using the Reapit Bootstrap app to create your React App in your current working directory, complete with all the tooling from our Create React App template.

```
$ reapit bootstrap my-new-reapit-app react {client-id} {user-pool}
```

{% hint style="info" %}
Make sure to add the client-id from your app and the required user-pool
{% endhint %}

### Bootstrap Node App (coming soon)

This command will be used to generate a node web application to be used with our IaaS platform. Not currently supported but on our roadmap.

### Pipeline Commands

The CLI supports a number of commands to manage a pipeline for your application.

#### List Pipelines

Run the below command to see a list of pipelines that are currently authorised for your given api-key.

```
$ reapit pipeline list
```

#### Create a Pipeline

Use the below command to start creating a pipeline. The Reapit CLI will then prompt you for required options and configurations.

```
$ reapit pipeline create
```

Required options you will be asked for

* App Id
* Project Name
* Deployment Branch (from your repository)
* App Type (react or node)
* Repository url (a default url will be supplied if a repository is found in cwd)
* OutDir (your application's build directory)
* Build Command (the command used to build your application)
* Package Manager (yarn or npm)

This command will then give you live updates of the IaaS platform creating your pipeline and the current state as it provisions your pipeline.

#### Editing Pipeline Config

This commands allows you to update the reapit pipeline config which will then sync with our IaaS platform.

```
$ reapit pipeline edit
```

#### Link an existing Pipeline

Pipelines can be automatically created when creating an app. This command allows you to download an existing pipeline's configuration in your current working directory.

```
reapit pipeline link {pipeline-id}
```

#### Delete Pipeline

Simply run the below command when in the directory with the Reapit pipeline config file output at the pipeline create stage.

```
reapit pipeline delete
```

### Release Commands

Commands that manage and trigger the deployment of your code to our infrastructure. You will need to have configured a pipeline before releasing your code.

#### List Releases

Use the below command to list out deployments made on a pipeline within the cwd.

```
$ reapit release list
```

#### Get the Current Release

Use the below command to deploy a previously deployed version.

```
$ reapit release version
```

This command will list out the available versions for you to select one to be deployed.

#### Release from local build

This command will trigger a deployment using the pipeline's configured build directory within the current working directory. It assumes that you have previously built the application before running.

```
$ reapit release zip
```

This command will also prompt and update your package's version value with your given value.

#### Release from repo

Trigger a deployment using the below command in your app's cwd. Assumes you have the latest version of your app pushed to your configured main branch.

```
$ reapit release repo
```

This will begin a deployment which the command will then give real time updates on. This can be closed and the deployment will continue.


# What’s New

We are constantly working to improve your experience with the Public APIs. Have a look to see what new features and fixes have been released.

To submit a request, please refer to [Feature Requests](/dev-requests) for more information.&#x20;

{% hint style="warning" %}

### Breaking Change - coming soon

Effective: **October 28th, 2026**

We're making changes to metadata retrieval filter options. We recommend reviewing apps and integrations that currently rely on metadata filters.

From October 28th, 2026 metadata GET requests will only support the following filter operations below `$eq`, `$ne`  and `$con`.\
\
For further enquiries, please contact **<partners@reapit.com>**
{% endhint %}

***

## September 2026

#### Certificates

Certificates typeId is now retrieved on bulk and individual retrieval. Certificate type ids are read-only.

Endpoint:

`GET /certificates`

`GET /certificates/{id}`

Example Response

```
{
  ...
  "typeId": "GS",
  "type": "gasSafety"
  ...
}
```

***

#### Configuration

The full listing of configured rent review check types can now be retrieved. Individual check types can also be retrieved by id.

Endpoint:

`GET /configuration/rentReviewCheckTypes`

`GET /configuration/rentReviewCheckTypes/{id}`

Example Response

```
[
  {
    "id": "RRC",
    "value": "rent review check 1",
    "active": false,
    "officeIds": []
  },
  {
    "id": "RRC1",
    "value": "rent review check 1",
    "active": true,
    "officeIds": []
  }
]
```

***

#### Properties

The UPRN (Unique Property Reference Number) is available on a property's address. UPRN can be set when a property is created or updated. A UPRN must be a 1-12 digit number when supplied, and is returned as a string.

Endpoint:

`GET /properties`

`GET /properties/{id}`

`POST /properties`

`PATCH /properties/{id}`

Example Response

```
{
  ...
  "address": {
    ...
    "postcode": "B91 2XX",
    "countryId": "GB",
    "uprn": "100071417210"
    ...
  }
  ...
}
```

***

#### Tenancies

A comparable on a rent review can be retrieved and updated via the API. The negotiator managing the comparable and the comparable market rent and frequencies (weekly, 4weeks, monthly or annually) are available.&#x20;

Endpoint:

`GET /tenancies/{id}/rentReviews`

`GET /tenancies/{id}/rentReviews/{rentReviewId}`

`POST /tenancies/{id}/rentReviews`

`PATCH /tenancies/{id}/rentReviews/{rentReviewId}`

Example Response

```
{
  ...
  "comparable": {
    "negotiatorId": "TMM",
    "marketingRent": {
      "amount": 1300,
      "frequency": "monthly"
    }
  }
  ...
}
```

***

#### Tenancies

Tenancies with a rent instalment frequency of britishQuarter are returned. This value is read-only.

Endpoint:

`GET /tenancies`

`GET /tenancies/{id}`

Example Response

```
{
  ...
  "rentInstalmentsFrequency": "britishQuarter"
  ...
}
```

***

#### Tenancies

Retrieve the Fees and Charges on a Tenancy invoice for reporting.

Endpoint:

`GET /tenancies/{id}`

Example Response&#x20;

```json
{
  ...
  "feesAndCharges": [
    {
      "description": "Deposit Invoice",
      "chargedTo": "tenant",
      "amount": 100.00,
      "vat": 20.00,
      "isIncluded": true
    },
  ...
}
```

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F56lbqtdbd2k7iYioThx6%2Fimage.png?alt=media&amp;token=e8e3b96b-c038-42b2-9347-c5c6ebaa4ba9" alt=""><figcaption><p><em>e.g., 'Fees and Charges' panel on a Tenancy record visible in the CRM.</em></p></figcaption></figure>

***

#### Journal Entries

Account notes can now be created via the API. Journal entries can be posted with `typeId: "AC"` and will appear in the CRM once created.

Endpoint:

`POST /journalEntries`

Example Request

```json
{
  "typeId": "AC",
  "propertyId": "RPT250106",
  "associatedType": "applicant",
  "associatedId": "SOL260001",
  "description": "tTest accountsNote",
  "negotiatorId": "TAN"
}
```

***

#### Tenancies

Return and update the rent review date field.

Endpoint:

`GET /tenancies/{id}/rentReviews`

`GET /tenancies/{id}/rentReviews/{rentReviewId}`

`PATCH /tenancies/{id}/rentReviews/{rentReviewId}`&#x20;

Example Response

```json
{
  ...
  "nextRentReviewDate": "2026-09-27"
}
```

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FC6sRtF1GvkisTd6FDboJ%2Fimage.png?alt=media&amp;token=5726eee6-5a48-4ea3-8d12-c8004761cb96" alt=""><figcaption><p><em>e.g., Next 'Review Date' field on a renters rights Tenancy Details screen in the CRM</em></p></figcaption></figure>

***

#### Tenancies

Return rent review date field, ‘last rent increase’.

Endpoints:

`GET /tenancies/{id}/rentReviews`

`GET /tenancies/{id}/rentReviews/{rentReviewId}`&#x20;

Example Response

```json
{
  ...
  "terms": {
    "lastRentIncrease": "2026-01-05"
    ...
  }
}
```

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FOHHla6lw02TEZvFDobXl%2Fimage.png?alt=media&amp;token=f75b520c-7c1e-4ea0-959e-21eac69eff8e" alt=""><figcaption><p><em>e.g., 'last rent increase' field on a CRM rentReview - Proposed Terms section</em></p></figcaption></figure>

***

#### Properties

Individual property checklist items can be retrieved and updated via the API. The checklist id can be used to update a property checklist. Checklist items that have never been saved return a null id and must be created via POST.

Each checklist item exposes a stable variable identifier from the checklist template. The checklist variable can be used to create a checklist item id. value of a new checklist item can also be updated during creation or update.

Endpoints:&#x20;

`GET /properties/{id}/checklists/{checklistId}`&#x20;

`POST /properties/{id}/checklists`&#x20;

`PATCH /properties/{id}/checklists/{checklistId}`

Example POST Request (creating an unset item id and its value)

```json
{
  "variable": "test2"
  "value": "tTest"
}
```

***

## August 2026

#### IdentityChecks

Identity checks retrieved via the API now include Right to Rent status, so agents can see whether a Contact has the right to rent a property when reviewing or renewing tenancies. When the status is 'Time Limited Right to Reside', the associated expiry date is also returned.

Endpoints:

`GET /identityChecks`

`GET /identityChecks/{id}`

Response Extract

```json
{
  ...
  "rightToRent": "timeLimitedRightToReside",
  "rightToRentExpiry": "2028-01-14"
}
```

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F19VPuPYWwDQSlmnZpXCu%2Fimage.png?alt=media&amp;token=4a894fd7-9e38-489f-b713-934c95bea066" alt=""><figcaption><p>e.g., CRM Right To Rent section on the identityCheck of a Contact record.</p></figcaption></figure>

***

#### Offers

Retrieve and update the `includeInPipeline` , reflecting the 'Include in Pipeline' checkbox on an accepted offer in the CRM. The `includeInPipeline` field value can only be updated on Offers with an Accepted status and is `null` when the field is unavailable in the CRM.

Endpoints:&#x20;

`GET /offers`&#x20;

`GET /offers/{id}`

`PATCH /offers/{id}`

Example Request

```
{
  "includeInPipeline": true
}
```

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fena2oJmjgtKrfwckKW42%2Fimage.png?alt=media&amp;token=2e46f916-fb10-43e5-adef-1a9c697305e3" alt=""><figcaption><p>e.g., CRM Offers screen, Accepted Status with enabled and checked 'Include in Pipline' checkbox.</p></figcaption></figure>

***

#### Tenancies

Metadata on rent review checks can be created, updated and retrieved via the API. Metadata can be supplied when a check is created, added or changed on a rent review Check.

Updating a check requires an If-Match header carrying the current ETag.

Endpoint:

`GET /tenancies/{id}/rentReviews/{rentReviewId}/checks`

`GET /tenancies/{id}/rentReviews/{rentReviewId}/checks/{checkId}`

`POST /tenancies/{id}/rentReviews/{rentReviewId}/checks`

`PATCH /tenancies/{id}/rentReviews/{rentReviewId}/checks/{checkId}`

Example GET Response Extract

```
{
  "metadata": {
    "CustomField1": "CustomValue1"
  }
}
```

*Example Request (attaching metadata)*

```
PATCH /tenancies/{id}/rentReviews/{rentReviewId}/checks/{checkId}
{
  "metadata": {
    "CustomField1": "CustomValue1"
  }
}
```

***

#### Certificates

Certificates can now be retrieved in batches by ID. The /certificates endpoint accepts an id parameter that can be supplied more than once, to filter for certificates matching one or more of the values provided.

Endpoint:

`GET /certificates`

Example Request:

```
GET /certificates?id=MKT26000216&id=MKT26000222&id=RPT26000465
```

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FWV3gjiF0T0YsycE6EX5j%2Fimage.png?alt=media&amp;token=3a25b660-d2d0-49a8-bd9e-0d3483d409c1" alt=""><figcaption><p><em>e.g., 3 certificate Ids queried on the API main swagger page</em></p></figcaption></figure>

## July 2026

#### Tenancies

Recurring charges on a tenancy (e.g. landlord-to-supplier payments, management fees) can now be retrieved via API.

Endpoint:

`GET /tenancies/{id}/recurringCharges`

Example Response:

```
{
  "id": "OXF190060",
  "created": "2025-05-13T15:44:28Z",
  "modified": "2026-05-26T09:24:02Z",
  "startDate": "2025-05-14",
  "endDate": "2026-10-23",
  "chargeType": "landlordToSupplierFee",
  "supplierId": "CMP1900001",
  "netAmount": 333,
  "includeVat": true,
  "frequencyType": "monthly",
  "frequencyInterval": 2,
  "narrative": "recurring maintenance charge"
}
```

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fo9443ZHJUhQXKnDDkedT%2Fimage.png?alt=media&amp;token=8b9ee640-f4b6-43af-b033-5b5edd14c61b" alt=""><figcaption><p><em>Example CRM Recurring Charge screen</em></p></figcaption></figure>

***

#### Transactions

Individual payments made against a transaction can now be retrieved via the API, including payment  amount and which transactions the payment moved from and to. This helps with allocating partial payments to the correct landlord, invoice, or period.&#x20;

Endpoint:

`GET /transactions/payments`

`GET /transactions/{id}/payments`

`GET /transactions/payments/{id}`

Example Response

```
{
  "id": "RPT26000122",
  "created": "2026-07-15T15:31:52Z",
  "modified": "2026-07-15T15:31:55Z",
  "transactionDate": "2026-07-15",
  ...
  "payments": [
    {
      "id": "RPT26000008",
      "created": "2026-07-15T15:31:54Z",
      "modified": "2026-07-15T15:31:54Z",
      "amount": 5.0,
      "transactionFrom": "RPT26000120",
      "transactionTo": "RPT26000122",
      "_links": {
        "self": {
          "href": "/transactions/payments/RPT26000008"
        }
      }
    }
  ]
}
```

***

### Tenancies

Tenancies can now record the date a tenancy agreement was signed, so agents can see when an agreement is outstanding or confirm when it was completed.

Endpoint:

`GET /tenancies`  `GET /tenancies/{id}`

`POST /tenancies`

`PATCH /tenancies/{id}`

Example Request

```
{
  "agreementSignedDate": "2026-02-31"
}
```

***

### Tenancies

Post-tenancy checks can no longer be updated via the API for tenancies with a Cancelled status. Updates are also no longer permitted for Finished tenancies once all post tenancy checks have a status of 'completed' or 'notNeeded'.are now restricted based on tenancy status:<br>

***

### Properties

The **Lost Instruction** status can now be created and updated via the API, allowing connected apps to record when an instruction has been lost to another agent, and why.

Endpoint:

`POST /properties/{id}/lostInstruction`

`PATCH /properties/{id}/lostInstruction`

Example Request

```
{
  "lostInstructionAgentId": "CMP2400001",
  "lostInstructionReason": "other",
  "lostInstructionNote": "Other agent charged £300 less"
}
```

New fields added:

* lostInstructionAgentId – the company/agent the instruction was lost to.&#x20;
* lostInstructionReason – the reason the instruction was lost. .
* lostInstructionNote – free-text note, only used when the reason is 'other'.

***

### Enquiries

Enquiries can be created with 0 bedrooms, allowing support for enquiries such as 'land'.

Endpoint:

`POST /enquiries`

Example Request

```json
{
  "bedrooms": "0"
}
```

***

### Negotiators

Negotiators with matching contact numbers can retrieved along with their `additionalContactDetails` .

Endpoint:

`GET /negotiators`

`GET /negotiators/{id}`&#x20;

Example Response

```json
{
"id": "NEG",
  "created": "2025-07-16T08:14:28Z",
  "modified": "2026-07-08T19:20:03Z",
  "name": "Tanya",
  "jobTitle": "negotiator",
  "officeId": "OXF",
"workPhone": "09876543212",
"mobilePhone": "09876543212",
"email": "tTest@tTesting.com",
  "profileImageUrl": null,
  "active": true,
  "diaryNegotiatorIds": [],
  "diaryOfficeIds": [],
  "additionalContactDetails": [
    {
      "type": "E-Mail",
      "value": "tTesting@tTest.com"
    },
    {
      "type": "Home",
      "value": "01324567876"
    },
    {
      "type": "Mobile",
      "value": "07876767676"
    },
    {
      "type": "Home",
      "value": "01414312345"
    }
  ],
  "_eTag": "\"X038FTDGXXEGT3748F93JF74HS62H10\"",
  "links": {
  }
}
```

***

### Works Orders

The **Raised To Chase** works order status can now be created, updated and retrieved successfully via the API.

Endpoint:

`GET /worksOrders`

`GET /worksOrders/{id}`

`POST /worksOrders`

`PATCH /worksOrders/{id}`

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FStlV1krFBgpMdm9wy6yp%2Fimage.png?alt=media&amp;token=528bdc14-0477-4477-bb6a-0e72a287d2ad" alt=""><figcaption><p><em>e.g., API retrieval of 'raisedToChase' status and 'raisedToChaseDays'</em> </p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FWjkvExsE2TVQVLCmRbza%2Fimage.png?alt=media&amp;token=4b337afb-b0ee-4428-85b5-16806a7ef8c9" alt=""><figcaption><p><em>e.g., extract of CRM Works Order displaying Raised status and Chase days.</em></p></figcaption></figure>

**Creating a worksOrder status of \`raisedtoChase\` status and interval**

When creating a works order with a status of `raisedToChase`, the `raisedToChaseDays` value can be supplied.

Example Response

If `raisedToChaseDays` is not supplied, the default chase value is **1 day**.

**Updating works order status to 'raisedToChase'**

When updating a works order with a status of `raisedToChase`, *both* the status and chase days interval must be supplied.

Example Request

```json
{
  "status": "raisedToChase",
  "raisedToChaseDays": 9
}
```

***

### Properties

The gas certificate field is not applicable to Sales properties and is not visible within the CRM UI.

As a result, the gas status field `noGas` will be returned as false for Sales properties when retrieving property utilities.

Endpoint:

`GET /properties/{id}/utilities`

***

## June 2026

### Tenancies

Retrieve links to occupier contact records on a tenancy. Links are only applicable to occupiers with contact records.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fn082RIAqOJD3PHYu5iAz%2Fimage.png?alt=media&amp;token=ab104a38-c01d-41cd-a3f3-94ccd6cab48c" alt=""><figcaption><p>e.g., CRM Tenancy record displaying Additional Occupiers </p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FAFsxYX7okxgwretS9T0d%2Fimage.png?alt=media&amp;token=90b1a371-ccd7-458d-8c11-07b57dc69c6b" alt=""><figcaption><p><em>e.g., retrieval of 'occupierContacts' on '/tenancies/{id}'</em></p></figcaption></figure>

### Applicants

API retrieval of applicant attributes: 'part-furnished' and 'unfurnished' mirrors CRM applicant attribute selection.

### Tenancies

Tenancy 'endDate' validation has been removed. Periodic tenancies can be created via API without an endDate.&#x20;

Endpoint:

POST `/tenancies/`

### Tenancies

Post EPC certificates on Sales properties.

Endpoint: \
POST `/properties/{id}/certificates`

### Tenancies

Meter readings and last read dates on Finished Tenancies can now be updated.&#x20;

Endpoint:

PATCH `/tenancies/{id}`

Fields:

* meterReadingGas
* meterReadingGasLastRead
* meterReadingElectrcity
* meterReadingElectricityLastRead
* meterReadingWater
* meterReadingWaterLastRead

### Tenancies&#x20;

When retrieving tenancies, the 'Days in Arrears' field value is now visible. Days in Arrears indicates the number of days a rent invoice can be overdue/ in arrears.

Endpoint:

GET `/tenancies`

GET `/tenancies/{id}`

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FaCFktOty97Ybl4MdR9Ts%2Fimage.png?alt=media&amp;token=054aa26d-bf0e-49e5-a3e1-bf25eee22afb" alt=""><figcaption><p>e.g., 'daysInArrears' field retrieved via API</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FR24ge4dHiiC52PTDVl72%2Fimage.png?alt=media&amp;token=7b3ce584-a101-4e77-80d8-d60ec8fc0f32" alt=""><figcaption><p>e.g., CRM Payable field on Financial &#x26; Renewals screen</p></figcaption></figure>

### Contacts

Embed 'landlordDetails' when retrieving all Contacts for visibility of Making Tax Digital (MTD) details across multiple contacts.

Endpoint:

GET `/contacts`&#x20;

## May 2026

***

### Enquiries

Retrieve and Update property enquiries with the addition of the 'createdPropertyId' field.

Endpoint:&#x20;

GET `/enquiries`

GET `/enquiries/{id}`&#x20;

PATCH `/enquiries/{id}`

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FBsOqTePe0efDVCJOXJbS%2Fimage.png?alt=media&amp;token=7e6b833f-1521-4f4f-a1e5-494a3fc65fb5" alt=""><figcaption><p><em>e.g., 'createdPropertyId' field retrieved via '/</em>enquiries/' endpoint</p></figcaption></figure>

### Tenancies

The Tenancies service now supports metadata on RentReviews.\
GET, POST, and PATCH endpoints allow flexible key–value storage.

Endpoint:

GET `/tenancies/{Id}/rentReviews`&#x20;

GET `/tenancies/{Id}/rentReviews/{rentReviewId}`&#x20;

POST `/tenancies/{Id}/rentReviews`

PATCH `/tenancies/{Id}/rentReviews/{rentReviewId}`

### Companies

Update company accreditation 'details' and 'expiry' dates via

Endpoint:\
PATCH `/companies/{id}/accreditations/{type}`&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F4Uf4R1yeqkPjnL1yRJlg%2Fimage.png?alt=media&amp;token=fc52abae-47e4-4092-b84a-6821b42d6bce" alt=""><figcaption><p><em>e.g., Accreditations section on a Company record in the CRM</em></p></figcaption></figure>

### Tenancies

Retrieve and update Notice Management dates and reasons for Landlords and Tenants via:

Endpoint:

GET `/tenancies/{id}/noticeManagement`

PATCH `/tenancies/{id}/noticeManagement`

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FczO4cRJn5toLXUI8GsWT%2Fimage.png?alt=media&amp;token=d1c14bf5-21bb-450a-8b64-e234557ebca5" alt=""><figcaption><p><em>e.g., CRM Notice Management screen accessed from a Tenancy record</em></p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fa2yo935VXLGcsVxZpV4v%2Fimage.png?alt=media&amp;token=e96716d9-a0ed-4f47-8ea0-d6d15eaaf473" alt=""><figcaption><p><em>e.g., API notice management retrieval</em></p></figcaption></figure>

### Tenancies

Retrieve letting and management fee 'type', 'amount' and 'frequency' for a tenancy alteration via:

Endpoint:

GET  `/tenancies/{id}/extensions`

GET `/tenancies/{id}/extensions/{extensionId}`&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F846TJeDkcZjmRNPtmQdV%2Fimage.png?alt=media&amp;token=a7a21284-63bf-4fb3-a125-5346ecfd7d11" alt=""><figcaption><p>e.g., Letting and Management fees, fee types and collection frequencies on a Tenancy Alteration screen in the CRM.</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FRPpkdVvA7mRhFzgsGzub%2Fimage.png?alt=media&amp;token=8d6877d3-f662-4dbe-898e-537b0da72148" alt=""><figcaption><p>e.g., lettingFee and managementFee retrieved via API</p></figcaption></figure>

### Enquiries

Retrieve and update the negotiator assigned to property enquiries via

Endpoints:

GET `/enquiries` \
GET , PATCH `/enquiries/{id}`

Fields:

* negotiatorId

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FqSFhs7cxlo3nk3RtMKag%2Fimage.png?alt=media&amp;token=ce03efd1-fd37-4d91-9bbb-0074ab5dff6f" alt=""><figcaption><p>E.G., 'negotiatorId' retrieval on a property valuation via '/enquiries'</p></figcaption></figure>

### Enquiries

'enquiryType' parameter accepts multiple values (salesApplicant/ lettingsApplicant/ salesProperty/ lettingsProperty) to retrieve specific enquiryTypes.

Endpoint: \
GET `/enquiries`&#x20;

## April 2026

***

### Works Orders

Retrieve (GET), create (POST) and update (PATCH) the latest worksOrder field dates via:

Endpoint:&#x20;

GET `/worksOrders/`\
GET, POST, PATCH `/worksOrders/{id}`

Fields:

* reviewDate

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FD8jDfuk151wEAJWnHrYk%2Fimage.png?alt=media&amp;token=bb92b7a4-71d3-4890-a0a4-225c5dea8127" alt=""><figcaption><p>e.g., CRM Works Order screen section highlighting retrievable 'Review Date' field </p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F5FmnvBV9ljNFQ0RrDQND%2Fimage.png?alt=media&amp;token=a821d028-2a25-43de-82c7-3e57653046fc" alt=""><figcaption><p>e.g. reviewDate field retrieved via API '/worksOrders/{id}'</p></figcaption></figure>

### Renters Rights

Tenancies – Rent Review Enhancements

This section summarises new Rent Review related API capabilities across Initial Contact, Agreement, Terms, and Checks, alongside the independent Renters Rights field.\
All functionality provides CRM parity and follows the Tenancies service model.

### Tenancies&#x20;

Retrieve a tenancy’s Renters Rights status 'isRentersRights' via:

Endpoints:

GET `/tenancies/{id}` \
GET `/tenancies/`

Field:

* isRentersRights

CRM screenshot placeholder\
*Display of “Renters Rights” field within the tenancy record*

API screenshot placeholder\
*GET /tenancies/{id} response highlighting isRentersRights*

### Tenancies

Retrieve (GET) unique rentReview identifiers, the date the rentReview was created and the latest modified date:time via:

Endpoints:

GET `tenancies/{id}/rentReview`

GET `/tenancies/{id}/rentReviews/{rentReviewId}`&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fbabt0KrgEPg4PMhHkWQn%2Fimage.png?alt=media&amp;token=fc633a9f-75fc-4120-92ff-109f7f873db9" alt=""><figcaption><p>example API rentReview retrieved displaying rent review 'Id', 'created' and 'modified' fields</p></figcaption></figure>

### Tenancies

**Rent Reviews: Initial Contact**

Retrieve (GET) and update (PATCH) Initial Contact information for Landlords and Tenants via:

Endpoints:\
GET, POST `/tenancies/{id}/rentReviews`\
GET, PATCH `/tenancies/{id}/rentReviews/{rentReviewId}`

These fields capture when communication was Sent or Received.

Fields:

* landlordSentDate
* landlordReceivedDate
* tenantSentDate
* tenantReceivedDate

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FIPHNxi4Ok8H3bY35NSwi%2Fimage.png?alt=media&amp;token=4218a1d1-52cb-40e1-aed7-eecc04cd50f4" alt=""><figcaption><p><em>Initial Contact section of CRM Rent Review screen</em></p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FC3nTX2rIwZBmBpJo7KvQ%2Fimage.png?alt=media&amp;token=b9e77185-0b06-4ea5-8b43-4c4fc1cb0255" alt=""><figcaption><p> <em>Initial Contact fields within GET /tenancies/{id}/rentReviews payload</em></p></figcaption></figure>

### Tenancies

**RentReview: Agreement**

Retrieve (GET), create (POST), and update (PATCH) Rent Review Agreement details via:

Endpoints:\
GET, POST `/tenancies/{id}/rentReviews`\
GET, PATCH `/tenancies/{id}/rentReviews/{rentReviewId}`

Fields:

* negotiatorId
* status

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FWP4fsN7Ct5FZTWPorpYq%2Fimage.png?alt=media&amp;token=406a8b28-3fa0-4d6f-82f7-323dfdc53a5b" alt=""><figcaption><p> <em>Agreement section of CRM Rent Review screen</em></p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FojvaWXoCMahZCDwOIEqk%2Fimage.png?alt=media&amp;token=09fb7150-9179-401f-b519-be05e59707b1" alt=""><figcaption><p><em>Agreement object within /tenancies/{id}/rentReviews</em></p></figcaption></figure>

### Tenancies

**Rent Reviews: Proposed Terms and Agreed Terms**

The Terms section captures all adjustable financial values and agreement indicators associated with a rent review.

Retrieve (GET), create (POST), and update (PATCH) Rent Review Terms via:

Endpoints:\
GET, POST `/tenancies/{id}/rentReviews`\
GET, PATCH `/tenancies/{id}/rentReviews/{rentReviewId}`

Fields include:

* proposedRent
  * amount
  * frequency
* proposedOn: (date)
* proposedStart: (date)
* agreedRent
  * amount
  * frequency
* effectiveDate
* tenantAgreed
* landlordAgreed

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F8u5345hlklS7WQMc1pdm%2Fimage.png?alt=media&amp;token=be1a2a30-3ea5-41f0-af01-c6cd9b2e9a4c" alt=""><figcaption><p>Proposed <em>Terms section of CRM Rent Review screen</em></p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FRmCtABUz4DD7UFocRa3v%2Fimage.png?alt=media&amp;token=9560241c-fc0f-4f28-929d-f18b027d5f62" alt=""><figcaption></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Ffnj5nDLL8rwL2l65vrgs%2Fimage.png?alt=media&amp;token=9a832ad8-eee8-40c5-9041-18f8a6da2ae2" alt=""><figcaption><p><em>Example Proposed Terms and Agreed Terms object retrieved via API</em></p></figcaption></figure>

### Tenancies

**Rent Review: Checks**

Retrieve (GET), create (POST), update (PATCH), and delete (DELETE) Rent Review Checks via:

Endpoints:\
GET, POST `/tenancies/{id}/rentReviews/{rentReviewId}/checks`\
GET, PATCH, DELETE `/tenancies/{id}/rentReviews/{rentReviewId}/checks/{checkId}`

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FgE23CtiJnp1VwU8fevh2%2Fimage.png?alt=media&amp;token=c2878339-0ee2-4f45-808e-9fcf6f7b3eb9" alt=""><figcaption></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FbUVW9dOZRpdgbvfTjUJ4%2Fimage.png?alt=media&amp;token=09299991-e9d3-4002-b249-512d83a279ec" alt=""><figcaption><p><em>Example rentReview Check retrieved via API</em></p></figcaption></figure>

***

POST Checks

Create a new Rent Review Check by supplying:

* status
* checkTypeId

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FuWP4rRwpKBP6eTkhBNMs%2Fimage.png?alt=media&amp;token=11d2084d-e794-44ce-b09e-4f7aee7264fe" alt=""><figcaption><p><em>Example rentReview checks POST fields available via API</em></p></figcaption></figure>

***

PATCH Checks

Update the status of an existing Rent Review Check.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F6pi6f51e6Lzl7HYRgbQu%2Fimage.png?alt=media&amp;token=219192a4-dab8-4d37-b319-a69a03dc80f7" alt=""><figcaption><p><em>Example PATCH rentReview check via API</em></p></figcaption></figure>

***

DELETE Checks

Remove a Rent Review Check by supplying mandatory fields:

* tenancyId
* rentReviewId
* checkId

### Properties

Retrieve (GET) property attributes per department via

endpoint: \`/departments\` and \`/departments/{id}\`

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FjiGGv8NLtd4H7AzBmBtU%2Fimage.png?alt=media&amp;token=8b459102-811f-40f1-9afd-79e6a00bb943" alt=""><figcaption><p>e.g., 'Commercial' attributes retrieved via API ‘/departments’, displaying attribute options configured for ‘Type’ and ‘Style’ in the CRM</p></figcaption></figure>

### Properties

Retrieve (GET) update (PATCH) and create (POST) additional International property attributes.

New mapped attributes:\
**Type**: penthouse,  farmhouse, mas, chalet, palace, chateau, countryHouse, developmentPlot

**Locality**: resort, mountains, waterfront

**Situation:** balcony, garage, vineyard, communalGarden

### Certificates

Retrieve (GET) certificates with endDates from a specified date or up to specified date with two additional parameters 'endDateFrom' and 'endDateTo' available via:

GET `/certificates`

## March 2026

### Properties

Retrieve (GET), update (PATCH) and create (POST) `serviceChargeReviewDate` and `groundRentType`  on Lettings property records. These fields are accessible in the CRM 'Keywords & Charges' tab which is visible on the property Attributes screen. Available endpoints:

GET `/properties`&#x20;

GET, POST, PATCH `/properties/{id}`

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FkR11xc75P8LogStdJXb5%2Fimage.png?alt=media&amp;token=3253f8e4-0030-498f-b49b-6c60581fd4cd" alt=""><figcaption><p>E.g., API '<em>groundRentType</em>' retrieval</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fmo4iffN1um1ypZfWxVMD%2Fimage.png?alt=media&amp;token=837cce8b-c312-4aa3-abba-196feaebbccf" alt=""><figcaption><p>E.g., API `<em>serviceChargeReviewDate</em>' retrieval</p></figcaption></figure>

### Properties

Retrieve (GET) `parking` related Material Information stored on a property record via `/properties/{id}/utilities`

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FP4C8NDn7q4Xo1DkejBr7%2Fimage.png?alt=media&amp;token=4a9008ba-5233-47e4-a35a-42d924f50979" alt=""><figcaption><p>E.g., '<em>parking</em>' utilities data retrieved via API </p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FMdjUNpYW7tbDU6OrXuuh%2Fimage.png?alt=media&amp;token=7668ee81-737e-4467-80b5-7c3ebd9de302" alt=""><figcaption><p>E.g., '<em>Parking</em>' utilities field on a property record's Attribute screen in the CRM </p></figcaption></figure>

### Contacts

Making Tax Digital (MTD).&#x20;

Retrieve (GET) landlord details for a specific contact via\
`/contacts/{id}/landlordDetails`&#x20;

**'makingTaxDigitalOptInStatus'** \
This field represents whether a landlord has agreed for the agent to share their landlord and transaction details via the agent’s CRM for HMRC tax reporting purposes. &#x20;

&#x20;Possible values :

* &#x20;`notSet` (default) &#x20;
* `optedIn` &#x20;
* `optedOut`&#x20;

**'makingTaxDigitalOptInStatusDate'** \
This field represents the date the 'makingTaxDigitalOptInStatus' was changed.

**'makingTaxDigitalConsentStatus'**\
This field indicates the landlord’s relationship with a digital tax integration/ app.

Possible values:

* `not Set` (default)&#x20;
* `invited`&#x20;
* `accepted`&#x20;
* `revoked`&#x20;

⚠️ **Note:** This field cannot be updated by agents via the CRM.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FchE8ou4byYjtJxifZ2On%2Fimage.png?alt=media&amp;token=00be493c-64d6-4015-adfd-377f1b61a987" alt=""><figcaption><p>Example makingTaxDigital status and optIn date retrieval via GET '/contacts{id}/landlordDetails'</p></figcaption></figure>

### Contacts&#x20;

Add (PUT) the relationship status between a specific landlord and a Making Tax Digital (MTD) integration/ app on the 'makingTaxDigitalConsentStatus' field via

`/contacts/{id}/landlordDetails`&#x20;

Possible values: (above)

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FaCbdNvuHl9VhXyvpIglr%2Fimage.png?alt=media&amp;token=d3b6e375-80be-4f18-874b-74b2125bbd5f" alt=""><figcaption><p>Example makingTaxDigitalConsentStatus via PUT '/contacts/{id}/landlordDetails'</p></figcaption></figure>

### Auctions

New Auctions service retrieves (GET) all auction lots  `/lots` or retrieve auction lots by id `/lots/{id}`

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FJQbRqlZOR1u0aA9WW6xb%2Fimage.png?alt=media&amp;token=0d5c8a4a-3e1f-4b73-a52f-bf005db7dc97" alt=""><figcaption><p>Example payload via /auctions/lots </p></figcaption></figure>

### Enquiries

Filter incoming enquiries using two new parameters, `officeId` and `status` when reading (GET) enquiries on `/enquiries` and `/enquiries/{id}` .

### Offices

Retrieve (GET) configured branchId/ officeId in the new onlineServices array available on the `/offices` and `/offices/{id}` endpoints. Online service id, name and associated branch codes are visible.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FaI7p8PPlV3RMD3970Tau%2Fimage.png?alt=media&amp;token=5a32720b-fc35-4621-8b29-608b9e1348a0" alt=""><figcaption><p>Online Services, id, name and code retrieved via API when calling GET /office and /office{id} </p></figcaption></figure>

## February 2026

### Properties

Read (GET) property Address, Strapline, Accommodation Summary, Brief description, Rooms and Extra Descriptions in CRM set languages via  `properties/{id}/multilingual` &#x20;

### Properties

Read (GET) and update (PATCH) property Address, Straplines, Accommodation Summary, Brief Description, Rooms and Extra Descriptions for a single language via /`properties/{id}/multilingual/{langId}` . One language can be updated at a time.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Ff21VbqHXuqiifdxmDPBB%2Fimage.png?alt=media&amp;token=98a62be5-5510-4c78-9608-a1fd818f176b" alt=""><figcaption><p>Property record strapline, accommodation summary, brief description, address lines and postcode API retrieval</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FuCjQFyyPgh6xui6X8dHp%2Fimage.png?alt=media&amp;token=e19262fc-87bf-4530-af2b-af721087fdb5" alt=""><figcaption><p>Accommodation Summary available on CRM Property record. Attributes. Rooms and Accommodation Screen</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F7dMm4JOEGK87bNXyA8Mk%2Fimage.png?alt=media&amp;token=c0d40ecf-dd07-408f-aecd-eb742cc6c0a5" alt=""><figcaption><p>CRM Property Record. Attributes. Rooms and Accommodation Screen</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FAX7n8dlhzmEXE8GFwVkW%2F2026-02-24_10h26_07.png?alt=media&amp;token=7ce86678-c3d7-4218-9581-0495ffac49de" alt=""><figcaption><p>API Rooms multi-lingual retrieval </p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F56B15BcuyaMwDH2XG4wB%2Fimage.png?alt=media&amp;token=e1993a54-64d7-483a-92d8-9fbbb7c5f924" alt=""><figcaption><p>CRM Property record, Marketing Details screen displaying Extra Descriptions and language options</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FoRJJ14fYJRXuyhKIL3DI%2F2026-02-24_10h26_29.png?alt=media&amp;token=f702f02d-1f61-4997-9ce8-5949a0bfb201" alt=""><figcaption><p>Extra Descriptions API multi-lingual retrieval</p></figcaption></figure>

### Configuration

Retrieve all languages configured in a database using `configuration/activeLanguages`

### Tenancies

Retrieve (GET) the number of occupiers associated to a tenancy with the addition of `occupierCount` field on `/tenancies` and `/tenancies/{id}`&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F9sOkXilEx6Fmc4Dy2Gco%2Fimage.png?alt=media&amp;token=008eea8c-0002-4f7f-ab8b-2e89683d5193" alt=""><figcaption><p>'occupierCount' field on GET /tenancies and GET /tenancies/id</p></figcaption></figure>

## December 2025

### Negotiators

Update (PATCH) additional contact details for Negotiators such as telephone numbers and email addresses on the CRM setup '*Negotiator and User*' screen via  `/negotiators/{id}`&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FRMBNcmgwTjY99IDd24fF%2Fimage.png?alt=media&amp;token=657cd2c2-9fab-4751-a41a-5c7417c106f8" alt=""><figcaption><p>additionalContactDetails PATCH on /negotiators/{id}</p></figcaption></figure>

## November 2025

### Conveyancing

Custom Sales milestones saved in the CRM can be retrieved (GET) on  `/conveyancing`  and (GET) `conveyancing/{id}`&#x20;

## October 2025

### Tenancies

Deposit Protection `registrationNumber` and `deregisteredDate` can now be updated on Current Tenancies when updated (PATCH) on `/tenancies`

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FKvLRnNq1e6P8lcYBL3yB%2Ftenancies-DeregisteredDate.png?alt=media&amp;token=679b67b9-33d3-4128-8318-c47334665d4f" alt=""><figcaption><p>deregisterDate and registrationNumber can be updated</p></figcaption></figure>

### Tenancies

Clearly identified current Tenants with the `isCurrent` flag.&#x20;

When `isCurrent` is true, the Tenant retrieved is a current Tenant of the property. A current Tenant is also indicated by the vacateOn and occupyOn dates.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FiHkRuUn1rxKgntRfYgXR%2FisCurrentTenancies-flag.png?alt=media&amp;token=9165d75f-9a26-4580-9871-9cb2e73dce98" alt=""><figcaption><p><code>isCurrent</code> flag indicating a current Tenant</p></figcaption></figure>

### Contacts

Archived roles on a Contact can be retrieved now the new `includeArchived` parameter on  `/contacts/{id}/relationships`

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FyaQh9ftOAQ2wqDtWrB25%2FincludeArchived-Contacts.png?alt=media&amp;token=ee50444e-deeb-42b6-9641-d0e84f12bb90" alt=""><figcaption><p>archived Contact role parameters</p></figcaption></figure>

### Contacts

Subscribe/ Unsubscribe to parent Subscriptions. This bulk option allows your selection to be applied to all 'children' of the parent subscription via the PUT on `contact/{id}/subscriptions`

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F9zAv1gpMeZK4QTRVt3HP%2Fsubscibe-unsubscribeParents-Contacts.png?alt=media&amp;token=cb6115d0-1f5f-458a-99a8-aae626589135" alt=""><figcaption><p>Bulk Subscribe/ Unsubscribe Mailings and Subscriptions on /contacts{id}/relationships</p></figcaption></figure>

### Journal Entries

Renewal Negotiation journal entries can be created (POST) using `"typeID": "RN"` on `/journalEntries`

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FaAnO5yPP407r197lH82T%2FrenewalNegotiation-JournalEntries.png?alt=media&amp;token=ef94b248-3ec0-497c-b666-e6e7d7ad68c9" alt=""><figcaption><p>RN Renewal negotiation <code>typeID</code> can create journal entries on <code>journalEntries</code></p></figcaption></figure>

## August 2025

### Properties

Additional licencing fields have been added to the `/property` payload for retrieval (GET) and updates (PATCH).

Note API-CRM mapping names:

* `licenceTypeRequired`  - Licence Type Required
* `licenceType` - Licence Type Granted
* `referenceNumber` (under `licencing`)- Licence Reference No.
* `referenceNumber` (under `application`) - Application Ref No.
* Granted - `licenceGranted`
* Expiry - `licenceExpiry`&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FsRgnumsH6ooOYWf0g3AZ%2Frpa-401-crm.png?alt=media&amp;token=a39b9346-4a43-4506-87eb-c04dec603bfe" alt=""><figcaption><p><code>licencing</code> screen in the CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FzIIGAyuNdU6NIkLlKUZT%2Fimage.png?alt=media&amp;token=c27ed293-d7af-4de6-aede-e018bda2eac8" alt=""><figcaption><p>Example <code>licencing</code> payload retrieval</p></figcaption></figure>

### Properties

`commercial` EPC information can now be created (POST), retrieved (GET) and updated (PATCH) via the property endpoint.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FEsEUU0MEj0cbXA9wrHSo%2Frpa-3-EPC-%20CRM.png?alt=media&amp;token=317be809-5d88-4fa1-944a-f2db8e9af776" alt=""><figcaption><p>Commercial EPC screen in CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F4rZcbCZj59YKKmb6G5ca%2Frpa-3%20Commercial%20EPC%20GET.png?alt=media&amp;token=bb003296-eff8-45c6-a68c-4ef91cb8e468" alt=""><figcaption><p>Example payload of <code>commercial</code> EPC retrieval</p></figcaption></figure>

### Properties

Property marketing fields including Extra Descriptions can be retrieved (GET) and updated (PATCH) via `properties/{id}/marketing`

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F6ytERBblZnsIAWa1M9Mp%2Fimage.png?alt=media&amp;token=a8917b47-9811-4e77-9ec1-69f29acfb556" alt=""><figcaption><p>Marketing screen in CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fmq0u9cOvcyOVVYRXulrI%2Fimage.png?alt=media&amp;token=2530c202-28f2-497c-8e03-89fe8d3346fe" alt=""><figcaption><p>Example of marketing extra descriptions retrieval in payload.</p></figcaption></figure>

### IdentityChecks

Company and Contact Ids are now distinguishable when retrieving Identity checks. A new field `contactType` is visible.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FbzEiNSqlFHIulzqPIubS%2Frpa-405-swagger.png?alt=media&amp;token=7ddbffe3-0193-476b-b982-2637d051dda3" alt=""><figcaption><p>Example <code>contactType</code> field in identityChecks payload</p></figcaption></figure>

### Configuration

A list of all Tenancy Finished Reasons used within a system can be retrieved (GET) .&#x20;

When a single Tenancy Finished Reason ID is provided the Tenancy Finished Reason id , value and category are retrieved (GET).

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FZPWtPDXEpcdFF2PsGB3A%2F2025-08-29_18h55_24.png?alt=media&amp;token=22cf3890-a547-4885-8943-9f6b34256a3a" alt=""><figcaption><p>Tenancy Finished Reasons on Tenancy record in the CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FD6hgwrPqcLsJ5ddeHnKz%2F2025-09-01_12h38_11.png?alt=media&amp;token=cc967e91-4b34-499c-b483-736a26134581" alt=""><figcaption><p>Screenshot of Finished Tenancy screen in the CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FJZAJ1oBEuVu8SxZCb08A%2F2025-08-29_19h04_37.png?alt=media&amp;token=3cdad484-1adc-4a43-a522-aa3b9e35612a" alt=""><figcaption><p>Endpoint to retrieve all TenancyFinishedReasons</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FURjvVz2G9bDVPgMTx71A%2Fimage.png?alt=media&amp;token=a1930895-af45-451c-a4d7-5c1f55cb6807" alt=""><figcaption><p>Endpoint to retrieve a single Tenancy Finished reason</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FOtfCtTMjhcVeXYOKfF4r%2Frpa-302.png?alt=media&amp;token=ae23ed19-844b-46f6-918c-c7de29477352" alt=""><figcaption><p>Example payload displaying <code>id</code>, <code>value</code> and <code>category</code> fields</p></figcaption></figure>

### Tenancies

The `Payable` field on Tenancy Renewals and Alterations screen is now retrievable (GET) via `/{id}/extensions`

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FLp4BJK0cBUiC3l3YmfsQ%2F2025-08-29_19h22_54.png?alt=media&amp;token=4fcba80d-a490-4175-aa7c-9d56f92dff5c" alt=""><figcaption><p>Tenancy Renewal and Alterations screen in CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FbvULOri4sxZxHu8wYO1N%2F2025-08-29_19h14_27.png?alt=media&amp;token=c4f0901f-191c-4ffd-a3ce-d4d4e7c96188" alt=""><figcaption><p>Example retrieval of <code>payable</code> field in  payload.</p></figcaption></figure>

### Tenancies

Arrears `status` and `followUp` date fields can now be updated (PATCH) on Current Tenancies.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FrD7qXXOXelXb87El273m%2F2025-08-29_19h50_03.png?alt=media&amp;token=8bdebbf5-2501-4c1d-b14c-363c18d9715a" alt="Example payload of arrears &#x60;status&#x60; and &#x60;followUp&#x60; retrieval."><figcaption><p>Example payload of arrears <code>Status</code> and <code>followUp</code> retrieval</p></figcaption></figure>

## June 2025

### Properties

`matchTo` prices are exposed (GET) and can be edited (PATCH) within the property payload:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FHNqPhdxA9RNVNQcvaa8V%2Fimage.png?alt=media&amp;token=06181fa7-83f0-4224-9e20-c83620ce3389" alt=""><figcaption><p>Financial and Agency screen in the CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FJAntroEeDoKpgEKBD4jj%2Fimage.png?alt=media&amp;token=13b15a46-e7d2-4595-9ae3-4c115f1b8972" alt=""><figcaption><p>Example payload showing <code>matchPriceTo</code> retrieval</p></figcaption></figure>

### Properties

You can now retrieve (GET) and update (PATCH) the following licencing fields below for the endpoint `/properties`:

* Licence Compliance Status
* Section 257 Property
* Article 4
* Licence Type Granted
* Licence Reference No.
* Restrictions
* Restrictions Details

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F6voLaDu9I9jjMIvMqyZa%2Fimage.png?alt=media&amp;token=d50ffc05-a3eb-4f10-9c1e-8ce9d9ad963f" alt=""><figcaption></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FgKHZe4WCnqDhcTtSZCR7%2Fimage.png?alt=media&amp;token=925b1b32-47e7-4484-a3ae-f85f3bc7c57b" alt=""><figcaption><p>Example of new licencing fields available on the <code>Licencing</code> tab via <code>Attributes</code> screen in the CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FfCQklKzBmlA2lJDy8Rls%2Fimage.png?alt=media&amp;token=be68b113-3096-4878-b2fb-93b4173bcbfb" alt=""><figcaption><p>Example payload showing new licencing fields available for PATCH and GET on <code>properties</code> endpoint.</p></figcaption></figure>

### Companies

Company `Commission paid to agent on a supplier invoices` percentage value can now be retrieved (GET) from a Company record and exposed on the Companies payload:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FxjAs1Oa3XcCTJ3RFxGkE%2Fimage.png?alt=media&amp;token=fe30a130-df22-473f-aaec-101d6e0155e3" alt=""><figcaption></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FSJa50uPdk2fM8kbrcIub%2Fimage.png?alt=media&amp;token=25420073-6b8d-49c6-a0d8-9c711ae796eb" alt=""><figcaption><p>Example payload showing an <code>agentCommissionPercentage</code> from the Companies endpoint.</p></figcaption></figure>

### Companies

Company `Referral Fee` amount can be retrieved (GET) from a Company record  and exposed on the Companies payload:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FMGNh51fcxLSrdmoDWtsu%2Fimage.png?alt=media&amp;token=7c7ccd1f-91c2-4c0c-a1a8-878ecdce14fa" alt=""><figcaption><p><code>Referral fee</code> amount displayed on a Company record in the CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FbUvICJobxI0ShdMM4mdr%2Fimage.png?alt=media&amp;token=1d6f47da-47b1-4eea-89b6-89b86a584feb" alt=""><figcaption><p>Example payload showing a <code>referralFee</code> amount when calling the Companies endpoint</p></figcaption></figure>

## April 2025

### Properties

EPC ‘`created`’ date is now exposed within a property payload:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FeoOcwdNprQ6WbUjuW7Qb%2FWN07051.png?alt=media&amp;token=5c66ba66-792f-4b62-9851-7d531d4c309d" alt=""><figcaption><p>EPC screen in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FghpUVSL90pZAI7XDdq6o%2FWN07052.png?alt=media&amp;token=25a331c2-11eb-4d8a-830a-b883f16f6b0f" alt=""><figcaption><p>Example payload showing the ‘<code>created</code>’ date</p></figcaption></figure>

### Tenancies

A new field ‘`deregisteredDate`’ has been added to the tenancies endpoint to track when a deposit is no longer protected.

This is available in both GET & PATCH:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FjCCH8TK4zM3teA6da0zO%2FWN07053.png?alt=media&amp;token=c4968974-903d-497f-b071-42ccb2b38c31" alt=""><figcaption><p>Tenancy Deposit Detail screen in Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FyESHY1uZytt3f6e1dxts%2FWN07054.png?alt=media&amp;token=a186a1d1-2724-4fc3-ab61-40b25f8ac9c0" alt=""><figcaption><p>Payload showing the ‘<code>deregisteredDate</code>’ field</p></figcaption></figure>

### Conveyancing

It is now possible to retrieve the details of the solicitor dealing with an offer through the Conveyancing endpoint:

The information is listed under ‘`vendorSolicitorContact`’:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F0vcOG3IcY80IP8U9fq17%2FWN07055.png?alt=media&amp;token=81d866aa-58b1-4784-8a0f-54ed9cb55e11" alt=""><figcaption><p>Example offer screen in the Reapit CRM showing the main staff contact for a Solicitor/Company</p></figcaption></figure>

&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fskyc6k2TUpvg55XubjSk%2FWN07056.png?alt=media&amp;token=6d7f198c-3637-454e-9301-985529616bdb" alt=""><figcaption><p>Example payload showing 'vendorSolicitorContact'</p></figcaption></figure>

## Feb 2025

### Properties

**Utilities**

You can now retrieve (GET) and update (PATCH) the type ‘other’ for the following utilities for the endpoint ‘/properties/{id}/utilities’:

* Water
* Electrical
* Sewerage
* Heating
* Broadband
* Parking

&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F5MUFRFTK9GiH5OZEQ3rw%2F1.png?alt=media&amp;token=92dcd5c8-2b97-4733-80c1-d23708091698" alt=""><figcaption><p>Example of ‘Other’ selected as a type for Electricity in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fdn8Hv0J6cl3ut3wzBLuO%2F2.png?alt=media&amp;token=b9c150bb-8725-459f-8867-5da374b13fb8" alt=""><figcaption><p>Example payload showing ‘other’ as a type for electricity</p></figcaption></figure>

&#x20;**Accessibility, Rights & Restrictions and Flood & Erosion Risk**

The above additional information is now surfaced on the 'GET /properties' & 'GET /properties/{id}' endpoints:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FtaPXw9W2Gmz7Qsenghvz%2F3.png?alt=media&amp;token=f5f4cfa9-8db4-425a-9c66-a51ea3083f18" alt=""><figcaption><p>Example information in Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FDnUFDYTPhdLCz3VlIRx2%2F4.png?alt=media&amp;token=ff1746bf-ada0-42d7-a93b-df1001923670" alt=""><figcaption><p>Example payload</p></figcaption></figure>

&#x20;

**Property Checks**

Default property checks are now returned via '/properties/{id}/checks':

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FUz6e89UDML7dfAqGLQkN%2F5.png?alt=media&amp;token=90842d26-2d5d-4f27-9141-b3719f04d93b" alt=""><figcaption><p>Example of the default Pre-instruction property checks in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FZxiJUSp4WbLFnVjirBmn%2F6.png?alt=media&amp;token=68ca0d5b-ea68-44e7-b857-86894abed439" alt=""><figcaption><p>Example payload </p></figcaption></figure>

**Sub Agent Fee**

Sub Agent fee information is now returned on 'GET /properties' and 'GET /properties/{id}' under ‘`subAgentTerms`’:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F22EQHofsKoA3nqcBDQ5B%2F7.png?alt=media&amp;token=6c90e329-d4be-4378-9148-7746d3e668b5" alt=""><figcaption><p>Example screen of Sub Agent information in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FgxsVeDfu3JuShOHncYyM%2F8.png?alt=media&amp;token=4e19ba99-55ce-434c-8262-c5bbcf64b63d" alt=""><figcaption><p>Example payload</p></figcaption></figure>

**Sales Progressor**

A new sub resource on the properties endpoint ‘GET /properties/{id}/negotiators’ has been added to support surfacing a sales progressor attached to a property (type : `salesprogressor`):

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F7Azh6pMWhS4uMdeOVUda%2F9.png?alt=media&amp;token=e8f60527-8505-485d-a357-93304bf6164c" alt=""><figcaption><p>Example screen in Reapit CRM of ‘John Smith’ as a ‘Sales Progressor’</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FdkGsLwnVb90gDM5HPlDh%2F10.png?alt=media&amp;token=68cb6237-ad68-4904-8019-60a561ed7158" alt=""><figcaption><p>Example payload</p></figcaption></figure>

**Withdrawn Reason**

The reason when a property is made ‘Withdrawn’, is now available via the properties endpoint under '`reason`':

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FbGs4jRKONFMraGumMrfO%2F11.png?alt=media&amp;token=1b1c0bb6-1655-4fc5-82d4-67532477a50f" alt=""><figcaption><p>Example ‘Withdrawal Details’ screen in Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FRLkJ6mnfvEzkdJ1Yy9vy%2F12.png?alt=media&amp;token=32ae87ad-1552-4d5d-9396-9b68c70c3ad1" alt=""><figcaption><p>Example payload</p></figcaption></figure>

&#x20;

**Modern Method of Auction (MMoA)**

The new disposal type (`modernMethodOfAuction`) added to the Reapit CRM, is now surfaced in the properties payload:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fb323J12Xwb11TJx3Nj2z%2F13.png?alt=media&amp;token=e63ec70a-ed5c-40e3-a6c2-ddab14f5be79" alt=""><figcaption><p>Example of ‘Modern Method of Auction’ selected as disposal type in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fb1jtuAn8zY4p0ghhZGDv%2F14.png?alt=media&amp;token=46d6baf4-83ad-4b58-92dd-bfaf88042783" alt=""><figcaption><p>Example payload</p></figcaption></figure>

&#x20;

**Gross Yield and Estimated Monthly Rental Value**

Both the Gross Yield ‘`grossYieldPercentage`’ & Est Monthly Rental Value ‘`estimatedMonthlyRetailValue`’ are now available in the Properties payload:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fji4AARjWe0BKcsciM8sX%2F15.png?alt=media&amp;token=5e834042-61c4-49b0-97f3-8cf99a52d08e" alt=""><figcaption><p>Example financial screen showing the two fields in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FDenGt2nfKd2QUP9KkoyQ%2F16.png?alt=media&amp;token=bf58d195-203d-4529-8fd2-34c6102601f3" alt=""><figcaption><p>Example Payload</p></figcaption></figure>

&#x20;

**Keywords**

We now support POST\PATCH for property keywords:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FhcOd2qtIrmHpfpbbwq98%2F17.png?alt=media&amp;token=b0dd99ec-dfaf-4368-a6b6-9747981e0a09" alt=""><figcaption><p>Selected keywords in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fc2D83SXJ5UvIyaMtkSc0%2F18.png?alt=media&amp;token=82e8beee-e43e-4ec7-ac7c-8b31c8955137" alt=""><figcaption><p>Example payload</p></figcaption></figure>

**Note**: This should be used in conjunction with 'GET /departments' configuration endpoint.

&#x20;

**Property Checklist**

A new sub resource' GET /properties/{id}/checklists' has been added under the Properties endpoint to support customisable property checklists:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fa6dleavxBC1Ujy6PHslz%2F19.png?alt=media&amp;token=b5abba1c-b3eb-4bfa-828b-ae459aed9f85" alt=""><figcaption><p>New endpoint</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FZPXn1xOBbAQKEfmANTcm%2F20.png?alt=media&amp;token=301da1e8-fb41-4bde-bd12-5874e1d0aa15" alt=""><figcaption><p>Example ‘Checklist’ screen in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FmdI1qgRlJH5GSDjWPW3r%2F21.png?alt=media&amp;token=9b2d5887-e0b6-46ca-8a74-aff35d91432f" alt=""><figcaption><p>Example payload</p></figcaption></figure>

### Certificates

**New endpoint**

We have introduced a new endpoint to support retrieving certificates without needing to specify a property ID:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F71ZMQAdl8EDipts4EWDi%2F22.png?alt=media&amp;token=149d39bf-ce40-4a4e-9daf-fbb72277ba48" alt=""><figcaption><p>New endpoints</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F5Er4Lv8wHretjMpFVXz2%2F23.png?alt=media&amp;token=b3757481-9401-49ef-acb4-cc094e750d2a" alt=""><figcaption><p>Example certificate screen in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FEz1fLSgE9oVKHcokdbJP%2F24.png?alt=media&amp;token=d2650125-c2c1-4515-80da-2fec325f8b91" alt=""><figcaption><p>Example payload</p></figcaption></figure>

**Note**: This should be used in conjunction with the new Configuration endpoint 'GET /configuration/certificateTypes’.

**Status ID**

It is now possible to POST\PATCH the ‘`statusId`’ for a certificate:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FD0rbxEeiKNLbE1o92VpU%2F25.png?alt=media&amp;token=7ff0899f-4f33-479c-9a25-9e7de990e679" alt=""><figcaption><p>Example payload</p></figcaption></figure>

**Note**: This should be used in conjunction with the new configuration endpoint 'GET /configuration/certificateTypes/{typeId}/statuses’

&#x20;

**Additional Descriptions Fields**

If additional subscription fields are added via the Marketing screen in the Reapit CRM, they are now returned via the 'GET /Properties/{id}/marketing endpoint':

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FTweTTbA9HfQ3f7afLgNg%2F26.png?alt=media&amp;token=60d22d65-64a2-461b-bc3c-cc4fd26f3af8" alt=""><figcaption><p>Example of ‘Extra Descriptions’ screen in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fb1gOqNSrzYhgbTvGU23v%2F27.png?alt=media&amp;token=a9fa8961-5e2a-4970-b02e-4600c6e6efe7" alt=""><figcaption><p>Example Payload</p></figcaption></figure>

### Alarms

A new sub resource on Properties to support GET/POST /PATCH for ‘Alarms’:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FKb29wClHcNQTqAemh1yI%2F28.png?alt=media&amp;token=1723f90e-a2d6-41d5-a5b0-15fedec7c598" alt=""><figcaption><p>New endpoints</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FhgDmcwEXHGvIXjufKBi2%2F29.png?alt=media&amp;token=69925da1-c640-4085-954d-2eeb3ac78f83" alt=""><figcaption><p>Alarms screen in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FVF7jza2k30LLDk4DJOWj%2F30.png?alt=media&amp;token=9fccf4b2-9df9-4707-bf0b-79c2ca097f18" alt=""><figcaption><p>Example Payload</p></figcaption></figure>

**Note**: This should be used in conjunction with the new configuration endpoints to support alarms:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FNnF8OZKo21XttTHY8XPF%2F31.png?alt=media&amp;token=9edcbf61-0856-4166-878b-62d95be8bf4e" alt=""><figcaption><p>Configuration ednpoints for Alarms </p></figcaption></figure>

### Companies

You can now identify staff members that are full contacts via the links collection on the 'GET /companies/{id}/staffMembers' endpoint:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FrtwYOXWL2ZYLLz8ZHFAH%2F32.png?alt=media&amp;token=f38df188-99ff-474e-b930-7a72d0fb38a5" alt=""><figcaption><p>Example of a contact and a non-contact registered as staff members on a company record in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FcvvfUZvSrRYWL9sT7guq%2F33.png?alt=media&amp;token=56fddb9b-f9d4-4c00-ac16-1486522fd184" alt=""><figcaption><p>Example payload showing the difference between the 2 staff members</p></figcaption></figure>

**Identifying the main staff member**

In the Reapit CRM, you can set a staff member as the main contact. This is now reflected in the payload via ‘`isMainContact`’ set as true:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FGojU9AJFZM9m9lGQzCOX%2F34.png?alt=media&amp;token=497dc7a5-2d28-410e-8611-3d6636bf56e5" alt=""><figcaption><p>Example of ‘Staff Member 1’ set as the main contact</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fd5iLlKH3S6VfCjVWuPI1%2F35.png?alt=media&amp;token=65474509-67e8-4de3-8ca8-381e122ccaa9" alt=""><figcaption><p>Example payload</p></figcaption></figure>

### Configuration

**Contact Categories**

It is now easier to identify the parent group of a contact category, as we have introduced a new field ‘`value`’ under the ‘GET /configuration/contactCategories’:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FqoeMg24wEtQVS8TGMZPn%2F36.png?alt=media&amp;token=6134a340-ef13-4b2a-9869-136f0698ce09" alt=""><figcaption><p>Example list of contact categories in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FeNRx5pWpTjgKoxqD9OHM%2F37.png?alt=media&amp;token=5018814e-e54e-4826-a312-59f784e7424d" alt=""><figcaption><p>Example payload</p></figcaption></figure>

### Tenancies

The `'currency'` value is now surfaced on a tenancy (previously was only available on the  Properties, Applicants or Offer endpoints):

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F2cHWSMJiBFd8b5K35PQ7%2F38.png?alt=media&amp;token=c3d51b23-da61-455b-9c15-e7f9d6d3dd11" alt=""><figcaption><p>Example payload showing the ‘currency’ field</p></figcaption></figure>

**Inspection Frequency**

Initial Inspection Frequency (`initialInspectionFrequencyInDays`) & Inspection Frequency (`regularInspectionFrequencyInDays`) are now available via the Tenancies endpoint:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FdIsXjbFE9CwSm7T9Gtrr%2F39.png?alt=media&amp;token=0f8b3fb4-0e76-42f6-a404-90f207caad94" alt=""><figcaption><p>Example fields in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FSyvrL6O1TIzsI8ZbNstT%2F40.png?alt=media&amp;token=31db995b-bf60-4311-82d5-76dd148ed1fa" alt=""><figcaption><p>Example Payload</p></figcaption></figure>

### Landlords

**Preferences**&#x20;

A Landlords ‘Send Statement’ preference is now available via 'GET /landlords/{id}':

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FlKZFfwXVToYcUedZEotu%2F41.png?alt=media&amp;token=e42d0f7c-3c6b-418a-bc82-3f91c258fcbc" alt=""><figcaption><p>Send statement preferences in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FXZua5wjsdvS8I2UXH8S4%2F42.png?alt=media&amp;token=a0a8b202-f951-4862-8109-324f049b65f0" alt=""><figcaption><p>Example payload</p></figcaption></figure>

### Enquiries

**Negotiator ID**

You can now retrieve, create and update (GET/POST/PATCH) a ‘`negotiatorId`’ to the Enquires endpoint to associate a specific negotiator:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FBH0ZvgnEZGPAypZPPPNU%2F1a.png?alt=media&amp;token=cafd591b-d66f-4332-9c2f-8f0c2f93de24" alt=""><figcaption><p>Example 'negotiatorId' field in the payload </p></figcaption></figure>

### Tasks

**New parameter**

You can now run a partial (like) search/filter based on the ‘text’ field:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fm1zhJhBNnUYq6De6bKCP%2F43.png?alt=media&amp;token=ad99a1e5-24bc-437c-84ac-04deba58c967" alt=""><figcaption><p>Example 'text' filter</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F5KxMVmEY2yLsn9TtoHBP%2F44.png?alt=media&amp;token=6028d053-0bd9-4722-aa67-b6c1d35ed04b" alt=""><figcaption><p>Example payload</p></figcaption></figure>

## 30/04/24

### Journal Entries

New endpoint ‘GET /journalEntries/landlords’ to support specific journal entries for landlords, with the following query parameters:

* pageSize/pageNumber
* landlordId
* propertyId
* negotiatorId
* type
* createdFrom/createdTo&#x20;

**Note**: Your app/integration will need the ‘Read journal entries’ permission/scope to interact with this endpoint.

### Applicants

We have updated the applicants endpoint to support setting an archived record as ‘active’. This is the only change that can occur to archived data on the applicants endpoint:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FAD86gB6TtdMpxi7u8Cht%2FWS30041.png?alt=media&amp;token=79666470-5f18-4ff6-9fbb-24e19ef2fa72" alt=""><figcaption></figcaption></figure>

### Analytics Schema

‘No Internet Advertising’ is now available on the PROPERTIES view as ‘INTERNET\_ADVERTISING’:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FAUUldkWZqD59K1NOtKxO%2FWS30042.png?alt=media&amp;token=5a7e8ac5-45a4-4045-b451-86b4bee5c0b3" alt=""><figcaption><p>Internet Advertising field </p></figcaption></figure>

### Properties

A new field to support recording if deposit schemes are accepted on a lettings property. ‘`depositSchemeAccepted`’ has been added to the properties endpoint:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FJ1ZcZaDoniEOiQG73KHq%2FWS30043.png?alt=media&amp;token=cb16a8bf-ee91-4985-afe7-fe637af5fddf" alt=""><figcaption><p>Deposit Scheme check box in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F1bK3SJ6L70FDHEkfjguy%2FWS30044.png?alt=media&amp;token=798efe1e-1466-4375-b339-146a1680fed5" alt=""><figcaption><p>Field in the Properties API</p></figcaption></figure>

&#x20;**Note**: The field is only available in the Reapit CRM from versions 12.182 +&#x20;

## 31/03/24

### Tenancies

We now expose the occupy date (`occupyOn`) and vacate date (`vacateOn`) for each tenant on a tenancy.

Retrieving a specific tenancy on the `/tenancies/{id}` endpoint will return a list of all tenants linked to that tenancy, both past and present.&#x20;

The `vacateOn` field indicates the date a tenant vacated the property. The `occupyOn` field indicates the date the tenant became a tenant.

All communications triggered via this endpoint will be sent to every tenant listed, unless logic is applied to remove them using relevant dates.

### Properties

Within the property payload you can retrieve information relating to available services:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FJPdxRTXXi3CvkddCUydR%2FWS31031.png?alt=media&amp;token=a1a3e561-ae2c-44db-8c61-6f25b4a1eea4" alt=""><figcaption><p>Available services screen in Reapit</p></figcaption></figure>

The list of services is configurable in the system and differs between customer systems. As such, the new GET /configuration/propertyServiceTypes endpoint should be used to when interpreting this data.

Occupier information relating to a lettings property is now available within the links collection:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FtyggjYa9sLRJquyF7Ecc%2FWS31032.png?alt=media&amp;token=3482d350-18ab-43dc-9f20-d8ddea544481" alt=""><figcaption><p>Occupier selection in Reapit</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FhkeFGpFYRI9wNQxKQ2B6%2FWS31033.png?alt=media&amp;token=ef8b8e54-337c-402c-a405-3ce7a4dcbfa1" alt=""><figcaption><p>Occupier details in the links collection </p></figcaption></figure>

Sub Agent Terms are now available on the properties under the selling model:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fs5egJZupkSKf3PtViIzm%2FWS31034.png?alt=media&amp;token=6d24d387-ffc6-4918-b588-4041efa3021d" alt=""><figcaption><p>Sub Agents Terms Model </p></figcaption></figure>

### Marketing Consent

A new string ‘marketingconsent’ has been added to:

* Applicants
* Vendors
* Tenancies
* Landlords
* Offers

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FXHeTf59UjXYrsweNMazJ%2FWS31035.png?alt=media&amp;token=92c9b2d0-1c60-4266-853b-47c8a913c990" alt=""><figcaption><p>Marketing Consent Field</p></figcaption></figure>

### Analytics Schema

New ' PROPERTY\_SALES\_CERTIFICATES' view:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fk4dzPQ4C8JxvWZF2oIoc%2FScreenshot%202024-04-17%20112153.png?alt=media&amp;token=3abea866-c23f-4a9a-a25b-e9bbf153ce69" alt=""><figcaption><p>New Property Sales Certificates View </p></figcaption></figure>

Added a new View ‘‘TENANCY\_STATUS\_CHANGES’. Similar to the view ‘PROPERTY\_STATUS\_CHANGES’, we have created a view to surface: TA (Tenancy Arranging), TC (Tenancy Current), TX (Tenancy Cancelled), TF (Tenancy Finished):

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FwfsvtgnwNGji1n2q7Tfz%2FWS31037.png?alt=media&amp;token=d3462774-29a7-49ee-a8c3-4c65ed57b8f8" alt=""><figcaption><p>New Tenancy Status Changes View</p></figcaption></figure>

Within the Analytics schema we are now surfacing ‘Management Period’ information in the Properties View:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FGisdztV7UBPkSwYJcAMX%2FWS31038.png?alt=media&amp;token=9e04af47-bb68-4d29-9fba-e7718d24b4ef" alt=""><figcaption><p>Management Period fields in Reapit</p></figcaption></figure>

&#x20;The ‘ONE\_OFF\_FEE\_NARRATIVE’ column has been added to the TENANCY\_ALTERATIONS view:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F717vj7styG67XRStwlyi%2FScreenshot%202024-04-17%20110848.png?alt=media&amp;token=e5845e79-2e3a-4e82-848b-e9dfd066c0f1" alt=""><figcaption><p>One-off fee field in Reapit </p></figcaption></figure>

&#x20;

New fields ‘LETTINGS\_RENT\_COLLECTION\_PERCENTAGE’ and ‘LETTINGS\_RENT\_COLLECTION\_AMOUNT’ have been added to the PROPERTIES view:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FKoId6BsqrCxSHRns7OUH%2FWS310310.png?alt=media&amp;token=6cee0f25-be35-4418-96d7-367f1f774fb4" alt=""><figcaption><p>New fields in the Properties View</p></figcaption></figure>

&#x20;

Added a new ‘EXCHANGE\_DUE’ field to the OFFERS view:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F1O24CEsej7Kad7faeN6F%2FWS310311.png?alt=media&amp;token=b07ca967-e614-4ab5-957f-fa4bb88514be" alt=""><figcaption></figcaption></figure>

&#x20;

‘HAS\_RENT\_INSURANCE’ has been added to the  tenancies view and we have also created a new ‘PROPERTY\_LETTINGS\_RENT\_INSURANCE’ view:

•       ID\
•       POLICY\_START\_DATE\
•       POLICY\_END\_DATE\
•       PREMIUM\_AMOUNT (take into account config)\
•       PREMIUM\_PERCENTAGE (take into account config)\
•       AUTO\_RENEWS (Yes/No)\
•       \_CUSTOMER\_ID\
•       \_LAST\_SYNCH\_AT

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FMhyrgaSYDi0GNoNpqXto%2FWS310312.png?alt=media&amp;token=36130cfb-9c55-4f37-a7ce-ae8b96608edd" alt=""><figcaption><p>Rent insurance information in Reapit</p></figcaption></figure>

Added a new ‘APPLICANT\_LOCATION\_REQUIREMENTS’ view:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fx1NmF9GkbMpZUe8kKWki%2FScreenshot%202024-04-17%20111725.png?alt=media&amp;token=94ff53b6-ae30-4162-8568-0c687fd05bbc" alt=""><figcaption><p>Applicant Location Requirements view </p></figcaption></figure>

&#x20;

Added a new ‘REQUIRED\_BY\_DATE’ column to ‘TENANCY\_CHECKS’ view:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FmbgvHi0QWZGLsLRH8AO7%2Fimage.png?alt=media&amp;token=4d5af9dd-d22a-454d-9033-67fc0924d9f0" alt=""><figcaption><p>Required By Date field </p></figcaption></figure>

### Reapit CRM

Discover our latest comprehensive release notes for the Reapit CRM, detailing new features and enhancements to our desktop application [here](https://reapit.atlassian.net/wiki/spaces/RW/pages/138903634/Release+Notes+index).

## 29/02/24

### Properties API

Subplot identification is now available via the properties API under '`developmentSiteType'` and extended to webhooks for properties 'created' & 'modified':

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FGZDF8shLVxUkvRq3lKvi%2FWS11103.jpg?alt=media&amp;token=e0bc9e5e-c74d-4e68-af29-09eb95410ca7" alt=""><figcaption><p>Development Site Types</p></figcaption></figure>

A new sub resource on the property images endpoint (POST propertyImages/reindex) to support image reordering:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FddTCgzxVi5ldIsn9neE5%2FWS08032.png?alt=media&amp;token=deaca84e-19f8-4ee2-8ed7-213b183220a1" alt=""><figcaption><p>Example POST payload on propertyImages/reindex</p></figcaption></figure>

&#x20;

‘Other Agent Appraisals’ information for GET, POST & PATCH is now available and can be located as a sub resource on the properties endpoint:

* GET properties/{id}/appraisals
* GET properties/{id}/appraisals/{appraisalId}
* POST properties/{id}/appraisals
* PATCH properties/{id}/appraisals/{appraisalId}

&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FAQm155YPug49reAP2xCh%2FWS08033.png?alt=media&amp;token=9b9701bf-d468-46a6-842f-30bc50e02c2e" alt=""><figcaption><p>Other Agent Appraisals section on the Reapit CRM</p></figcaption></figure>

### Offices

&#x20;A new query string parameter has been added to the offices endpoint to support ‘Region’ filtering:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FBiVYouJ3e7um7PlHiAyR%2FWS08036.png?alt=media&amp;token=46d1f163-292d-4a40-bedd-feca0883c87a" alt=""><figcaption><p>Region filter on 'Offices' </p></figcaption></figure>

### Analytics Schema

A negotiator's profile image (PROFILE\_IMAGE\_URL) has been added to the NEGOTIATORS view:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FdJ44FqlVyOZIPdRdFz2U%2FWS08037.png?alt=media&amp;token=0f206c1b-ac04-4003-9130-96db78334297" alt=""><figcaption><p>Profile Image URL Field in the Analytics Schema documentation</p></figcaption></figure>

We have also added alternate/old codes to the PROPERTIES view, which can provide a means of identifying properties either by giving them an alternate reference number that is more meaningful, or being able to locate properties by an old system code when a customer has migrated to a Reapit product.

### Companies API

We now surface the following communication preferences (read and write) for companies:

Email, Letter, Phone & SMS&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FCl5A4K8FuzwbP8lXMVS2%2FWS08038.png?alt=media&amp;token=dafef6ed-a339-4792-821b-774140ce787f" alt=""><figcaption><p>Communication preferences on a Company record in the Reapit CRM</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F8wcMFsk0Ps1o8qMz8fJX%2FWS08035.png?alt=media&amp;token=84fb4b15-f437-41c5-bbc7-d596415f3e31" alt=""><figcaption><p>Communication Preferences fields in the Companies API </p></figcaption></figure>

&#x20;

### Webhooks

**Deprecation Notice:** On **1st September 2024** we will be retiring the legacy webhook signing mechanism in favour of the now more widely adopted cryptographic signing method.&#x20;

You only need to take action if you are currently reading and validating the `Reapit-Webhook-Signature` header that is included with all webhook events. You will need to update your webhook handler to switch over to using the `X-Signature` header instead, using the method outlined in the developer [documentation here](https://foundations-documentation.reapit.cloud/api/webhooks#securing-your-endpoint), which includes code samples for both Node and .NET.&#x20;

If you are not currently validating the sender of the webhook event, it is highly recommended that you introduce this important security feature and implement validation of the X-Signature header to protect your own systems.&#x20;

If you require any assistance updating your application, please reach out to us on [Github](https://github.com/reapit/foundations/issues/new/choose) where we will respond in line with our development processes.&#x20;

### Reapit CRM

Discover our latest comprehensive release notes for the Reapit CRM, detailing new features and enhancements to our desktop application [here](https://reapit.atlassian.net/wiki/spaces/RW/pages/138903634/Release+Notes+index).

&#x20;

&#x20;

## 31/01/24

### Tenancies

A new '`managerId'` (Tenancy Manager) field has been added to the TenancyModel:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FkS2wLgOA9Js7iAlRl0J8%2FWS31011.png?alt=media&amp;token=8efd0ea7-f83d-4c0d-8210-d90d4d7a16d6" alt=""><figcaption><p>Tenancy Manager field in Reapit</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FyyPTwM33zhdyK3qz9Q6w%2FWS31012.png?alt=media&amp;token=2c647aab-378d-43de-ab30-f3fc29213380" alt=""><figcaption><p>Related <code>managerId</code> field</p></figcaption></figure>

### Referrals

A new POST referrals endpoint has been added to allow the creation of referrals via the Platform. Customers using the Marketplace Management app will have the option of restricting which referral types an app or integration has access to:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FlHng5KZHvsPMKE1Q60nA%2FWS31013.png?alt=media&amp;token=176dd843-71f9-4fcc-baa2-9161f8152fd2" alt=""><figcaption><p>Referral panel in Reapit</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FkPx0ZcqfzzllC8yt1cqO%2FWS31014.png?alt=media&amp;token=da3dac0d-8c8b-46da-af82-bdf85e3c0cc3" alt=""><figcaption><p>POST referrals endpoint</p></figcaption></figure>

&#x20;

### Appointments

Appointments in Reapit now provide an ‘Attendance’ option. This has been added to the Appointments API in the Platform under ‘`attended`’:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FFJ7Z3WS12NAS3i3PiofZ%2FWS31015.png?alt=media&amp;token=fa133162-8980-4d87-b5ff-cfaf4673f12a" alt=""><figcaption><p>Attendance field on an appointment in Reapit</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FycdtAe2hNzPQXUKZPaKM%2FWS31016.png?alt=media&amp;token=5f0c0353-bef5-4d03-a3a0-202556e0c3a1" alt=""><figcaption><p><code>attended</code> field in the Appointments API</p></figcaption></figure>

### WorksOrders

A new ‘`reserveAmount`’ field has been added to the WorksOrder payloads that maps to the ‘main float’ in Reapit. The main float is the amount of funds to be held back by the agent in landlord payment runs to cover the cost of any works required by the works order item. For full validation and behaviour rules, please review the following ticket: <https://github.com/reapit/foundations/issues/8758>:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FEFrIpy61iAJcEXu2oQuC%2FWS31017.png?alt=media&amp;token=20852034-6037-40a0-8b98-9028375d0335" alt=""><figcaption><p>New <code>reserveAmount</code> field in the WorksOrders API </p></figcaption></figure>

## 31/12/23

### Tenancies API

**References and Guarantors**

It is now possible to retrieve a guarantor's '`id`', '`guarantorAssociatedId`', '`type`' & '`referenceStatus`' from the tenancies/{id}/relationships endpoint:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FcZtKkJEufSo2Omy4qZH2%2FWS04011.png?alt=media&amp;token=926ba060-4c55-4c94-a39a-bc7e05985957" alt=""><figcaption></figcaption></figure>

Above is an example of a single guarantor associated to a tenant in AgencyCloud.

Using the tenancy ID and calling the GET tenancies/{id}/relationships endpoint, it will return the following in the ‘guarantors’ object:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F3GuXgXhLlJo8KmWleaZ9%2FWS04012.png?alt=media&amp;token=ffe0ce3a-34b6-4f79-a831-5c74e5253669" alt=""><figcaption></figcaption></figure>

Multiple guarantors will be displayed as below:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FlAyag37TypkF2uDBsxGr%2FWS04013.png?alt=media&amp;token=4d3ab723-832a-4183-857f-bca79d756c5a" alt=""><figcaption></figcaption></figure>

**References:**

Below is an example of a single contact added as a reference to a tenant in AgencyCloud:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FGljJX87dfRuCNWFrykF3%2FWS05014.png?alt=media&amp;token=c350309a-c937-4d62-a020-7e88c1ffca50" alt=""><figcaption></figcaption></figure>

Using the tenancy ID and calling the GET tenancies/\[id}/relationships endpoint, it will return an '`id`', ‘`referenceAssociatedId`’, ‘`type`’, ‘`referenceStatus`’ & ‘`referenceType`’ in the ‘references’ object:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FTd7ltaNWRSAFLFKYnzzK%2F5WS05014.png?alt=media&amp;token=6c82b147-a25d-4285-a8bb-733936d3bfb5" alt=""><figcaption></figcaption></figure>

## 30/11/23

### Properties API

We have added a new sub resource to our Properties endpoint to obtain Property Certificates without the need to specify a Property Reference (ID):

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FV4jAihNOuuObnyOakBTF%2FWS30111.png?alt=media&amp;token=95b64465-be5b-4246-8cab-e84b5265dd1e" alt=""><figcaption></figcaption></figure>

In addition to this and to support the 'Certificate Management' functionality in AgencyCloud (desktop CRM), an endpoint to understand the certificate responsibility (GET /properties/{id}/certificates/responsibilities):&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FIRUm0NX9AD7dqfplOxPM%2FWS3012.png?alt=media&amp;token=1c6c3997-8ecd-40bf-aedb-4ccb3a597ff7" alt=""><figcaption><p>Certificate Management screen in AgencyCloud</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FgF9AnZ0DfYMOrYhXBXN0%2FWS30113.png?alt=media&amp;token=33953277-09da-4107-802c-13097658479b" alt=""><figcaption><p>Example payload showing <code>responsibleParty</code></p></figcaption></figure>

## 31/10/23

### Appointments API

Two new filters added to the Appointments endpoint, ‘followUpFrom' and 'followUpTo’:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FeiWuSKHutzuWupSzRnOr%2FWN311001.jpg?alt=media&amp;token=4c0c6347-813a-4389-9985-20281d1aeeb2" alt=""><figcaption><p>New Follow Up filters </p></figcaption></figure>

**Related ticket:** <https://github.com/reapit/foundations/issues/10018>&#x20;

### Tenancies API

‘paymentPlan’ is now surfaced under the Tenancies endpoint:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F2JhDxq5WHEhI13klO85t%2FWN311002.jpg?alt=media&amp;token=07a56c8a-6998-4cd5-adbe-0afee122c810" alt=""><figcaption><p>Payment Plan field</p></figcaption></figure>

**Related ticket:** <https://github.com/reapit/foundations/issues/9909>&#x20;

### Negotiators API

We are now returning the Business number in the negotiators endpoint under the 'additionalContactDetails' object:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FWlmZlS8eyCvsbAWMQf6R%2FWN311003.jpg?alt=media&amp;token=92c356e7-0452-4801-b9cc-805244cac791" alt=""><figcaption><p>Additional Contact Details Object</p></figcaption></figure>

**Related ticket:** <https://github.com/reapit/foundations/issues/9792>

### Landlords API

You can now filter the Landlords endpoint by associated officeID:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FHr88P5VFzEsixx752tHA%2FWN311004.jpg?alt=media&amp;token=eaa3b072-257d-41cf-8081-3a4695c5eed8" alt=""><figcaption><p>Office ID Filter</p></figcaption></figure>

**Related ticket:** <https://github.com/reapit/foundations/issues/9791>&#x20;

### Properties API (Certificates)&#x20;

Visibility of the ‘status’ is now presented on a property certificates with an associated up to our configurations endpoint (/configurations/certificateTypes):

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FMrm8BkEITwnGNr35XC1u%2FWN311005.jpg?alt=media&amp;token=8baccd08-6b4d-43b5-990b-5290830b01d3" alt=""><figcaption><p>New statusID field example</p></figcaption></figure>

**Related ticket:** <https://github.com/reapit/foundations/issues/9126>&#x20;

### Webhooks

We have released an update to our webhooks package to support app authentication rotation

**Related ticket:** <https://github.com/reapit/foundations/issues/9915>&#x20;

### Enquiries API

Revised support on the enquires endpoint for office groups (customers using the Marketplace Management App)

**Related ticket:** <https://github.com/reapit/foundations/issues/10076>&#x20;

### Documents API

We are now returning a more meaningful error when the physical file does not exist

**Related ticket**: <https://github.com/reapit/foundations/issues/10005>

&#x20;

## 30/09/23

### Tenancies API

You can now POST the ‘breakFrom’ and ‘noticeRequired’ fields in the 'tenancies/{id}/breakClauses endpoint':

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FNYyXlH8GS4h46x144cdP%2FWN30091.png?alt=media&amp;token=adccdeb8-3c51-4a32-ad1f-a27e35e41d64" alt=""><figcaption><p>POST Endpoint</p></figcaption></figure>

&#x20;

### Journal Entries

We are now automatically posting a journal entry using a new Journalisation package when the following occurs:

* When a new property is registered:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fvi9aMmLwV77W4TaT9pgV%2FWN30092.png?alt=media&amp;token=8f6afadb-dea6-47c6-9fa6-66e584f2e74b" alt=""><figcaption><p>Property Registered Journal Entry</p></figcaption></figure>

* When a new applicant is registered:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F9cRMItQrL63nyEDSvXC2%2FWN30093.png?alt=media&amp;token=1f682f22-c053-49ee-a286-fc61947526a0" alt=""><figcaption><p>Application Registered Journal Entry Example</p></figcaption></figure>

* When a new contact is registered:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F4PYmeQ0dBwt1rSNyAl2I%2FWN30094.png?alt=media&amp;token=7f4f6a46-0018-4083-bc54-2f5850b09c39" alt=""><figcaption><p>Contact Registered Journal Entry Example</p></figcaption></figure>

* When we detect a change to the contact consent flag:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FSVeVHfu13fyJCOqZs1FW%2FWN30095.png?alt=media&amp;token=c2330e93-3b30-4326-b594-f90a6fbef874" alt=""><figcaption><p>Marketing Consent Journal Entry Example</p></figcaption></figure>

### Properties API

Two new fields have been added to the EPC model to expose the ‘First Page URL’ (`firstPageDocumentUrl`) and ‘Full Document URL’ (`fullDocumentUrl):`

&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FmI15MR0hPFiiO9yqgjRj%2FWN30096.png?alt=media&amp;token=7b9f3164-2597-4dbd-b53a-294301ba5db6" alt=""><figcaption><p>EPC Section in AgencyCloud</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FXmQOd0vXeEADA9WojtDA%2FWN30097.png?alt=media&amp;token=769a6e77-432d-44fb-83b1-4842358ebd77" alt=""><figcaption><p>Example EPC Payload </p></figcaption></figure>

&#x20;

## 31/08/23

### Offices API

The latitude and longitude are now populated under ‘geolocation’ for offices in the Offices API:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FTY5DUVnZelC5wR3rhK8t%2FWN31081.png?alt=media&amp;token=c6164d68-423b-4694-b0c5-4b9ef38191b9" alt=""><figcaption><p>Example Sandbox Office</p></figcaption></figure>

### Analytics Schema

We have added a new view ‘PROPERTY\_STATUS\_CHANGES’, to the Analytics Schema to expose a simple view of property status changes.  The new view includes the following fields:

* ID
* PROPERTY\_ID
* PROPERTY\_CODE
* OLD\_STATUS
* NEW\_STATUS
* CHANGED\_AT
* \_CUSTOMER\_ID
* \_LAST\_SYNCH\_AT

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FON1EkAy1167TSKQQbYNs%2FWN31082.png?alt=media&amp;token=5ad91899-8330-4600-bd14-7f9409d4d1ab" alt=""><figcaption><p>Property Status Changes View</p></figcaption></figure>

Property Manager field in AgencyCloud is now exposed under '‘LETTINGS\_PRIMARY\_PROPERTY\_MANAGER\_NEGOTIATOR\_I’ in the Analytics Schema.&#x20;

&#x20;

### Tenancies API

We have extended both the POST and PATCH tenancies endpoint to support Letting Fee (`lettingFee`) and Management Fees (`managementFee`):

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fh8Y5CAUJKMaR9ohiw9M7%2FWN31083.png?alt=media&amp;token=d9a92f19-49d3-495c-9e17-4cda5d738d4a" alt=""><figcaption><p>Letting &#x26; Management Fee fields (POST)</p></figcaption></figure>

&#x20;

### Properties API

Next Call (nextCall) and Last Call (lastCall) are now exposed in the properties API:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fp5KMQeqxcdocDeREd4MM%2FWN31084.png?alt=media&amp;token=2e0ce6d9-b4f1-4f0e-8f8c-8036f466a2c2" alt=""><figcaption><p>Last and Next call fields</p></figcaption></figure>

&#x20;

### Enquiries API

A new endpoint has been added to support updating existing enquiries:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FHEHarVwc9U7UvaeDOvUA%2FWN31085.png?alt=media&amp;token=86dfc0a7-7889-4605-86b8-79121e0b36dc" alt=""><figcaption><p>New Enquires endpoint</p></figcaption></figure>

## 31/07/23

### Properties API

If enabled, Rental Insurance information is now available under the ‘PropertyLettingModel’:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FyDDdJbIm6VxeZu84ui2o%2FWN31071.png?alt=media&amp;token=fd14576d-94e7-45ed-993a-c21406ebfc33" alt=""><figcaption><p>Rent Insurance Model</p></figcaption></figure>

This also includes a new configuration endpoint to surface Cancellation Reasons:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FYWaBNotISU0iUWQsT0Fo%2FWN31072.png?alt=media&amp;token=92790218-5af8-4693-a2a1-6eb2726ada5a" alt=""><figcaption><p>Configuration Endpoint to support Rental Insurance </p></figcaption></figure>

Property Licensing Data is now available on the properties endpoint, displayed under the ‘PropertyLettingModel’:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FjzOBU5LA0Z4peaRQKNmT%2FWN31073.png?alt=media&amp;token=5d9c2a54-89a8-466e-822d-f5c1be0c165a" alt=""><figcaption><p>Licencing Model </p></figcaption></figure>

In addition to this, we have added a new documentation type ‘LIC/Licensing’ to the document type configuration endpoint:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F20vCAmdPoLIX3U8b3aDL%2FWN31074.png?alt=media&amp;token=41cd803a-a9cc-43cb-9ba8-5b9c02feaed9" alt=""><figcaption><p>New Documentation Type</p></figcaption></figure>

### Companies API

You now have the ability to embed ‘relationships’ via the companies endpoint:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FxZieruWzpi9zAW9E0Gf1%2FWN31075.png?alt=media&amp;token=e98e9e57-3c5a-4038-8bd4-2618434bbf30" alt=""><figcaption><p>Embed options on the Companies API </p></figcaption></figure>

### **Tenancies API**

We now support tenancy renewal options (Tenancy Agreement Clauses) in the Tenancies API:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FLkQLG8Qt90HgqSreld3V%2FWN31076.png?alt=media&amp;token=04a6a34a-001b-4818-99e7-af9ce693d974" alt=""><figcaption><p>Renewal Options Model</p></figcaption></figure>

This also includes 2 new configuration endpoints to support the tenancy renewal options and renewal optional conditions:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FHGk5rnVE6rFGC7BAl1oR%2FWN31077.png?alt=media&amp;token=4027b77f-1c23-4846-bda5-93e5b7a9da7e" alt=""><figcaption><p>Tenancy Renewal Options Configuration Endpoint</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FhBQvr9iPIgpPjuZlfwbi%2FWN31078.png?alt=media&amp;token=ef88d368-c73e-4a2f-b02f-b24523b6585b" alt=""><figcaption><p>Tenancy Renewal Option Conditions Configuration Endpoint</p></figcaption></figure>

\
In addition, we have also included a ‘lettertext’ field in the TenancyAllowanceModel (/tenancies/{id}/allowances endpoint) & the TenancyResponsibilityModel (/tenancies/{id}/responsibilities): &#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FcCrFlfkNqJbl9gJ3siwx%2FWN31079.png?alt=media&amp;token=3098e742-7645-4cb7-8ab8-dbe44f65981d" alt=""><figcaption><p>Tenancies Allowances Endpoint</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FrRz2k85pJF2Src96DRbG%2FWN310710.png?alt=media&amp;token=e2d5c4ae-094b-41b8-b93c-e72532aee26c" alt=""><figcaption><p>Tenancies Responsibilities Endpoint</p></figcaption></figure>

3 new fields have been added under the Tenancy Break Clauses endpoint (/tenancies/{id}/breakClauses) to surface Break From (breakFrom), Required Notice (noticeRequired) and Letter Text (letterText):&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FtCh3bCGhkGL0QavomK0V%2FWN310711.png?alt=media&amp;token=58d0a78e-7607-461a-895c-ef8b73211f5a" alt=""><figcaption><p>Tenancies Break Clauses Endpoint</p></figcaption></figure>

## 30/06/23

### Developer Portal

It is now possible to set the default window size of your app when it launches in AgencyCloud. Currently, all apps are launched based on the default configuration set by the customer. The standard configuration is set as Width 950 x Height 700.

Within the ‘AgencyCloud Integration’ section on your app, you will be able to adjust the size in which your app is presented in AgencyCloud:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FMnELaQ5Hu4p2Aj6UqoPL%2FApp%20Size.jpg?alt=media&amp;token=ba4b9eaa-1826-4ec2-b442-3f81c6d74f80" alt=""><figcaption></figcaption></figure>

Please note that only apps with a desktop integration type can modify the app size. If you do not have a desktop integration type, you will not be able to edit the default sizes.

### Properties

Floor Level (`floorLevel`), Property Internal Floors (`internalFloors`) & Total Building Floors (`totalFloors`) are now available both read and write:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F4VrjTm98YFWsd11yDEfT%2FWN30063.jpg?alt=media&amp;token=9619a7ff-dc02-40d2-a122-e3df644df2c4" alt=""><figcaption><p>Property Attributes in AgencyCloud</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FRL6I9eMGPF85PH9028dl%2FWN30062.png?alt=media&amp;token=6303dd9a-259e-4f2a-a3e1-a92aba489503" alt=""><figcaption><p>Example payload </p></figcaption></figure>

&#x20;

## 31/05/23

### Tenancies

We have added the field ‘checkTypeId’ to the POST /tenancies/{ID}/checks endpoint:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fys732KSud2wcQECGvbyg%2FWN3101.png?alt=media&amp;token=f40d97b7-07aa-4f3e-86ff-2ace3d428e4d" alt=""><figcaption><p>Example payload showing 'checkTypeId' field</p></figcaption></figure>

&#x20;

### Developer Portal

It is now possible to view more information about an office group installation through the DeveloperPortal.

If your app is installed by an office group, you will receive an email and a webhook (if configured) with the customer ID, for example XXX-XXXX. The first 3 characters represent the organisation, the remaining 4 characters represent the office group ID. For more information on office groups please visit: <https://foundations-documentation.reapit.cloud/faqs#what-are-office-groups>&#x20;

To see which offices are within that group, open your app in the developer portal and navigate to ‘Installations’:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FDp0Ktmixxq84WegeLC4M%2FWN3102.png?alt=media&amp;token=2c3fb011-0246-4065-a99d-87230e93fba6" alt=""><figcaption><p>'Installations' section on an App</p></figcaption></figure>

&#x20;

This will display all active installations for your app. If you have an office group installation, for example RES-GRTA:

&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F5FpHDUvk2vy9fuL2anfV%2FWN3103.png?alt=media&amp;token=0c8f000d-9fa0-48ce-aa3f-198ac74731dd" alt=""><figcaption><p>Example customer installation </p></figcaption></figure>

You will have the option under the dropdown menu to ‘Show installed offices’:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FFI4tuKEA2Cp9EGfeRCf2%2FWN3104.png?alt=media&amp;token=497d11f2-0023-4df6-8ce1-ff3eef1c8ce9" alt=""><figcaption><p>Example office group installation information</p></figcaption></figure>

This will provide you the name of the office group ‘Office Name’ and the office ID’s that form that group. From the example above, only office ‘BCK’ is in the office group ‘Market Town’.

To retrieve further information about an office, you can use the ‘ID’ in conjunction with the ‘Offices’ endpoint.

### Additional Contact Details

**Related services**: Applicants, Landlords, Tenancies, Offers & Vendors

AgencyCloud provides the option of a free text field to record additional contact information, such as ‘Wife’s Mobile’ in addition to the core fields such as Mobile, Home & E-mail.

By default, we will now return those additional contact details under the ‘additionalContactDetails’ array on the above related services.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FXKiQMjYo1sUUVkVQ71JC%2FWN3105.png?alt=media&amp;token=2667d49f-f4b4-4e8c-a889-6ddff720c887" alt=""><figcaption><p>Example AgencyCloud Applicant Record</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FEiA9ppl16olJNbY1g9Ro%2FWN3106.png?alt=media&amp;token=563cc9bd-6c6a-42f9-931c-3e474f9841ae" alt=""><figcaption><p>Example core fields on the Applicants API</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fu8gZLL5VI3IwKhjaAH1L%2FWN3107.png?alt=media&amp;token=56392e56-93c6-4cac-8b22-5c6ff815591e" alt=""><figcaption><p>Example 'additionalContactDetails' array on the Applicants API</p></figcaption></figure>

&#x20;

## 30/04/23

### Tenancies

The ‘Details/Notes’ field is now available on a tenancy under ‘feeNotes’:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FZFrSfv2n89h3BJ04dIXB%2FWN31041.png?alt=media&amp;token=bb997e56-85e3-466c-a183-738386449c74" alt=""><figcaption><p>Details/Notes field in AgencyCloud</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fk81fYE5ZZZ9CrdkdZt0P%2FWN31042.png?alt=media&amp;token=834ca5aa-cc23-4781-aea5-ecabd00ce92c" alt=""><figcaption><p>Example 'feeNotes' field</p></figcaption></figure>

&#x20;

&#x20;

### Journal Entries

A new POST /bulk endpoint has been added to allow a creation of multiple journal entries:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FA2vlLcVKKNOAWbRS4nTl%2FWN31043.png?alt=media&amp;token=fc3461d1-0250-4155-8455-1c963e452422" alt=""><figcaption><p>POST endpoint for Journal Entries </p></figcaption></figure>

&#x20;

### Configuration

We have added a new configuration endpoint ‘terminology’ to help developers understand customer specific terminology.

For example, some customers prefer to use 'Sold STC' instead of 'Under Offer' or 'Market Appraisal' instead of 'Valuation'.

Using the new configuration endpoint, this will make it easier to understand for each customer. Please see example for our Sandbox configuration:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FdKsEkpJLnhdVT7OOWEgQ%2FWN31044.png?alt=media&amp;token=25554ebd-9f61-4222-800c-890ed6841144" alt=""><figcaption><p>Example 'Terminology' payload </p></figcaption></figure>

&#x20;

It is now possible to filter by ‘Active’ status and by ‘OfficeIDs’ on the `/preTenancyCheckTypes` and `/renewalCheckTypes` configuration endpoints:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FFN8kW4wc1CMCEcvZUi4k%2FWN310455.png?alt=media&amp;token=bf484109-b5e7-405c-8048-03d51a28d550" alt=""><figcaption><p>New filtering options</p></figcaption></figure>

&#x20;

### Appointments

It is now possible to both read and write to the ‘Repeat’ field on appointments:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FYhmPRZk2VTIZBes8C38V%2FWN31046.png?alt=media&amp;token=3178517b-17c1-4856-8b4a-2760b25aaf46" alt=""><figcaption><p>Example 'Repeat' field in AgencyCloud</p></figcaption></figure>

&#x20;

### Properties

By default, the property payload will now return the name of the local authority ‘localAuthorityCompanyName’. Previously, it only returned the ID:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FjrgUhLCxFFnItrIi90vU%2FWN30049.jpg?alt=media&amp;token=5b0f015c-6ecd-4db1-b6f4-95ea4f6ffdc7" alt=""><figcaption><p>Local Authority field in AgencyCloud</p></figcaption></figure>

&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fdvgopj76gbGTYPXX7Gw6%2FWN31048.png?alt=media&amp;token=7ff154e0-7060-4b47-aa44-de3df4a081d7" alt=""><figcaption><p>'localAuthorityCompanyName' field </p></figcaption></figure>

## 31/03/23

### **DeveloperPortal**

Added Authentication Security: By default, the ‘Authentication Client Secret’ will now be hidden and only accessible by an ‘Admin’:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FrhxJTG7KPXbtedasz3Dl%2FWN31031.png?alt=media&amp;token=64545589-6273-46d0-a327-b7d7d5c8dbfc" alt=""><figcaption><p>Client Secret - Admin only</p></figcaption></figure>

\
Non Admin users will see the following:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fa1QQHWM4OE4kzICjfRXF%2FWN31032.png?alt=media&amp;token=0d431a1e-9e47-4e14-a61e-bbebe65f8f5a" alt=""><figcaption><p>Client Secret - Non Admins</p></figcaption></figure>

As an Admin, you can check or change the role of a user within your organisation by simply navigating to the ‘[Members](https://developers.reapit.cloud/settings/members)’ area.\
&#x20;

### **Applicants**

We now support the option for 'Four Weekly' rent frequency on Applicants:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FSZrNap19dQ8ItxcjGDqA%2FWN31033.png?alt=media&amp;token=a4e6afcb-0e1e-4f30-86dd-19bf580fe818" alt=""><figcaption><p>Rent frequency in AgencyCloud</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fq7Qp6Jp2XJKnR1eSsKKG%2FWN31034.png?alt=media&amp;token=e83ff9c9-3693-46c6-884f-13aac4c2c0f8" alt=""><figcaption><p>Rent frequency example </p></figcaption></figure>

&#x20;\
&#x20;<br>

### **Properties**

Agreement signed is now available under the Property Letting Model:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Ffm9AhKjzAcOjOm2986MB%2FWN31035.png?alt=media&amp;token=e3287e18-b613-4d5b-a6f9-8e53d8561356" alt=""><figcaption><p>Agreement Signed field in AgencyCloud</p></figcaption></figure>

### **Appointments**

Other Agent information has now been added to appointments `otherAgent` with the otheragentId available in the \_links collection

### **Journal Entries**

The list of allowed journal entry types has been expanded to now include ON (offerNote):

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FlyGANlPy9ErEkhNFmnAk%2FWN31036.png?alt=media&amp;token=876cd8db-aec3-4f0c-b5d5-d0eef92decf0" alt=""><figcaption><p>Example offer note</p></figcaption></figure>

## 28/02/23

### Applicants

Two new filters have been applied to the Applicants endpoint to allow filtering by ‘Last Call’ (`hasLastCall`) and ‘Next Call’ (`hasNextCall`):

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FufvkCMRBfcly8a9UafDN%2FWN28021.png?alt=media&amp;token=f97bd40d-8bda-4561-a2c8-60ea28b85235" alt=""><figcaption><p>'Next Call' section in AgencyCloud</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FiyEHonwdX5fw9svYOABo%2FWN28027.jpg?alt=media&amp;token=5858a1ab-f62c-4fb6-a624-e407f6cb1efd" alt=""><figcaption><p>Filtering options </p></figcaption></figure>

### Configuration

We have added additional information on the ‘preTenancyCheckTypes’ configuration endpoint to surface if a check is ‘active or inactive’ and which offices the check applies to e.g. OXF, MKN:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FAkUSCqREC3TupXqc3eBr%2FWN28023.png?alt=media&amp;token=c792c216-5c23-4d28-a400-8de9fcf56196" alt=""><figcaption><p>Example payload showing 'active' and 'officeIds' fields</p></figcaption></figure>

&#x20;

### Analytics Schema

Management Fee information (percentage & amount) is now available in the Analytics Schema under the Tenancy Renewal table:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FPHMDP0t27S5DxjWEYt2J%2FWN280224.png?alt=media&amp;token=afc9b7ec-9448-44fb-bc03-82163d1f6ea2" alt=""><figcaption><p>Fields available in the Analytics Schema</p></figcaption></figure>

### Developer Edition&#x20;

The Developer Edition has been upgraded to 12.160 which now includes a new desktop integration type of ‘Renewal Negotiation Check’

‘Renewal Negotiation Check’ can be given to an application that will replace the checks section on a Renewal Negotiation screen in AgencyCloud.

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fu8BIIqaqAuAsLRAwRHqo%2FWN28025.jpg?alt=media&amp;token=a26018ac-7252-4fae-b68c-b0b6de388549" alt=""><figcaption><p>Checks section in AgencyCloud</p></figcaption></figure>

For more information on this desktop integration type, please [visit](https://foundations-documentation.reapit.cloud/api/desktop-api#renewal-negotiation-check).&#x20;

Also coming soon, the ability to launch apps from the images section in AgencyCloud.

## 31/01/23

### Property Images

The property images endpoint now respects the maximum dimensions that are set in a customer's configuration. &#x20;

### Tenancies

When a tenancy is in an arranging status, we now expose the contacts associated to the attached applicant in the `related` collection.&#x20;

### Contacts

Company information is now returned on a contact under the company link.

### Properties

Converted room dimensions are now returned on a property under ‘`dimensionsAlt`’.&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FdZeWzYOKosuVOOxfooqj%2FWN3101231.png?alt=media&amp;token=b48a4bd7-4342-4ce8-8b89-84f9ae833b7e" alt=""><figcaption><p>Property Rooms and Accommodation screen in AgencyCloud</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fci7vmPtdGgRXiRW2CNDY%2FWN3101232.png?alt=media&amp;token=c1286f3d-1193-4952-8c24-6f1ad697c14c" alt=""><figcaption><p>Example 'dimensionsAlt'</p></figcaption></figure>

### Design System

Release 4.0.0

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FhiFJCD5WvBptY7JpPPeF%2Fimage%20(1).png?alt=media&amp;token=6ef5304c-f0ef-4dba-b3fd-784fdaae9b7b" alt=""><figcaption></figcaption></figure>

**New Features**

* Visual Language has been revamped with detailed rules for icons, fresh new icons and improved styling for better visual consistency.
* Iconography (Visual Language section) has been reorganised into new categories.
* Product Brand Imagery (Visual Language section): a full set of illustrations was added to the collection.
* Mobile navigation has been added to UI Elements&#x20;

**Bug Fixes**

* Reapit and ReapitConnect logo sizes have been adjusted
* ReapitConnect logo is now a vectorial image
* One Choice Chips (Segmented Control) has been renamed to Toggle Button. Its width size changed from static to dynamic.
* Desktop - Full Options Expansion Panel style has been changed (shadow and outline)

## 30/12/22

### Applicants API

Custom applicant attributes that are usually captured on the requirements screen under ‘Must Have’ or ‘Special/Special Requirements’, are now surfaced for applicants under ‘specialFeatures’:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FQz4982enJDIqQRsOmLE1%2FWN03011.jpg?alt=media&amp;token=2a998ea4-90f1-45b2-a1ff-b5e7d097534c" alt=""><figcaption><p>Applicant Requirements screen in AgencyCloud</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F0nN9NlyVU7zczhuGUgp0%2FWN03012.jpg?alt=media&amp;token=2b160279-68ec-4df5-bf49-ed9a321a1165" alt=""><figcaption><p>Example Special Features Data</p></figcaption></figure>

&#x20;The ‘Renting Position’ is now surfaced on an applicant under ‘`renting.positionId`’:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FIqWC1YOVaQdGTTfhZejH%2FWN03013.jpg?alt=media&amp;token=d29175e4-a015-4cc7-b32f-182b1e2b62d7" alt=""><figcaption><p>Applicant status screen in AgencyCloud</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FUap7hpgBtett5BOHqF3R%2FWN03014.jpg?alt=media&amp;token=1e8afa5a-3369-4e81-8189-17afefd85bce" alt=""><figcaption><p>Example 'positionId'</p></figcaption></figure>

**Note:** The renting position list is configurable and can be cross referenced against a new sub-resource under the Configuration endpoint ‘GET /configuration/rentingPositions’.

&#x20;

### Transactions API

You can now create pending supplier invoices using the new sub-resource under the Transactions endpoint ‘POST /transactions/supplierInvoices’:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FFtUwLSCTHd0XYDvxA6ai%2FWN03015.jpg?alt=media&amp;token=9e91c2eb-2872-42e4-9355-23ec824a3dec" alt=""><figcaption></figcaption></figure>

For the full specification, validation, and behaviours, please review ticket <https://github.com/reapit/foundations/issues/7764> in conjunction with the swagger documentation.

&#x20;

### Analytics Schema

‘Tenancy Alterations’ data is now included in the Analytics Schema:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FWFWHyvqUo9yrvRQLFskm%2FWN03016.jpg?alt=media&amp;token=8e37d815-00d6-449d-9799-75fbfba2734d" alt=""><figcaption><p>Analytics Schema </p></figcaption></figure>

## 30/11/22

### Applicants API

It is now possible to set an applicant as a Potential Client (`potentialClient`):

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FGnnOt9grMiw0ByNxhwhj%2FWN30117.png?alt=media&amp;token=f9657ae9-9dee-443a-90ce-3b13c04b6f82" alt=""><figcaption><p>Applicant Status screen showing the 'Potential Client' field In AgencyCloud</p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F5cgtK5Z2W5yqZrRlngmv%2FWN30118.png?alt=media&amp;token=a4cd1306-2805-459a-bd2a-7822358de8ff" alt=""><figcaption><p>Potential Client field</p></figcaption></figure>

We are now surfacing remaining lease (`leaseRemaining`) information on Applicants:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fqn0ikLm8eoeei01wxXLd%2FWN30112.jpg?alt=media&amp;token=1e1205a2-b768-44bd-b06e-0ad17a78908e" alt=""><figcaption><p>Applicant Requirements screen showing the 'Remaining Lease' fields in AgencyCloud  </p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FvELPh1pxWwE63x76Dqyb%2FWN30113.png?alt=media&amp;token=96cd3d37-6552-441b-8c58-9f90d4f3e742" alt=""><figcaption><p>Reaming Lease field</p></figcaption></figure>

&#x20;

### Analytics Schema&#x20;

'Pre Instruction Checks' data is now included in the Analytics Schema:  &#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FOCw0h4EGYvh6kYp6Pcza%2FWN30114.png?alt=media&amp;token=0c5a2ba1-6b59-4893-b06c-e454ea827ac1" alt=""><figcaption></figcaption></figure>

### Journal API

We now support the option to POST to the Journals endpoint the following letter types:&#x20;

Arrears Letter (AL),\
Notice to Quit Letter (NQ),\
Tenancy Renewal Letter (TR),\
Letter Sent (LE)&#x20;

**Please note**: In the case of AL/NQ/TR the associated type MUST be ‘tenancy’.&#x20;

### Properties API

&#x20;The ‘Text’ field (`urlcaption`) is now both read and write:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FmHi8TNafaTETKit0heja%2FWN30115.png?alt=media&amp;token=0247f5e4-b245-44f3-b6ba-4562c230eb59" alt=""><figcaption><p>Marketing Screen showing the 'Text' field in AgencyCloud </p></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FXlIecVqElvIXmY8CkM65%2FWN30116.png?alt=media&amp;token=ad26b8b9-e72d-47a8-b7fa-5e6e8f78ff8e" alt=""><figcaption><p>Text field</p></figcaption></figure>

## 31/10/22

### Analytics Schema

'Referral' data is now available within the Analytics Schema:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F5CjFOKn69HiJOLvVt7HU%2FWN31101.png?alt=media&amp;token=b2d14408-c90b-4478-824d-e14382b190cc" alt=""><figcaption></figcaption></figure>

### Contacts API&#x20;

It is now possible to update the ‘marketingConsent’ field on an archived contact record:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FCbTuuYc5wUdBQR62E332%2FWN31102.png?alt=media&amp;token=b3bf3cd5-de01-4a8c-b3d0-957f02697690" alt=""><figcaption></figcaption></figure>

**Please note:** Only the Marketing Consent field on an archived record can be updated.&#x20;

### AppMarket 2.0

As you may have already seen, on Wednesday 26th, we launched the latest version of the AppMarket. The updated AppMarket includes and now supports, app name & developer searching, new categories and filter options plus featured apps and app collections:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FqMAfwnmhHAjXLJGiS2K7%2FWN31109.png?alt=media&amp;token=aefc61f2-8829-447a-9f0d-10664d3bea31" alt=""><figcaption><p><a href="https://marketplace.reapit.cloud/">https://marketplace.reapit.cloud/</a></p></figcaption></figure>

Part of the redesign will now allow customers on Rackspace, to view apps that were previously hidden due to the compatibility with AWS. Whilst they still will not be able to install or enable integrations that use data Webhooks, they will now be able to enquire about the app/integration, view the marketing materials and videos.

The new AppMarket now also includes the ability for Developers to add videos to their app listings. ‘Getting Started’ & a ‘Why’ video. For information on how to add a video to your app listing, please [click here](#developer-portal).

###

### Applicants API

Applicant Tenure information is now available in the Applicants ‘Buying’ modal:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FWc2IRTQBGrfZGfaNBh5v%2FWN31103.png?alt=media&amp;token=84280e3e-4414-456c-8a8e-405ec6952956" alt=""><figcaption></figcaption></figure>

### Companies API

We now support filtering on the Companies endpoint by Office Groups.

For more information on office groups, please visit <https://foundations-documentation.reapit.cloud/faqs#what-are-office-groups>

&#x20;

### Tenancies API

‘Allowances’ can now be created and updated:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fearj6r3pCoIy4gpv5Iy8%2FWN31104.png?alt=media&amp;token=dd9ac322-3b3e-4506-a6f5-b3c90380e433" alt=""><figcaption></figcaption></figure>

‘Break Clauses’ can also be created and updated:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FT590WIdjdYze1oc9cfId%2FWN31105.png?alt=media&amp;token=ab15c2de-4cd2-4e68-aee7-928674dfe39b" alt=""><figcaption></figcaption></figure>

And also for ‘Responsibilities’:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F1sb4jwjY7uUFvhKiicjh%2FWN31106.png?alt=media&amp;token=10ae5a77-3b13-40c5-9067-35be40c5d942" alt=""><figcaption></figcaption></figure>

### Metadata API

It is now possible to patch nested objects in the Metadata API

### Properties API

We have exposed the `ValuationDate` & `AgreementExpiry` dates under the property selling model

### Developer Portal

**Videos**

Applistings now support the ability to add video URL's. Under the section 'AppMarket Listing', you'll see 2 new fields:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FGoJPS5gqFfGnE02URpQG%2FWN3110.jpg?alt=media&amp;token=cd5e2ede-d817-4f5d-b17d-af2c62cbf278" alt=""><figcaption></figcaption></figure>

The video's will then be rendered in the AppMarket:&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fe5tBfUHauwnBeoraWhDU%2FWN311010.jpg?alt=media&amp;token=003dcabb-2dbc-4268-b8f9-db77e55963b3" alt=""><figcaption></figcaption></figure>

**Please note:** We recommend strongly that if you do upload videos, to use the online streaming site YouTube.

**App Deletion**

To prevent accidental data loss, we have added an additional layer of protection for apps. On each app, under the section ‘AppMarket Listing’, you will now see the following check box:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fu5pDtxfSX69O4OeaK4U8%2FWN31107.png?alt=media&amp;token=0fccc7e4-f2c3-4aca-ab1b-2c44f35f0aef" alt=""><figcaption></figcaption></figure>

If you should then accidentally select ‘Delete’, you’ll be prompted the following message and will need to disable the additional protection before you can delete the app:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FLyoak9zdVu6HeymTzGdf%2FWN31108.png?alt=media&amp;token=76a46358-fb70-4eef-9f2f-abf5fa35d4d8" alt=""><figcaption></figcaption></figure>

**Please Note:** The app data protection check box is not selected by default so, to ensure your apps and its associated data are protected, please review your app listing.

&#x20;

## 30/09/22

### Properties API

Unmapped attributes:

Property and Applicant attributes/requirements (department data) is completely customisable for each agent and subsequently it can be difficult to understand how to interpret this data as it comes out of the various APIs that expose it.

As the Platform APIs are standardised across all our customers, Department data has also been standardised where possible using a mapping mechanism to map the customisable values from our CRM into standard values in the API.

Any options that do not have a corresponding mapping and are selected on a Property or Applicant entity will be included in the `unmappedAttributes` and `unmappedRequirements` collections in their respective APIs. Additionally, the *Special* attributes column in the CRM is mapped explicitly.

Example payload:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FEJ1XRSA6ZYAtf0RQaMMw%2FWN30091.png?alt=media&amp;token=f0e19140-47f2-4cfa-bb50-6f2c3d1f1be5" alt=""><figcaption><p> </p></figcaption></figure>

Fields:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FeLViY6iJp7hnBxNhfeqO%2FWN30092.png?alt=media&amp;token=12e5c2ea-714e-443e-8ef4-13d2c35c4569" alt=""><figcaption></figcaption></figure>

To view the latest version of the mappings, please visit: <https://foundations-documentation.reapit.cloud/platform-glossary#interpreting-department-data>

&#x20;

The Properties API now displays the Maximum Reception/Bathroom ranges:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FJAwXXwSr00hL2LI6VDNk%2FWN30093.png?alt=media&amp;token=978100f2-0144-42cc-b88c-1d9b973db852" alt=""><figcaption></figcaption></figure>

### Journals API

It is now possible to create a Works Orders journal entry:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FSr7eOSusPdFjkdTGXVQW%2FWN30094.png?alt=media&amp;token=807806b3-14f6-4744-8d53-4f071b3f05e5" alt=""><figcaption></figcaption></figure>

**Note**: TypeID must be set to 'WO' when passing worksOrder

### Companies API

We now support filtering on the Companies endpoint by Negotiator and Office:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F4jBD0pYq6YuLs7c8vSNe%2FWN30095.png?alt=media&amp;token=c00a59e7-2519-4e05-9c89-8835e346232b" alt=""><figcaption></figcaption></figure>

### Applicant API

Applicant ReasonID and SellingPosition now available using POST and PATCH methods:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FoEnUGkCNDxXrlpQJYnMe%2FWN30096.png?alt=media&amp;token=6a546fce-3a5d-4a13-9147-1256646a6265" alt=""><figcaption></figcaption></figure>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F9w1bmNaIgFqqAou6NnNI%2FWN30097.png?alt=media&amp;token=358d966e-9f5b-4316-87e4-9973c2929264" alt=""><figcaption></figcaption></figure>

### Integration Types

New ‘Diary’ desktop integration type now available from version 12.152.3. App’s that have selected ‘Dairy’ as the integration type will be launched from an existing appointment. For more information, please [click here](https://foundations-documentation.reapit.cloud/api/desktop-api#diary).&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FdhpyK0XeYefYnxgbyJGv%2FWN30098.png?alt=media&amp;token=8be3cab1-92b4-4d75-bd40-f11325d27ba5" alt=""><figcaption></figcaption></figure>

## &#x20;30/08/22

### Tenancies API

It is now possible to read deposit and deposit holder information via the tenancies API. This information can also be written back up to a certain status:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F86KD4jOYxZvBsQevOVLd%2FWN3008.png?alt=media&amp;token=57b9dcd5-a240-4e9a-b998-e4567c5ef304" alt=""><figcaption></figcaption></figure>

&#x20;It is now possible to filter tenancy checks by type:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FRyUOBYCdNaPmNXFraGYJ%2FWN30082.png?alt=media&amp;token=9750b194-8c0e-4fb6-8890-2d4c5ea19ba5" alt=""><figcaption></figcaption></figure>

### Properties API

Market Appraisal (valuation) price now available:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FRVc5xEoQd1KOgwExBpq8%2FWN30083.png?alt=media&amp;token=2191e8d6-205b-43a0-8884-7475e370210d" alt=""><figcaption></figcaption></figure>

Pre-Instruction checks can now be managed via /properties/{id}/checks:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F91K2RhyoFasm1TAiMmpo%2FWN30087.jpg?alt=media&amp;token=8e30bc1e-fade-4f9c-8448-87b6ea538516" alt=""><figcaption></figcaption></figure>

### Applicants API

It is now possible to find applicants by phone number (and any other contact detail):

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fh5LeR8DscHzaFvwFcKEk%2FWN30084.png?alt=media&amp;token=7e449b81-64b9-40b9-a9dd-1b3abb43d8d2" alt=""><figcaption></figcaption></figure>

### Webhooks API

Webhook transactions can now be filtered much more granularly to allow you to find transactions more easily (Topic name, Entity ID & Event ID):

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F7hF3ilgeigOcT9BfagGa%2FWN30085.png?alt=media&amp;token=0d5ffe9e-a5b2-4b20-80d1-6b64b75a562c" alt=""><figcaption></figcaption></figure>

### Enquiries API

The validation has been updated to more closely match the contacts API&#x20;

## 29/07/22

### Referrals API - Phase 2

The Referrals API has now been enhanced to support updating (PATCH) and the ability to store metadata:&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FFjyxP9B8FBu0EY6X8uiv%2FWN108.png?alt=media\&token=6c5764be-96c7-4394-8130-3e84ff5ed83f)

### Properties API

It is now possible to see the Id’s of disabled portals set against a property:

![ The ID’s are stored on the configuration endpoint for portalTypes.](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FQl0DZKsK87jsGWQP4u64%2FWN208.png?alt=media\&token=99e7fa53-2f88-434a-a310-80c08787ce23)

&#x20;You can now filter properties by AreaId:&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FQAVN8Kru65BYgK77S0tW%2FWN308.png?alt=media\&token=7c925bb6-a3ef-4302-80e3-32df9db322f1)

Our multi currency support milestone has been completed. It will be most beneficial for UK customers that advertise international properties. For more information, please review our milestone [here](https://github.com/reapit/foundations/milestone/142?closed=1).

### **Enquiries API**

When creating a new enquiry (which is visible on the Internet Registration panel in AgencyCloud) you can now pass price/bedroom requirements for sales and lettings applicant enquiries:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FkpJ4l9hYTH1EyHi0qeJp%2FWN408.png?alt=media\&token=3fa7ce3a-212a-4e7b-88ca-6e817f755661)

### Journal API

We have added support to allow retrieval of ‘tenancy’ journal entries.&#x20;

## 27/06/22

**Rural** property data is now exposed with certain fields writeable under the ‘rural’ section on a property:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FwBxa6d5RSYf0klBKi97w%2F27061.png?alt=media\&token=04762cce-e242-4470-b6c2-9faeb59a39fe)

**Lettings management fees**, type and amount now available under the ‘managementFee’ section:&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FQN8C5BCwnHdgSzJC8K5K%2F27062.png?alt=media\&token=5758be5f-06d0-433c-9c04-f4694e6a7107)

**Number of units** (numberOfUnits) in a development now available:&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FqY19bxKAD3pp82QLmIOP%2F27063.png?alt=media\&token=d7b77637-0ac5-46cd-9e37-7bef828ec14e)

**Minimum tenancy term** (minimumTerm) now available for lettings properties:&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FiRm7UvbdCAIRspUiWKz3%2F27064.png?alt=media\&token=54b627d6-64c0-4c44-b190-91f9a57ca1a4)

‘**smallHolding**’, ‘**estate**’ & ‘**developmentOpportunity**’ property types are now available via the Properties, Departments & Applicants endpoints. Please note, the additional types are only available in some customer's systems. The 'Departments' endpoint should be used to understand the configuration of a specific customer.

**Contact categories** can now be retrieved using the ‘Configuration’ endpoint ‘contactCategories/{id} and can also be set on a ‘Contact’**:** &#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FDZlLVEpyOCZhFbBvAm0l%2F27065.png?alt=media\&token=33dfccd9-9cab-4866-a9ff-8a9252b921a2)

&#x20;**Public brochure URLs** (publicBrochureUrl) are now available in the Properties API under either the ‘Selling’ or ‘Letting’ object:&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FAZhigT9PW0bD7KZuvbX9%2F27066.png?alt=media\&token=d97c2242-16e1-430b-876d-65dfec9c1360)

A **works order note** (worksOrderNote) can now be added at the property level which will cascade down to any works order for that property in Agency Cloud:&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FEvck5pS3IJX07gjpwZq0%2F27067.png?alt=media\&token=2a96cfb3-4a02-4fa4-8f3b-97e4ed105c2f)

**Office status** can now be obtained from the Offices API so you can understand whether an office is open or closed based on the field type ‘active’:&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FOIGMyQ9wv9kmgrR25Ov6%2F27068.png?alt=media\&token=967a4da7-4016-4dc7-8a25-071545cc6bd8)

&#x20;

## 24/05/22

### **Referrals - Phase 1**

Last week, we released the first phase of the ‘Referrals’ endpoint which includes the following:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fsow35JQw9HazOzEFqvij%2FWN8.jpg?alt=media\&token=fe52bd58-2eda-4acd-8e2e-6c668852b193)

The second phase will include the ability to write to the endpoint, metadata & associated webhooks. You can track the phase 2 milestone [here](https://github.com/reapit/foundations/milestone/136)

### **New features**

**Journal Entries**: You can now store a journal entry of Match (MA) against a property or applicant record\
\
**Bedroom Range**: The ‘Max’ bedroom range is now exposed in the Properties API – this is most useful for marketing of property developments.\
\
**Properties**: We have added support for Juliette Balcony (property situation), Studio (property style) and Villa (property type).\
\
**Companies**: Additional contact information is now available for companies. The additional information is available in ‘additionalContactDetails' object:&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FCDwlPqxj0DlvOIaC3OKd%2FWN9.jpg?alt=media\&token=c966508f-53d8-4545-8f64-71f9cd1aa3eb)

**Transactions**: It is now possible to filter transactions by ‘Outstanding’ amount.

### **Developer Portal Release**

The latest release of the Developer Portal (v3.0.5) included the re design of the following pages…\
\
**Settings**: We have updated the UI within the settings section in accordance with our design system and the other pages within the portal. The options available to you when accessing settings will be dependent on your user level:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FBxYeHZ9PrcXtg8GOL0k1%2FWN3.png?alt=media\&token=30ed2022-d169-4157-b1dd-182f25a4ede4)

Admins of an organisation can set the level of users (members) on the ‘[Members](https://developers.reapit.cloud/settings/members)’ page.\
&#x20;\
**Analytics**: We have separated the features and information available to you in specific sections: ‘API Usage’, ‘Costs’ & ‘Installations’.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FSgbx3rkfjocAbms66wBi%2FScreenshot%202022-05-24%20164411.jpg?alt=media\&token=3b7a0934-a680-446a-8a8a-6095c9f1b736)

\
You can use the filters on the left-hand side to set the data results for each page.

### **Design System**

In the latest release of our Design System Figma file, we introduced new button states and a new component. We have also fixed a few bugs and revised/added additional documentation for buttons.\
&#x20;\
New Features

* Disable and hover states for desktop buttons

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FFnWzQKDi6ZkifiZQQ6NB%2FWN4.jpg?alt=media\&token=578c175f-1f2a-4b65-aea1-9565d9fba195)

* Disable state for mobile buttons

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FkMOooSz5OyExrqED6L5Z%2FWN5.jpg?alt=media\&token=db3a65d1-14f8-4b3d-9c7c-c40bf0228d6d)

* New medium size infographic icon (Manage App Listing)

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FdzrpNGDHSOVeBmg5lc9E%2FWN6.jpg?alt=media\&token=b94ab889-5c41-45b1-8e7b-de766cbbf776)

* File Upload component

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fujd6s3m2RIt54nIZaniV%2FWN7.jpg?alt=media\&token=1d11b4ee-36d8-43b1-b0de-8a1b78318f67)

### **Bug Fixes**

* Measurements: misspelling on the red static button; it was 38px, now it’s 40px&#x20;
* Measurements: misspelling on the ‘One Choice Chips’ component - active state, selected chip, padding was 4px and now it’s 3x, margins were 3px and now it’s 4px
* Documentation about button types was added to all components that use them
* Static button with icon has been documented
* Static button width size for mobile has been increased to 120px
* Guidelines for static and dynamic buttons have been revised
* Desktop - Full Options Expansion Panel: button margins and distance between buttons and content have been revised

## 01/04/22

### Trading Standards – Material Information Requirement

We are pleased to confirm, the Properties API has been updated to provide the following information ahead of the Material Information requirement by the end of May 2022. Related information [here](https://www.nationaltradingstandards.uk/news/material-information-for-property-listings-announced/).&#x20;

The following fields are available:

* Council Tax Band (`councilTax`)
* Local Authority (`localAuthorityCompanyId`)
* Ground rent for leasehold properties (`groundRent` & `groundRentComment`)
* Maintenance charges for leasehold properties (`serviceCharge` & `serviceChargeComment`)
* Leasehold length (`tenure.expiry`)

### Webhook Enhancements

Last week, we updated our Webhook functionality to increase throughput and to reduce latency. We have seen a significant improvement already. We have enhanced the way in which we process webhook events. Nothing has changed for you in how you create or manage your webhooks but the background service has been re developed to better increase the rate in which they are emitted.

### Additional fields

Deposit Data (Type & Amount) is now available inside the Lettings object on Properties API under ‘deposit’:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FTLnLEuzyRmkJXbkZOqpE%2FDepositData.png?alt=media\&token=12637976-c784-4cf7-a9f5-b12d6c5f6cc8)

### Additional Filtering

Properties by Negotiator ID(s)

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FmvwTyIz0Q26XcMrFxcVf%2Fnegid.jpg?alt=media\&token=08171a88-66ad-478c-ad30-adc9e9efa03e)

Properties by Country ID:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FMOcWmkUDjMj8C4e5ZSBJ%2FCountryID.jpg?alt=media\&token=77ad7d86-083a-4b2b-8b7b-38bba8022e1b)

### GitHub Username Field

To better help us identify the company you are associated to and help with triaging tickets that are raised via GitHub, you can now save your GitHub username on your ‘[Profile](https://developers.reapit.cloud/settings/profile)’ page in the DeveloperPortal:

&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FcOKAf7NJ67bYnYXPjbmK%2FGithub%20Username.jpg?alt=media\&token=335e2d7a-b5ec-43cf-97f5-198178c015fe)

### Help is moving

The 'Help' page is moving into our main documentation. The 'Help' icon on the main navigation will soon no longer be visible but you can still access help by going to '[Docs](https://foundations-documentation.reapit.cloud/) > [Help](/help)'.&#x20;

## 24/03/22

### New Release

This week, we have released a new version of the Developer Portal, specifically an updated version of the app creation flow and app edit pages.

The new design has been developed to improve the UI (now using Elements V3) and to improve the user experience. We’ve also added a very helpful new feature. Read below to find out more.

### App Creation

To better help you navigate the app creation process, we have included a helpful app creation wizard. The wizard is designed to make creating an app as straightforward as possible by preselecting/populating certain fields based on your use case.

You can select the type of integration from the list below:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FigjGYodQoRKIJFfSeFeQ%2FWizard1.png?alt=media\&token=e4a2bdb5-6fd8-4fc1-942a-1e9ed1bf30bb)

Or if none of the above suit your requirements, simply scroll down and select either a Client-side app or Server-side Integration:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F7Xl92unrKXdwqzNcyxoY%2FWizard%202.png?alt=media\&token=6fe8684b-f534-4e8a-b1be-9558b90a1759)

With every selection, we will present the associated documentation on the right-hand side to help you with the process.

You’ll find helpful links for more information or on certain selections, a short video.

When you have completed the wizard, you’ll be directed to the ‘App Details’ page. This page will contain all the information you need to get started developing right away, such as the Client ID and or Client Secret:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F2Aq40jmMh2uXEjDfhdpt%2FWizard%203.png?alt=media\&token=5c21c909-8a38-4f1b-ab47-16e869a42cca)

The app name will be pre-populated based on your company name. You can change this at any stage.

To edit your app, simply click ‘Edit App’ from the left-hand navigation.

Depending on what type of app you have selected from the wizard, you’ll be presented with various tabs. The first tab for all types is the ‘About Listings’.

### **New Feature**

On the ‘Edit App’ page is where we have introduced a new feature ‘Check Status’.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FDEWnt9sJyx8BNbhNEftg%2FWizard%208.png?alt=media\&token=298d55f7-e58e-408e-a78c-fd0ea59c94cf)

The check status button is a very quick and easy way to see the current status of your app, what information is missing, your AppMarket status and to see if have any changes that require saving.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F6tSoZJDF5kL2AbrDVson%2FWizard%204.png?alt=media\&token=a4056ddc-3d60-4e39-b364-1d1348bd4f6e)

The process for submitting your app for review is the same as before. Simply check the status of your app and once all checks have been completed (see example below):

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FZrFNdCs3ibRS0a65a6Ve%2FWizard%205.png?alt=media\&token=13801644-6d95-4243-ab41-fc7ec65e98c2)

A button on the left-hand side will appear ‘Submit Review’. This will create a revision to our Admin team.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FWtK77l9vCZB5oc9cq4kZ%2FWizard%206.png?alt=media\&token=d2e1ef24-2e42-4104-904a-837a1fb606fa)

&#x20;

Once your app has been approved (please [click here](/listing-your-app) for more information on the reviewal process) the button will change to present the option to ‘Delist’ your app.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fd98R0f7JOqBCmvEDiwOX%2FWizard%207.png?alt=media\&token=ca537a3a-f6b5-42f4-b1dc-81fa5247fb2c)

The additional tabs, as mentioned previously, will depend on your app type but in all cases, you will have an ‘AppMarket Listing’ and a ‘Permissions’ tab.

The ‘AppMarket Listing’ tab captures the app listing content for the AppMarket and will need to be completed before submitting your app. Images, description, contact information etc.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FYHUvszH2cXETRtxWZ3Ji%2FWizard%209.png?alt=media\&token=5e4a1441-9366-462c-be29-2e9c35d72e3d)

The ‘Permissions’ tab will relate to the endpoints and data sets you wish to interact with and the visibility of your app (either public or private).

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FZLHC6M5IF4lVIIXi0fGS%2FWizard%2010.png?alt=media\&token=55f7de82-9529-4a70-94ae-72f46e57cdfc)

For other types of integrations, you will see the tabs for AgencyCloud Integration and Authentication.

We will be continuing to update the Developer Portal in the coming months to further enhance the user experience and features available to you. &#x20;

## 14/03/22

### Works Orders&#x20;

You can now interact and launch with the native works orders screen and pre populate certain search criteria using the newly added AgencyCloud scheme:&#x20;

```
agencycloud://worksorders/{id} 
```

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FbVfdQOs9Nx8RMaP1nsD1%2FWorksOrders.jpg?alt=media\&token=71fd2365-dcfd-45d1-9da7-dc3c75c22527)

For more information on Works Orders, please click [here](https://foundations-documentation.reapit.cloud/api/desktop-api#works-orders)

### Match Output Integration Type

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.

An app with the integration type 'Match Output' will be visible by selecting 'Print' after running a match:&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FgpEoiTnoMqMq59X8JgoQ%2FMatchoutput1.jpg?alt=media\&token=55a0e809-c4ac-4528-806a-3256d7120638)

For more information on Match Output, please click [here](https://foundations-documentation.reapit.cloud/api/desktop-api#match-output)

## 10/03/22

### Property URL

We are now returning (when manually entered) the Property URL, which is accessible from the 'Marketing' screen:&#x20;

![Properties Endpoint](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FbnolIDXysnORlueDWqtS%2Fimage.png?alt=media\&token=d13d5c51-7ed9-47cc-a35a-ffc8e8de65bb)

![Marketing Screen in AgencyCloud](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FU2myVQHNQMyaZBarSnTO%2FPropertyURL.jpg?alt=media\&token=24121ea6-24c7-44c1-b531-d0338ca2ba49)

**Please note:** The URL will only be returned when it has been explicitly set. Default URLs' will not be available.&#x20;

## 23/02/22

### Property Featured Image

The featured property image (featuredImageUrl) is now being returned in the properties object, without the need to embed or make an additional call to the property images endpoint. This will be mostly beneficial for website integrations for property results.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fpq8Pe9cmbB1j3sc5Cws0%2FFeaturedURL.jpg?alt=media\&token=66783554-3eee-4b91-930c-f6daaaba3056)

### Property Manager Information

We are now returning the Property Manager ID (propertyManagerId) within the lettings object on a property.&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FJ865AcATmDmuzPc2MuKg%2FPropertyMan.jpg?alt=media\&token=3ee9fcc0-d25c-40f1-8ef1-26b0046577dd)

### Additional Extras support for Landlords and Works Orders

We have now added the ability for users to request additional extras fields for Works Orders and Landlords.&#x20;

&#x20;Also, you can now filter by ‘QuoteAccepted’ on Works Orders.

### Code generation

We have now updated our code generation mechanism to now support office specific referencing.

## 10/12/21

We have recently updated our [Development Request documentation](https://foundations-documentation.reapit.cloud/dev-requests) to now include a [FAQ’s](https://github.com/reapit/foundations/milestone/105) section.\
\
Part of the update to the documentation includes a detailed description on each label, column and board.\
\
Please take the time to review the updated documentation and ensure you understand how feature requests and bugs are triaged via the Platform.\
\
In addition to the updated documentation, we will shortly be implementing a ‘GitBot’. The GitBot is designed to auto reply to specific issues raised, when issues are moved to certain columns, assigned specific project boards or certain labels added.\
\
Essentially, an automated comment to will be added to the issue which will help explain the reason a specific label was added, why it was moved to a certain column and the time frame in which we expect the work to be completed by. The automated email will be sent the person that raised the issue or anyone that has subscribed.\
\
If you would like to receive a notification (email) to an issue you are following but have not raised, please make sure you are subscribed, using the ‘Subscribe’ option from the right-hand navigation.\
\
Please do not contact our service desk, customer success managers or any other channels within Reapit with regard to the status or timeline of an issue. Please first refer to the [documentation](https://foundations-documentation.reapit.cloud/dev-requests) and communicate with developers directly in GitHub.

## 13/09/21

### Troubleshooting

We have introduced a new section in our documentation ‘[Troubleshooting](/troubleshooting)’.

The documentation is intended to provide guidance to our Developers when building apps and integrations through the Developer Portal.

Currently, it offers support on the following topics:

[Accessing Customer Data](/troubleshooting/accessing-customer-data)\
[Authentication Issues](/troubleshooting/authentication-issues)\
[Installation](broken://pages/-MfHjv7yrWkNatjMClJN)\
[REST API](/troubleshooting/platform-api)\
[Reapit Connect](/troubleshooting/reapit-connect)

We will continue to add and update this section but don’t forget, we also have a dedicated page for FAQ's, which can be found [here](/faqs).

Remember, if you are having an issue not covered in the documentation or you have discovered a bug, please raise an issue on our public board by clicking [here](https://github.com/reapit/foundations/issues/new/choose).

### **Notification Email**

The email address you entered when registering for the Developer Portal, is used by default to receive email notifications,. For example, when your app is installed from the AppMarket, you will receive an email with the details (see more information [here](https://foundations-documentation.reapit.cloud/faqs#installation))

As you cannot change the email address that registered your organisation, we have now provided the ability to supply an alternative ‘Notifications Email’.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MjYcr4Q9LksyDhZ79Hs%2F-MjYdgZRuEzMXZmXRlnX%2Fimage.png?alt=media\&token=74a44ad1-f0bc-4430-9075-f78db446231a)

If you want to setup an alternative email address, simply go to ‘[Organisation](https://developers.reapit.cloud/settings/organisation)’ page.&#x20;

**Please note:** Only an Admin will have the correct permissions to update this information.

### **Certificates**

We are pleased to announce have added new endpoints to the Properties endpoint to now allow for reading and writing of ‘Certificates’.&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MjYcr4Q9LksyDhZ79Hs%2F-MjYe2JwNPkebZ9SAaSd%2Fimage.png?alt=media\&token=0bf74446-8ada-463f-9497-3fc6966991c1)

In conjunction with the new entities, we have also added to our Configuration endpoint, the ability to surface CertificateTypes.

## 25/06/2021

### **Webhooks Transaction Logs**

We have now included a ‘Transactions Logs’ section on the ‘Webhooks’ page, to allow you to filter your transactional Webhook history by date and app. \
\
To view your webhook transaction logs, simply navigate to the ‘Webhooks’ page inside of the Developer Portal, select a date range (will default to the last 7 days) and select an app:&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-Mcx4Ns5Bx7lhflsLAYl%2F-McxGP2Mo-XuRPSdbu0w%2FTranslogs.png?alt=media\&token=bd640967-b5c1-44df-b8ca-d9c24e33b935)

From each log item, you will be able to see the URL, the selected topic, status and the option to ‘Download’.

Selecting ‘Download’ will save a copy of the specific payload as a JSON file.<br>

### **New Webhook Topics**

We have added the following new Webhook topics:\
\
appointments.cancelled\
appointments.confirmed\
contacts.optedout\
enquiries.accepted\
enquiries.rejected\
offers.rejected\
offers.withdrawn\
offers.accepted\
properties.selling.askingpricechanged\
properties.selling.completed\
properties.selling.exchanged\
properties.selling.withdrawn\
properties.selling.instructed\
properties.selling.lostinstruction\
properties.selling.underoffer\
worksorders.cancelled\
worksorders.complete\
worksorders.raised\
&#x20;\
If you wish to setup subscriptions to any of the new the topics listed above, you will need to have selected the associated scopes.\
\
For more information on the required scopes, please visit the associated documentation [here](https://foundations-documentation.reapit.cloud/api/webhooks#available-topics).<br>

### **New REST Hooks Endpoint**

We have introduced a new REST Hooks Endpoint. This functionality allows you to programmatically set up webhook notifications for your application rather than needing to do this manually using the ‘Webhooks’ page in the developer portal which can help you automate onboarding of customers.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-Mcx4Ns5Bx7lhflsLAYl%2F-McxGtI-H3yJdqbHz-zd%2FResthooks.png?alt=media\&token=b80a5484-7676-4ea6-974c-8d0dc1c08f8c)

### **Updated Terms and Conditions**

We continue to develop new features and products on the Foundations Platform and have updated our Terms and Conditions to reflect these changes.\
\
From 25th June, when you next login to the Developer Portal, you will be presented with the latest updated terms and will need to accept before continuing to use the Developer Portal.\
\
Our current and revised terms can be accessed through the Developer Portal documentation under ‘[**Developer Terms and Conditions**](https://foundations-documentation.reapit.cloud/developer-terms-and-conditions)’.

## 04/05/2021

### New Desktop Integration Types

Our desktop integration types have been extended to now include the following communication types included in AgencyCloud from version 12.130.1 :

* Outbound – Email
* Outbound – Landline
* Outbound – Mobile

On each communication type, the Desktop API will provide a 'cntCode' and relevant communication information, either email, landline number or mobile number.

App that’s have any of the above desktop integration types will be visible in AgencyCloud when right clicking on the relevant icon, please see example below:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MZrrfLQfwA9q07w0SI0%2F-MZrxYXd1eZelqm3g8Ju%2Fimage.png?alt=media\&token=d78b34b2-4c13-478c-849d-1b540e602978)

The Developer Edition of AgencyCloud has automatically been updated to include the new communication types.&#x20;

## 19/04/2021

### Setting Predefined Property Brochure Details

It is now possible to set or clear default property brochures when updating existing properties, using the PATCH method on /properties/{id}

Updating the ‘brochureId’ field on the ‘Selling’ and/or ‘Lettings’ models with a document ID, will set a PDF as the predefined property details. Please see an example in the Property Details screen from within AgencyCloud (Desktop CRM) below:![](file:///C:/Users/HPHILL~1/AppData/Local/Temp/msohtmlclip1/01/clip_image004.png)

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MYeR5qupqAd11dYQGk1%2F-MYeRS4IXkdwvQDH6HH-%2Fimage.png?alt=media\&token=584534bc-4eeb-4ba2-a2bd-cac88a0ea0d9)

### Inactive Webhooks

To ensure data viability and security, we have made a change to the way 'Sandbox only' Webhooks are handled.

Webhooks that have been setup specifically for Sandbox testing (SBOX) and have been unmodified for 14 days, will automatically be deactivated.

Should you wish to continue using Webhooks for Sandbox testing, you can reactivate it again by selecting the check box ‘Active’ when editing. ![](file:///C:/Users/HPHILL~1/AppData/Local/Temp/msohtmlclip1/01/clip_image007.png)

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MYeR5qupqAd11dYQGk1%2F-MYeRXNwBgFdOXoCUrmr%2Fimage.png?alt=media\&token=107c1765-92ea-4b22-855d-b88b9148d7c3)

### Large File Support

We have added additional support for uploading files over 6MB (Up to 30MB) to the Property Images and Documents endpoints via the use of pre-signed URL's

## 01/04/2021

### &#xD;Developer Portal and AppMarket Refresh

We are excited to announce today, the Developer Portal, Reapit AppMarket and AppMarket Apps UI have been updated in conjunction with the release of our Elements UI library version 2. The functionality of all apps remain the same but with UI enhancements to your user experience.

The visual changes you see are the first step towards a universal design language we have been working over the first part of the year. In the coming months you will see continued incremental updates as pages and flows are re-worked for better UI consistency, polish and UX. In keeping with our open source commitment, in the coming months we plan to make available publicly the design language, sample layouts and designs so that Reapit Developers can leverage our design resource to build better user experience into their own AppMarket apps.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MXaBHDsUSkAPr-EGwAN%2F-MXaClFfL1TJFDbJl-AE%2Fimage.png?alt=media\&token=eab0aac4-6674-47d2-ba4e-1a2a91bcff79)

Because we ask that all AppMarket Apps use our UI for visual consistency, we wanted to give the style guide a lift to ensure it best showcases of our development partner's work. This is the core of the Elements v2 release - it is a subtle evolution of the library, including a new font, typography, colour pallet, form inputs, notifications, dialogue boxes and much more.

Care has been taken to avoid breaking changes both to React Components and CSS Classes so that upgrading for all developers should be trivial and painless. We will also offer ongoing long term support in terms of security and bug fixes for the v2.x.x release. You can see the updates to the React Storybook here: <https://elements.reapit.cloud/?path=/docs/>

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MXaBHDsUSkAPr-EGwAN%2F-MXaD6WtCEyEH7FTXpqi%2Fimage.png?alt=media\&token=00bee685-d21a-426b-b853-d64095933db3)

This however is just the start and we are now looking ahead to version 3 of Elements. Version 3 will be a ground up re-write of the library, both implementing fully the new design language and responding to both internal and external developer feedback. The version will focus on three core areas of improvement:

* Visual UI refinement and consistency, fewer components and clearer design patterns to implement.
* Better documentation for both React and non-React users, including suggested use cases and composed components for off-the-shelf UI / UX flows.
* Much smaller library with very little required JavaScript and very few dependencies. Elements will be about the visual presentation with developers free to make their own choices as to how to implement behaviours. This will mean a far better developer experience, especially for non-React users and a much more flexible, less opinionated library.

For more information about the latest release and news about Elements 3.0 (coming soon) please [click here](/app-development/elements#elements-v-3-x-x-coming-soon).

## 09/03/2021

### Configurable Webhook Behaviour&#x20;

A new configuration option is now available when editing existing/creating new webhooks.&#x20;

By default, webhooks will not be emitted when only the entity's eTag and modified timestamp has changed.&#x20;

If you would prefer to receive notifications in this situation, please use the '**Ignore notifications where only the eTag has been modified'** toggle option when configuring your webhook. See example below:&#x20;

![Adding a New Webhook](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MVLd93u3z9aGsICczb5%2F-MVM4IxUEuqZ8TEcJOGC%2Fimage.png?alt=media\&token=3206d28f-3e22-4942-99ab-c0cf6012f774)

Existing webhooks will remain as they are and you can edit your webhooks at any stage from the '[Webhooks](https://developers.reapit.cloud/webhooks)' page in the Developers Portal

### New Developer Requests Documentation

To '[Request a Feature'](https://github.com/reapit/foundations/issues/new?assignees=\&labels=feature-request%2C+needs-triage\&template=feature_request.md\&title=) or to '[Report a Bug](https://github.com/reapit/foundations/issues/new?assignees=\&labels=bug%2C+needs-triage\&template=bug_report.md\&title=)' you can visit the '[Help](https://developers.reapit.cloud/help)' page in the Developers Portal. To help with understanding the process for each new issue raised, we have added a new section in our documentation '[Developer Requests](broken://pages/-MTzCNhRuWxZfj5frdpW)'.&#x20;

The new documentation will outline our processes, from what happens after submitting an issue to how your ticket will get triaged and categorised. Depending on the nature of the request or bug, it will determine which project board it may get assigned to. As our boards are public you will always be able to track the progress of any issue or request raised.&#x20;

![Help section in the Developers Portal](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MVMZEH95q6g4n9M85Qm%2F-MVMa2CJ5ezQJuZjuVsX%2Fimage.png?alt=media\&token=9cc8a69e-86e4-47ae-9ae4-6ca49aa986b0)

### Virtual Viewing check box

With the very significant increase in the number of listings carrying virtual viewings, we have introduced an additional 'Virtual' check box on appointments inside of AgencyCloud:&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MVMgIWE1aZf-bcvvMes%2F-MVMgKsTvZoGAbmaAjfi%2Fimage.png?alt=media\&token=06dd3457-bdaf-41f4-9c45-5dac1a9776f4)

The virtual field is also now available in our 'Appointments' API in the Platform:&#x20;

```
 "accompanied": true,
      "virtual": false,
      "negotiatorConfirmed": true,
      "attendeeConfirmed": true,
      "propertyConfirmed": true,
      "metadata": {
        "CustomField1": "CustomValue1",
        "CustomField2": true
```

The latest version of the Developer Edition of AgencyCloud will include the new checkbox

## 25/02/21

With all enterprise customers now having access to the AppMarket, we wanted to use today’s What’s New update to highlight the features available to you on the ‘[Analytics](https://developers.reapit.cloud/analytics/)’ page in the Developers Portal.

The Analytics page provides useful information on the following:

### Current Installations

A table to display the individual installations per client with a total number of installations per app

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MUO3wu2HLZT3W3Vq4aR%2F-MUO4EmiDar93Awe6XGH%2Fimage.png?alt=media\&token=6787fe9e-66a3-4a57-b2f1-f6f6e85911d5)

### Hits Per Day

A graph showing the number of endpoints that are hit per day. You can also hover over a specific point for more information :

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MUO3wu2HLZT3W3Vq4aR%2F-MUO4GtMgv2S6MN4Gq3M%2Fimage.png?alt=media\&token=9346d8e0-8d85-4e54-a85c-4577f81867e7)

### Installation Details

A full history of any installations or uninstallations that have occurred for your apps:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MUO3wu2HLZT3W3Vq4aR%2F-MUO4JOY_ZsnCZGIxWB1%2Fimage.png?alt=media\&token=adc4219c-8a48-42a6-9538-4352ad19a3e8)

### Transaction History

For a more granular level of information, you can download a month by month CSV of your transactions:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MUO3wu2HLZT3W3Vq4aR%2F-MUO4LF00i20dfOUS5_U%2Fimage.png?alt=media\&token=55a825a1-8bf0-4d7d-8eed-6ad63ffbc9d7)

### Services Chart

Any subscriptions or services you have subscribed to will be shown on the services chart and referenced by colour. Subscriptions/services may include, App Listings/Developer Edition of AgencyCloud/ Developer Registration etc:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MUO3wu2HLZT3W3Vq4aR%2F-MUO4N2lwiLvQnL6jisI%2Fimage.png?alt=media\&token=5aba57e8-ee41-4e9f-a7f0-7b093b7e2ce0)

### Cost & Usage

You can use the ‘[Cost Explorer: Cost & Usage](https://developers.reapit.cloud/analytics/costexplorer)’ section to view your current monthly subscription charges and navigate through previous months if required. We also provide a ‘Download’ option which will download this information in a CSV.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MUO3wu2HLZT3W3Vq4aR%2F-MUO4QUIjuiE1_njoCtw%2Fimage.png?alt=media\&token=14f3beaa-7717-4dc2-95f4-224fd8e948b2)

### New section in the documentation

With an increase in apps now being submitted for approval, we have added a new section in our documentation ‘[Listing an App](/listing-your-app)’.

It covers, in detail, how to prepare your app before listing, what information is required, our testing processes and what happens when your app has been approved. &#x20;

## 03/12/10

### &#xD;New fields now available

We have recently updated the Developers Portal to allow for 4 new fields on your App listing which can be managed when clicking on 'Edit Details'.&#x20;

* Terms and Conditions
* Privacy Policy
* Pricing Info
* This Application is Free

For your App/Integrations to be submitted for approval and listed in the AppMarket, you will need to provide a secure URL (https\://) for each field.

![New fields on the 'Edit Details' app form](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MNbjBWVbMsLKlEPIxXq%2F-MNbk2C4AewJ3F7gJNFj%2Fimage.png?alt=media\&token=0fcff7c9-30a2-40df-aa6c-d5660c1d7eb6)

However, if your app is free of charge and occurs no cost to the end user, please use the ‘This Application is Free’ check box. If selected, you will not be required to enter your Pricing Information.&#x20;

The information you provide in each field is then surfaced on your app listing in the AppMarket for agents to view:

![Example of the new Developer Links section](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MNbjBWVbMsLKlEPIxXq%2F-MNbnPVMnvzAXVOg7ewM%2Fimage.png?alt=media\&token=0d4826bf-f863-4729-a60d-4ecafe77d555)

If your app is ‘Free’, the pricing link will not be present on the app listing. A 'FREE' tag will be displayed when browsing the AppMarket:&#x20;

!['Free' App in the AppMarket](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MNbjBWVbMsLKlEPIxXq%2F-MNbnyFZpKTGdFlMhbpK%2Fimage.png?alt=media\&token=05b69590-1537-4992-af9f-9138883058a4)

The URL you provide for your ‘Pricing Information’ will also be presented to an agent on the install confirmation modal.

If you have provided a URL we will display the following new section under 'Pricing Information':

![Example 'Install' confirmation modal displaying a link to pricing](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MNbjBWVbMsLKlEPIxXq%2F-MNboDXKlAeocVVsh5ZR%2Fimage.png?alt=media\&token=465ba4ee-dd7d-4093-b89f-863e9b0056aa)

### AgencyCloud Apps now launchable after installation

The latest release also includes a new ‘Launch App’ button after installation.

This will allow the agent to have the ability to immediately launch your App. This option is only available for AgencyCloud Apps (not available for ‘Integrations’)

![New 'Launch App' button](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MNbjBWVbMsLKlEPIxXq%2F-MNbocPd1YxXBIVgdUBs%2Fimage.png?alt=media\&token=02d32f98-92be-40a2-a7f3-b6a60dc00cff)

As installations are only available to 'Admins', this is a great way to accelerate the onboarding process as it can be completed immediately.&#x20;

### Terminology Update

‘Direct API’ has now been updated to ‘Integration’. This has been updated in the Marketplace, Developers Portal and all associated documentation.

## 26/10/2020

### &#xD;**Seamless integration between the Developer Portal & the Reapit AppMarket**

Access between the AppMarket & the Developer Portal with one click! When you next log into the Developer Portal, you will see a new ‘Marketplace’ icon appear on the navigation. Clicking on the icon will take you to the Reapit AppMarket and automatically log you in using your Developer credentials.

To go back to the Developer Portal, simply click on the ‘Developers’ icon in the nav bar. The introduction of this flow will save time when testing and viewing your integration.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MKeoJKQ1_OoqtBA8W8O%2F-MKeoQYwzVl-b8gJks1h%2FMPWN.jpg?alt=media\&token=532c52e9-d781-41d2-a197-2707a0878044)

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MKeoJKQ1_OoqtBA8W8O%2F-MKeoV4khHu_mel1TC2g%2FDevWN.jpg?alt=media\&token=850a7838-ba59-4d1c-8a2b-acf44788df72)

### &#xD;**Full AppMarket View**

Included in the new access flow, you will now see a full list of live and available apps, in addition to your own applications that are still in development. Previously, with your Developer account you could only see your own apps.

Apps that belong to your organisation and that are ‘In Development’ (not listed) will be clearly be shown with an ‘In Development’ banner, see example below:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MKen2giPN7G-Xt2CR9M%2F-MKenUwT5mA4MZgiWhlb%2Fimage.png?alt=media\&token=c2f08e44-670a-49b3-b3bf-595d99d7365b)

The ‘In Development’ banner will be visible on the ‘Browse’ apps page, ‘Installed’ & ‘Managed’:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MKeoJKQ1_OoqtBA8W8O%2F-MKeotkyeSnSHNpHXriv%2FEPIndev.png?alt=media\&token=b5829f0c-aff5-488e-8a0b-2ad0f1807298)

### &#xD; **Third Party Installations**

App installation remains the same and you still will only have the option to install apps that belong to your organisation. You can of course view apps that belong to third parties but the option to install will not be present. &#x20;

### **Desktop API support for Emails & Websites**

We are now supporting default mail client and browser loading for emails and external websites. If your AppMarket application presents an link to an email, you will need to update the mailto link to include the new AgencyCloud scheme ‘agencycloud://process/email?’

This will allow you to launch the users default email client and send to an address.  An example would be:

```
agencycloud://process/email?address=help@reapit.com
```

This will create a new email in the user’s 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.

Similar to the email link, using the scheme ‘agencycloud://process/webpage’ for a website page URL, will allow you to launch a webpage in the local default browser.  An example would be:

```
agencycloud://process/webpage?url=https://www.reapit.com
```

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.

For more information on the ‘Process’ scheme using the Desktop API, please click [here](https://foundations-documentation.reapit.cloud/api/desktop-api#process)

## 10/10/2020

It has been just over a month since we went into full production for the Foundations Developer Portal and since we officially launched the Reapit AppMarket.

We currently have the following apps live and available for agents that have access to the AppMarket to install.

Access to the AppMarket is dependent on the migration from our Rackspace environment to our AWS Infrastructure. The Migrations Team are still working hard on finalising the list of agents that will be part of Tranche 1. Once this has been confirmed we will share this information with our App Partners.&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MJX5NeRPzOCO1e6XyGV%2F-MJX5TZxI8lOffrIgbRx%2Fimage.png?alt=media\&token=b9797440-612f-418d-8f1c-ec8d85a73375)

In addition to the apps that are publicly available, we also have several apps and integrations that are currently going through their final testing phase, most of which you will be able to see and follow on our coming soon section.&#x20;

The coming soon section is visible on the AppMarket and provides agents the ability to click on any developer or company they are interested in to send an enquiry email.&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MJX5NeRPzOCO1e6XyGV%2F-MJX6LcRPi54D6lRDNH2%2FComingSoon1.jpg?alt=media\&token=b6f1f5d9-2885-4a20-ba1b-5c9cdb4cd442)

### Additional Testing

We have recently created a internal demo environment for us to be able help test and view your integrations using our office with the Customer ID ‘RES’. This new environment not only gives us the opportunity to see your integration or app in action, but it also allows you to further understand how the user flow is handled/presented outside of the sandbox installation.&#x20;

If you wish to take part or setup a demo, you will need to list your app (tick the ‘is listed’ box on the app listing) and set 'Private App' to ‘Yes’ using Customer ID ‘RES’.

After submitting your revision, we will contact you directly to talk through the installation and what to expect.

### Fixes and Changes

Over the last few weeks we have been working closely with our developers to see if we can look to improve or enhance the functionality on the Developers Portal, please see below what we’ve been working on.

### Organisation & Billing

When you are ready to list your app, you will first need to complete your Organisation & Billing information. The Admin of your organisation will have access to this information from the ‘Settings’ page.

To complete your Organisation information, you will need to click on ‘Settings’ and select ‘Organisation’\
\
&#x20;You will then be required to fill in the following information:

* Company Name
* Telephone Number
* Website Address
* VAT/Company Reg and or National Insurance Number
* About Us – The section will be displayed on any app listing in the AppMarket in addition to information about the app.&#x20;
* Company Address

Once completed, please then switch to the 'Billing' tab.

If you have an existing relationship with Reapit, you may already have a Reapit Reference. If so, simply enter your reference and submit. You can find your reference on any previous accounting correspondence.&#x20;

We will then verify the reference and company information with our Accounts Department. This is normally completed the same day.

You will receive an email once your account has been set to ‘Confirmed’.

If you do not have a Reapit Reference, please then complete a Direct Debit mandate. It is an online form that will open in another tab. For those of you that have cookies disabled by default, and we know most developers do, you will need to enable them to complete the form. It’s an Adobe requirement, you can of course, disable as soon as you’ve signed the form.

Again, our Accounts Department will setup your account and you’ll receive an email with your new Reapit Reference. No need to do anything with the reference,  as we will add this on your account automatically. Once received, you’ll be able to list your app or make any additional subscriptions.

### Subscription fees suspended until 31st March 2021

Hopefully, you should have received an email from our Marketing team last week, which included the announcement of the following subscription fees suspended until March next year:

* Annual Developer Registration
* Developer Edition
* App Listings
* Reapit Connect

The idea and goal behind the suspension is that it should provide you a head start in the development of your app whilst the AppMarket and it’s users continue to grow.

In addition to this and quite exciting for us, Matt Goddard will now be leading our Reapit Partnership program. As the email quite rightly mentions, his knowledge and experience in the business will be an incredibly asset to you whilst you develop your integrations. Of course, our developers will still be available through Live Chat and I’ll be here to help if needed. Matt will be making contact with you in the coming weeks but if you have any questions, you can contact him [here](mailto:mgoddard@reapit.com).

### User Role Information

As you may be aware, only Reapit Admins have the ability to install or uninstall apps from the AppMarket. The Admins of an organisation are set by the individual office and are made aware of who has been assigned to the which role when they are migrated over to the new AWS infrastructure.  However, to make it easier for you when speaking with Agents and for the users, we have introduced a ‘Role’ section within the AppMarket

.

When on the ‘Settings’ page – accessed by clicking on the company profile or group icon, will see a new field ‘Role’:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MJQfHIgUin6ZfGqz6JO%2F-MJQffWFqZ4xYX30Ibc5%2Fimage.png?alt=media\&token=97c1304a-a41c-465c-aae4-4e6e7355c00d)

Those with a ‘Role’ set to ‘Admin’ or ‘Administrator’ will have the ability to install or uninstall apps.

Other changes we’ve been focusing on and something that will be coming soon.&#x20;

## 28/08/20

### What’s New with the Developers Portal?

Well, quite a lot actually! We are now in full production, which is a huge milestone for all of us. It does also mean with the new production environment, we have been able introduce quite a few new features.

### **Organisations**

With the production environment in full effect, we now have the concept of organisations. Previously, if you were building or testing in the developers portal for the same company, you would have needed to share an account or setup additional users under a separate account. Now, you can setup your own organisation and invite members to join you.

This means you can collaboratively build and test your integrations under one account. It’s worth mentioning that only an ‘Admin’ will have the ability to view your organisation information.

### **Invite New Members**

To invite members to join your organisation, simply click on the ‘Invite New Member’ button. The recipient will receive your invitation via email and will have the option to reject or accept. You can track the status of any members in the ‘Members’ table on the organisations tab:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MFf2D0OLYpSdhahlpp9%2F-MFf2n-1JmlNzBfsoDH6%2Fimage.png?alt=media\&token=c623f025-15b5-4071-8d56-4ac46ba14a37)

Within the members section you will also have the ability to disable members and to set other members as ‘Admins’.

### **About your Organisation**

The ‘About’ field is a text box provided for you to give a bit of information about your company. This will then be automatically included on your app listings and will be visible to users viewing your app in the AppMarket:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MFf2D0OLYpSdhahlpp9%2F-MFf3-ZXQta9kF5GgXKN%2Fimage.png?alt=media\&token=11bbe555-c1b1-472d-af27-26b9938b7501)

### **Account Information – Billing**

Admins will also have access to setup and manage the account information for their organisation.

Account information will be required before an app can be listed in the AppMarket or before any subscriptions can commence. &#x20;

If you are an existing customer of Reapit and already have an provided your account information, you can simply add your Reapit Reference (you will still need to submit some additional account information such as a contact name, email address etc). We will then send your information to our accounts department to be verified.

Once verified, your account status will be set to 'Confirmed' and you can continue with any subscriptions.

If you do have a Reapit Reference, you will be asked to complete an online Direct Debit mandate. Again, your information will be sent to our accounts department to be setup and once complete, you account status will be set to ‘Confirmed’ and you will automatically be provided with a unique Reapit Reference which we will add the billing page for you.&#x20;

All subscriptions such as the annual App Listing fee, annual Developer registration & API Consumption Costs will then be added to your monthly Direct Debit. A break down of any subscription costs can be found on the ‘Cost Explorer’.

### **Description Field**

We have now increased the character limit for the ‘Description’ field on your app listings. This will provide more room for additional formatting. The character limit has been set to 1,500. Remember, as the description field is using HTML, some special characters will count against the total, so we still advise on keeping the content as direct and concise as possible.

## 10/08/20

### Reapit Foundations App Developer Experience

Over the Reapit Foundations public beta period, we have been working to improve the experience for AppMarket App Developers. Today we are announcing some significant updates to our front end tooling for web developers.

#### **New Create React App template**

Firstly we have released a new Create React App template to replace the scaffolder we demoed at the November launch. As before the template represents the quickest way to get started building AppMarket Apps, now with the added benefit of long term support, familiar CLI and stability from the React Scripts package.

#### Reapit Connect OAuth enhancements

We have also given a lot of attention to making the Reapit Connect OAuth flow as smooth and simple as possible. This has taken the form of a new, lightweight NPM Package, Connect Session. The module handles all OAuth re-directs, session caching and refreshing. There is a browser version that works with any front end, a Node version for server-side apps and a convenient Hook for React users. We have also integrated Connect Session into an embeddable “Sign in With Reapit”, button that is served from a CDN and returns a Reapit Connect Session without the need for any package installation or tooling.

#### Stable v1 Elements UI library

Finally, we have released a stable v1 of the Elements UI library. This will guarantee long term support and a stable API for our React Components and style guide package. We haven’t stopped there though, Elements v2 is coming later this year with a much better experience for non-React users, simpler API, improved documentation and smaller bundle sizes.

For full details visit the new App Development section of our documentation [here](https://developers.reapit.cloud/api-docs/app-development).

## 27/07/20

### &#xD;New Webhooks Available

From today, you will now be able to subscribe to 2 new Webhooks. ‘Application Install’ and ‘Application Uninstall’.

Each Webhook will trigger a notification when your app is installed or uninstalled and the payload will include the following information:&#x20;

Customer ID (ID of Estate Agent)\
Customer Name (Name of Estate Agent)\
Customer Address (Address of Estate Agent)

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MDMAzUsLvdPu7lnUxM0%2F-MDMBI_hfpziM2tE5Vt5%2Fimage.png?alt=media\&token=150152be-40c6-43de-9525-d3085f7f4081)

Setting up a Webhook is simple and easy to do. For more information on Webhooks please visit the documentation [here](https://foundations-documentation.reapit.cloud/api/webhooks)

### Testing your app inside of AgencyCloud Developer Edition

Following the recent successful launch of the Developer Edition of AgencyCloud, we have been gathering feedback on what we can do to help you further test your integration within our Desktop Software.

&#x20;For the last couple of weeks, our Desktop Team have been working hard behind the scenes and we are pleased to announce a brand-new feature, ‘Remote Debugging’.

![Remote Debugging](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MDMAzUsLvdPu7lnUxM0%2F-MDMBOQC93Rnwc0YivC7%2Fimage.png?alt=media\&token=f3855eba-e181-476e-9797-f5f305d70855)

With the remote debugger you can inspect, in real time, Chromium Developer Tools. You will notice the button appear on your app and simply clicking this button will launch a separate window which hosts the developer tools.

For more information on the Desktop API, please click [here](https://foundations-documentation.reapit.cloud/api/desktop-api#debugging-your-app)

## 23/07/20

### New AgencyCloud Integration types

The list of available AgencyCloud Integration types has been updated and now include the following additional options:

* Landlord
* Contact
* Company
* Tenancy
* Offer
* Sales Progression
* Chain Management

You can select the type of integration your app requires on the ‘AgencyCloud Integration’ section when you edit your app listing.

![Agency Cloud Integration Section](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MCxOoT-_uhJxEyEw8Dg%2F-MCxPQwH7tz0V4OJa1s9%2Fimage.png?alt=media\&token=fd085418-76fc-4c72-9809-f3bef7b17767)

The list will continue to grow as we understand more about what our developers are building and how they wish to integrate within Agency Cloud.

For more information on Integration Types, please click [here](https://foundations-documentation.reapit.cloud/api/desktop-api#desktop-types).

## 06/07/20

### AgencyCloud Developer Edition

The highly anticipated Developer Edition of the Reapit AgencyCloud CRM is now available to download. This is an incredible milestone that we have been working very hard to deliver and is now available to our developers free of charge during the Beta Phase.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MBcqCeoGtQ6cZ9xS3P7%2F-MBcrCdP6Ot9j411jWIS%2Fimage.png?alt=media\&token=ae6eae30-bc99-4cfe-b89b-182add61f349)

You will have the ability to test your app and interact with sandbox data using the CRM interface. Seeing in real time how customers will use and view your app inside the desktop application.

For more information, please visit the ‘[Desktop](https://marketplace.reapit.cloud/developer/desktop)’ page within the Developers Portal.

### New App Registration

The latest release has redesigned the way you submit an app. It is now easier to get building & testing through Foundations.

When you submit an app through the Developers Portal, you will be presented with a step-by-step wizard and will only need to provide an App Name, select/provide the authentication method & permissions (scopes). Once completed you will be presented the relevant access tokens/ID's to work with our APIs. &#x20;

![Create New App Wizard](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MBcqCeoGtQ6cZ9xS3P7%2F-MBcqtfFkGt-7YF_4Lfj%2Fimage.png?alt=media\&token=ab878407-cc13-450c-9df0-054c17e18690)

There is no requirement at this stage to add an icon/images/description etc until you are ready to list your app in the AppMarket.

When your app is ready to be listed, simple tick the ‘Is Listed’ box on the ‘Edit Details’ page. This will then let you know what information is needed to ensure your listing is meets the requirements to be available in the AppMarket. You can find more information on providing your app listing content, [here](https://foundations-documentation.reapit.cloud/developer-portal#3-register-an-app).&#x20;

For more information on submitting an app, please click [here. ](https://foundations-documentation.reapit.cloud/developer-portal#3-register-an-app)

## 29/06/20

### &#xD;App Revisions

We have changed how we handle app revisions. Previously, any revision (edit) would need to be approved by our Admin team. This understandably meant a slight delay and prevented any further revisions as your app was in a ‘Pending Revision’ state.

Thanks to the recent update in the Developers Portal, general revisions no longer require Admin approval, meaning no more delays.

The only time your app will be required to be approved by our Admin team, will be when you are ready to list your app in the AppMarket. This is triggered by the ‘Is Listed’ status when editing your App.&#x20;

Along with the new app listing pages, as mentioned below, we are currently working on a simplified submit app wizard, which will change how we handle the requirements when editing your app. More on this to follow soon.

## 18/06/20

### &#xD;**New App Listing Pages**

We are pleased to announce that the App listing pages in the Developers Portal have been updated. This means you will now be able to add a more detailed description including bullet points, paragraphs, external links, and a featured image.

The description and imagery you upload, are incredibly important to help capture the user’s attention. &#x20;

With that in mind we have also added a ‘Preview’ feature. When you next open your app, you will see a ‘See Listing Preview’ option. It will open a new tab displaying your app listing exactly as it will be seen by users inside the AppMarket.

To maximise the space and to truly showcase your app, we have put together the following tips/guide to help.

### **Summary**

The summary is a short description about your app and will be one of the first things shown in the AppMarket before a user clicks through for more information.

Users should be able to clearly see what your app is about when browsing. You have a maximum of 150 character to utilise which will be displayed on both the app tiles and on your app listing.

### **Icon**

Your company icon will be shown on the left hand side of your app listing in the AppMarket.&#x20;

The suggested image size is 96px x 96px and the app icon is the first opportunity to communicate, along with the app summary, what you are offering. We recommend keeping the logo simple but should be recognisable and understandable. The icon will be placed on a white tile and background so ideally avoid text, screenshots or photos.

![Example Icon (TouchRight Software) ](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MDUwGPk93EWsZo2xaF4%2F-MDV8GtXvRVwmQC00_IR%2FTouchRight-Software-icon%5B1%5D.png?alt=media\&token=21e613b9-124d-4e4f-a519-9e63c6db7a38)

### **Featured Image**

The featured image is 495px x 222px and it will appear at the top of your listing page as the first graphic representations of your app before any screenshots.\
\
It may also be used for marketing within the portal under our ‘Recommended Apps’ or ‘Featured Apps’ sections as well as potentially used for external communications.

![Example Featured Image (Goodlord)](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MDUwGPk93EWsZo2xaF4%2F-MDUwdgQXHT92dfgRF86%2FOh-Goodlord-Ltd-screen1ImageUrl.png?alt=media\&token=8a5b53cf-dfec-40ae-a757-21f6ae391140)

With that in mind, we are looking for the Featured Image to be more of a graphic/advert style rather than a screen shot of the application. Ideally it should convey your app’s value proposition.

### **Description**

The next step after a user discovers your app in the AppMarket, is to read more about it.

Creating a detailed and accurate description of your app is what will give users the full understanding of what your app has to offer. Appealing enough to encourage users to install.

The description field on the app listing has been converted to support HTML. This means that you can now use paragraphs, bullet or numbered lists, headings and external links.

The focus should be on conveying the value of your app and should work alongside the images you provide.

A great way to think about how to format your description is to picture yourself as the user and what would appeal to you about your application, what problem exists and the solution it provides.

### **Imagery**

You have the option of uploading 4 screenshots on your app listing and we recommend images sizes of 598px x 457px

Whilst screenshots give the user the ability to see your app in action, you can create the screenshots to include text to highlight the important features. Really maximise the space and visual impact of your app listing

2 screenshots are placed directly under the ‘Summary’ and the other 2 are placed below the ‘Description’.

![Example Screenshot (GEO Diary) ](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MDUwGPk93EWsZo2xaF4%2F-MDV8WNSkKbAC5Sw1lod%2Fimage.png?alt=media\&token=2c290650-346b-46ab-a7c6-8848bc444a01)

### **Highlight Key Features**

You can add a bulleted or numbered list of key features within the description.

Key features should be quick, short paragraphs. Help your users to easily see the main value that your app provides.  Focus on the benefits. For example:&#x20;

* Mobile Friendly
* Easy to Install
* Helpful Hints
* Simple Reporting

### **External Links**

We are now supporting external links which allows you to navigate your users to your own website.

You can use this feature to perhaps link to your own website with a dedicated page with more information or video demos of your application.

Maybe even provide instructions on how to register an account with you or details on how to get in touch to your sales/support team.

If you have more information you want to share with the users, external links are a great way to achieve this. &#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MXCsXdgLWWpP7BX5_Oj%2F-MXCt30TykpEKM0fEL6L%2FGoodlordExample.jpg?alt=media\&token=cd85325c-89ec-4f7d-830f-8b2a356eac1d)

## 22/05/20

With the launch of the Beta Phase for the Foundations Developers Portal and with several more developers and PropTechs joining the Platform, we have been pretty busy the last few weeks. It has been great to see some of the applications that are being developed and also having the opportunity to see them in action with live demos . Our Development team have been concentrating on delivering the following new features in the Developers Portal which we are excited to share with you.

### Webhooks

With Foundations, you can now create a Webhook subscription which will allow you to be notified about changes as they happen to your chosen Endpoint.

Setting up a Webhook is very simple and can be created from the new ‘Webhooks’ page in the Developers Portal [here ](https://marketplace.reapit.cloud/developer/webhooks)

![Adding a new Webhook](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M7Mz5c0hCiu7ZI80Ii8%2F-M7MzQTDYgwhv-tONP33%2Fimage.png?alt=media\&token=19e72464-5d23-47ca-9c7d-48307e12668b)

It will give you the ability to chose which events to listen to with the option to select specific customers or all customers (once installed) for your selected applications.

We currently support subscriptions to events for a wide range of entities. For each type, you can choose to subscribe to created events, modified events (changes) or both. You will only be able to select topics based on the permissions assigned to your app.

Also, another very neat feature is the new ‘Ping’ option. Allowing you to test, in real time, your subscriptions to your chosen secure URL.

For more information on Webhooks please click [here](https://marketplace.reapit.cloud/developer/webhooks)

### Desktop Integration Types

Now you may have seen how our demonstration of how the desktop integration types will work when the Desktop API is ready, if not, you can see it in action here:&#x20;

{% embed url="<https://www.youtube.com/watch?v=aWYmxpWf6y0&feature=youtu.be>" %}

In the video, it is showing how the Homeflow application set a desktop type of ‘Property’. This means that within AgencyCloud, the application (after being installed) will appear within the native Property Screen.

![AgencyCloud Integration](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M7Mz5c0hCiu7ZI80Ii8%2F-M7MzcgzIGO7aJm5ATAY%2Fimage.png?alt=media\&token=8ab08dc0-7e6b-4702-9420-a59115a8ea3b)

You can set your Integration Type when Submitting or Editing your app in the Developers Portal. Whilst we are still in Beta Phase the current Integration Types are still in development but you can follow the progress [here](https://foundations-documentation.reapit.cloud/api/desktop-api#desktop-types)&#x20;

### Cost Explorer

An additional tab has been added on the ‘Analytics’ page, the ‘Cost Explorer’. This will provide you with detailed information on the individual costs for each Resource, Webhook & Service.

The ‘Services’ bar chart will give you a month to month total of your cost (excluding VAT).

![Example Services Bar Chart](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M7Mz5c0hCiu7ZI80Ii8%2F-M7Mzot4l333FTRlTUMx%2Fimage.png?alt=media\&token=15310ad5-6f44-4585-8429-c66b7894e5ee)

But for a more detailed breakdown you can use the ‘Cost Explorer: Usage & Cost’. This will provide the ability to see on a granular level, the amount you are spending on each Resource. Notably, until the AppMarket is live and you have app installations, you won’t see any traffic but you can an example below:

![Example Resource Table](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M7Mz5c0hCiu7ZI80Ii8%2F-M7Mztwc6g72H1MMqEV3%2Fimage.png?alt=media\&token=c1b4fe89-ed9a-41c8-92ec-faed816d33ac)

Selecting the ‘Configuration’ entity from the table, I can see the breakdown of the specific endpoint my apps have been interacting with, how many API calls have been made and the total cost for that month.

You will also be able to download a CSV file with the full ‘Transaction History’ per month for all your applications.

![Transaction History](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M7Mz5c0hCiu7ZI80Ii8%2F-M7Mzz68KoTFNtWbQbNs%2Fimage.png?alt=media\&token=8f3aa456-f0b3-44c3-b600-e8424aa7def6)

Finally, with the Cost Explorer we have also added a new feature the ‘Cost Calculator’. The calculator is interactive and provides a quick way to see the estimated cost for endpoints used against Monthly API Calls.

### Description Box

As we are working on developing the Client Portal (AppMarket) we want to ensure your app will be presented in the best way, this means providing the ability to add a better formatted description.

The ‘Description’ box when submitting or editing an App, has now been updated to support HTML. You can create headers, bulleted or numbered lists, line breaks and paragraphs.

![Updated Description Box](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M7Mz5c0hCiu7ZI80Ii8%2F-M7N-3ba7-yabuPjMEFW%2Fimage.png?alt=media\&token=3a83b8c6-dea7-4c9f-8521-4a945f252b5c)

We are also supporting ‘External Links’ which will no doubt be very handy to provide more information about your company and your app for potential clients.

### HTML feature in Elements

Elements Storybook now also supports a vanilla HTML. Simply apply the classes to your markup as displayed in the HTML tab in each Storybook component as per below:

![HTML Tab in Elements](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M7Mz5c0hCiu7ZI80Ii8%2F-M7N-8_mKj9qNC1E4XrQ%2Fimage.png?alt=media\&token=94fc9c9c-c3b6-4da2-a6b4-7a9510e3d781)

### Changes

The ‘Submit’ button has moved to the ‘Apps’ page. To submit your app, click on ‘Apps’ from the navigation bar and use the ‘Create New App’ button.

## 15/04/20

### Bring on the Beta.

We have officially started the Beta Phase! If you had signed up to the  Alpha Phase, you will be able to continue using the platform with no interruption, this is simply the next phase for the Developers Portal. \
\
For our new Beta Developers, welcome to Reapit Foundations. If you didn't get the chance, have a look at our on-boarding video [here](https://youtu.be/YSsy5-XonHI). It has been created to help you navigate the portal and to demonstrate what is available. Remember, if you have any questions or need any assistance, you can visit the 'Help' section.&#x20;

{% embed url="<https://youtu.be/YSsy5-XonHI>" %}
Foundations Developers Portal | On-boarding
{% endembed %}

What’s New has been designed to give you a high-level overview of the latest features and fixes that have been included over the last couple of weeks.

With that said, let us take a look at what we’ve been working on:

### New Features

#### Private Apps

A new section is now available in on the Submit and Edit app forms, giving you the ability to specify which customers you would like to share your application with. You can enter the Customer ID or IDs and when the AppMarket is live, only those customers will see your application in the AppMarket. It is especially helpful to those building in private in-house applications.&#x20;

![Private Apps section on the Submit and Edit App forms](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M51owHcujC_IlOeGvty%2F-M51pju69KVIi95qbtuK%2Fimage.png?alt=media\&token=ae319c7d-2ae8-4213-ace5-c86879d2c6b0)

For more information, please [click here ](https://foundations-documentation.reapit.cloud/developer-portal#3-register-an-app)

#### &#x20;Analytics

The Analytics section has had a significant update, you can now see the specific Endpoints and ‘Total’ number of hits for your App(s) as well as a graph displaying your ‘Hits Per Day’. As the data is Sandbox data you will see ‘SBOX’ in your client filter list, but this will include Client IDs when your app has been installed in the AppMarket.

In addition, you can now search the data using a date range filter or simply select a predefined option of ‘Yesterday’, ‘Last Week’ or ‘Last Month’. More to come on the Analytics page in the coming weeks.

![Example Analytics Data ](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M51owHcujC_IlOeGvty%2F-M51q-FOPd26obQgAp4R%2Fimage.png?alt=media\&token=a5db9e6c-00c2-4e4f-860d-af3ea57aa865)

#### Tags Input

A new ‘Tags Input’ component has been added to Elements. We will be using this on the Submit and Edit app forms shortly, but it is available for you to use, as are all the components in Elements. Selecting an item from a drop-down list, it will automatically add as a tag in the field. It also offers a hover over state allowing the user to clearly see a brief description regarding each selection.<br>

![Tags Input Component in Elements](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M51owHcujC_IlOeGvty%2F-M51qLaEGnlLx7Cmnelg%2Fimage.png?alt=media\&token=c5d04bab-a0d5-48bb-960b-dee657368a7f)

To see the new the component, please [click here](https://elements.reapit.cloud/?path=/story/dropdownselect--primary)&#x20;

## 31/03/20

Over the last couple of weeks we have been working on implementing a couple of new features, for example the Pending Revision modal as mentioned below. In addition and coming soon a new update to the 'Analytics' page within the developers portal which will provide additional and useful app statistics. &#x20;

### &#xD;Changes

**Pending Revisions**

We have now introduced the ability to view what revisions are currently pending and the option to ‘Cancel Pending Revision’.

When you have submitted a revision on your app, you will now be able to click on the ‘Pending Revision’ button (previously disabled) which will present a modal with the changes you have made highlighted.

![Example of the enabled 'Pending Revision' button](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M3kpPag7_y3MhsZ5r2W%2F-M3kqz0Ms73IhTnWGd5b%2Fimage.png?alt=media\&token=fba3c788-87d6-4973-9a19-bab09be86a85)

For text or selections that has been added it will be highlighted in GREEN and for text deleted or options deselected, it will be highlighted in RED.

![An example showing the diffing](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M51owHcujC_IlOeGvty%2F-M51tGexmdw3g2q3lET1%2Fimage.png?alt=media\&token=d26e5594-d972-4794-9f03-ac3052f7bed6)

If you wish to cancel your pending revision to make additional changes for example, click ‘Cancel Pending Revision’. It will immediately cancel the revision and you will be able make any edits as usual.

### Fixes

#### Checkbox group feature in Elements

There was a slight issue with the ‘Checkbox’ component in Elements not behaving correctly. This has been fixed and is now working as expected.

![Checkbox component in Elements](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M51owHcujC_IlOeGvty%2F-M51tOQnjG39-fYMdWgL%2Fimage.png?alt=media\&token=d55fdd35-3814-479f-9c2e-c419d11be5b1)

### New

#### Journal and Enquires API

The Journal API is now read and write and available within the Interactive API explorer. It has the ability to read and write dated event information into the Reapit Journal system and automatic generation of these events from other services. &#x20;

In addition, the Enquiries API is also available and gives the ability to read and write information about new leads into AgencyCloud.

## 11/03/20

I’m pleased to confirm it has been another successful week in the Alpha Phase, not only have we been able to deliver ahead of schedule in terms of a few of our [Milestones](https://github.com/reapit/foundations/milestones), I have also had the pleasure of speaking with you all and gathering your feedback regarding the Foundations Platform. We still have a few weeks to go until the end of the Alpha and already we have had quite a few entries for the Early App Program.&#x20;

Towards the end of March, we will be contacting those wishing to participate to confirm the specific details but if it is something you wish to take part in, please be sure to get in contact with our Marketing team. Remember, this is a great opportunity for your application and brand to be visible in the Marketplace.

Now let’s look at what we’ve been doing:

### Changes

**The release of the of Tenancies API**\
The ‘read’ functionality of the Tenancies API is now available. We are still developing the ‘updating’ and ‘creating’ functionality, but you should now get great visibility what is available and what information you can use within your application.

![Tenancies API ](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M3L9uiE6Hv41Y-cAEYQ%2F-M29MCUxstaFJzHCABYo%2Fimage.png?generation=1585214900651386\&alt=media)

To follow the milestone to see what is still to come and follow the progress, please [**click here**](https://github.com/reapit/foundations/milestone/13)

**Works Orders API**\
In addition and ahead of schedule, the ‘Works Order API’ is now up and running and fully interactive, read, write and update with the Sandbox data to see exactly what information you can use within Property Management.

![Example response of the Works Order API ](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M29LbT3jHamRfLuDZk2%2F-M29MTspG8kL1G9Tk_WT%2Fimage.png?alt=media\&token=fe6e600e-9d99-4cbc-8705-079d86dfa840)

\
**Embedding Data**\
Now available in the Interactive API Documentation, the option to request additional resources when making a GET request on our APIs.

If your application requires data from one or more related endpoints, you can simply specify the name of the related resource from the list provide in ‘Embed’ section and our APIs will do the rest.<br>

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M2YMSW7MW1fWlw1c8HV%2F-M2YMeW73xmmkZxj1exv%2Fembed.png?alt=media\&token=61d85e77-7b84-4d85-848e-b1908724c39a)

For more information of this feature, please [click here](https://foundations-documentation.reapit.cloud/api/api-documentation#embedding-data)

### Fixes

**Custom URL Schemes**\
We are now supporting Custom URL Schemes for your App, for the ‘Redirect URI’ and ‘Sign Out URI’ fields.

For example, ‘myapp\://’ is now an accepted format, previously it was causing an issue when trying to save on a ‘Submit’ or ‘Edit’ app page unless the format was https\:// or <http://localhost>

Don’t forget, whilst the ‘What’s New’ page will give you a brief look at some of the things we have been working on, the Platform Change Log and coming soon ‘Web Change Log’, will give a more detailed list on the issues we have been addressing. \
\
[Click here](https://foundations-documentation.reapit.cloud/whats-new/platform-changelog) to the view the ‘Platform Change Log’

To follow the release of our  Web Change Log, please [click here](https://github.com/reapit/foundations/issues/599) <br>

## 28/02/20

Firstly, thank you to all our Alpha partners for your feedback during the first week of the Alpha Phase. It has been incredibly useful in helping us make the necessary changes and updates that ultimately deliver a better experience for you.

Whilst we continue to update the system in the background, here are the highlights of the things we’ve been doing: &#x20;

**Changes**\
We have added a more informative way to display if the incorrect number of characters had been used in the ‘Summary’ and ‘Description’ fields on the ‘Submit’ app form. Previously, this wasn’t very obvious and resulted in delay when submitting an App.

![New, clearer validation now in place](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M1A37lVSDpCoPjqiRnv%2F-M1A3WVryoVvlnxmOiTK%2FSummaryField.png?alt=media\&token=1c27c569-2cec-4b8d-9500-f0715e82ce86)

**Fixes**\
Thanks to **Navin Mahendran** who reported an issue with the Scaffolder when trying to scaffold an app in the Windows Shell. I’m pleased to confirm this has been fixed and is ready to use immediately.

![Screenshot from the Reapit App Scaffolder ](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M1A37lVSDpCoPjqiRnv%2F-M1A4YfSnnB48sL81_VH%2FScreenshot%202020-02-16%20at%2013.48.28.png?alt=media\&token=38fdc2a0-d76e-4cbd-8b93-3e4f2d1434a3)

**Bugs - Interactive API Explorer** \
\
An issue was detected with the ‘CURL’ response, resulting in seeing an ‘Undefined’ error. This is now displaying the correct response.

![An example of the correct CURL response](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M1A37lVSDpCoPjqiRnv%2F-M1AAJ_TCO0CfyxkqgFx%2FCURL.jpg?alt=media\&token=e0bd81ad-5b8e-464c-8ae4-1412c4a5a497)

A missing comma from the JSON response has been found and is now back in place. A well spotted bug from **Erol Ziya**. &#x20;

![Content reported showing Expected and Actual Results](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M1BUmneptMXa3qa02xu%2F-M1BX6cysN9E6Dnvpcab%2FCommaMissing.png?alt=media\&token=a8e03c0a-1e80-4c63-bff0-8096a5242eea)

Also, we would like to give a quick thumbs up to those that have used the Live Chat feature and reported a bug directly on our board. It’s proving to be a great way for us to stay in communication and hopefully helping you navigate through the Developers Portal.

## 19-02-2020

What’s new? Well… everything! We have officially gone live with Reapit Foundations. Not only have we decided to create an independent Marketplace for all our AgencyCloud Users but it comes complete with a fully stocked Developers Portal, plus we’ve open sourced everything!

We want to share with you all we can in order to help you develop and interact with our Foundations Platform.

So, let's recap on a few things that we've been up to since the initial launch in Nov 19…

* Open sourced code ✔
* Easy to understand and follow documentation ✔
* Interactive APIs ✔
* Single-sign on and identity service ✔
* New cloud infrastructure ✔
* UI Storybook of usable components ✔
* Feature requesting ✔
* Public Roadmap. ✔

I think it's fair to say, we’ve been busy!

Our Developers have been working incredibly hard and we are all excited to see Reapit Foundations come to life. Each week, I’ll be featuring the best of our releases and talking about the exciting new features we have introduced into the Foundations Platform, as well as sharing updates on our APIs as they happen.

So, this week is the start of the very much anticipated Alpha launch. With that in mind, let me talk you through just a few of the features our new Developer Portal has to offer:

### GitBook Integration

Those of you familiar with [GitBook, ](https://www.gitbook.com)will know they are the leader in the industry for organising and detailing technical documentation. We’ve used the best of the best to ensure you can find and reference what you need as easily as possible. We know the importance of documentation and want you to have the right tools. You can access the documentation from within the developers' portal from the '[Docs](https://marketplace.reapit.cloud/developer/api-docs)' page.&#x20;

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M03Nja3JJ7AnMpkH5p7%2F-M03Q6WOF-Gq7Y1LTBEX%2FGitBook.png?alt=media\&token=05b80961-8efe-4923-a5fe-3175041410da)

### Instant Support

Available for a **limited time only**, direct access to our Foundations Platform Product Owners and Developers. You can access this feature from the ‘[Help](http://marketplace.reapit.cloud/developer/help)’ section in the developer portal. We hope you won’t need us and that everything you need can be found within our documentation but it’s nice to know we’re here if you do.

![Live Chat feature](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M53Oao7cRP43Qrx5txu%2F-M53Pzg0LipRGUvZk4U-%2Fimage.png?alt=media\&token=5fb4c14b-ef6c-408b-9f3f-0d3c24eae04d)

### Full Visibility ([Roadmap](https://github.com/reapit/foundations/milestones?direction=asc\&sort=due_date\&state=open))

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-M03Nja3JJ7AnMpkH5p7%2F-M03R77zzqqyWQrS5H2v%2Fimage.png?alt=media\&token=ac022738-de9c-452f-8f7f-bb71c3ffc35c)

From every issue raised through to completion, you’ll have full visibility on what we’re doing. We want you to be a part of this exciting new platform, which is why we’ve opened sourced not only our cloud applications but also our developer portal! Giving you the ability to submit feature requests or to raise bugs directly on our Foundation Repo and track the progress.

These are only a but a few of the features we have included with many more still yet to come.  \
\
If you're interested, we will also soon be including a release note section, giving you detailed information on everything that has been changed, fixed or showcasing something new.  <br>

#### Finally...&#x20;

Feedback is important!  We have spent a long time creating the Developer Portal and we know it inside out but it helps to hear what you think. So, whilst you are reading through the Documentation, testing the endpoints, or simply navigating through the Portal, we want your feedback. We don't even mind bugs! It's the Alpha Launch, all feedback is welcome. Remember, you can use the [Request a Feature](https://github.com/reapit/foundations/issues/new?labels=feature-request\&projects=reapit/foundations/3\&body=Summary%20of%20Request:%0d%0dExpected%20Behaviour) or [Report a Bug](https://github.com/reapit/foundations/issues/new?labels=bug\&projects=reapit/foundations/2\&body=Summary:%0d%0dSteps%20to%20reproduce:%0d%0dExpected%20Results:%0d%0dActual%20Results) from the 'Help' section to get in contact.&#x20;


# Platform Glossary

This section provides further information on the concepts and terminology referenced by the Reapit Foundations Platform and the endpoints we provide

### Applicant

Applicants represent the [property](/platform-glossary#property) buying or renting interests of one or more [contacts](/platform-glossary#contact) or [companies](/platform-glossary#company). This includes requirements such as the number of rooms, maximum budget and the geographical areas that the applicant is interested in.&#x20;

### Area

Areas represent a specific geographical location that an [applicant ](/platform-glossary#applicant)is interested in buying/renting within. Areas are comprised of either polygon coordinates or a listing of postcodes. Areas are hierarchical and a single area can alternatively include a list of other areas.

### Appointment

Appointments represent calendar engagements used by [negotiators](/platform-glossary#negotiator) to schedule meetings or arrange events, such as [property](/platform-glossary#property) viewings and valuations. Appointments can be set to recur by including recurrence information and can be scheduled to appear in multiple [negotiators](/platform-glossary#negotiator)’ calendars.

### Auctions

Auctions represent internal or external [property](https://foundations-documentation.reapit.cloud/platform-glossary#property) sales using lots. Properties can be organised into single and multiple lots for auction.

### Company

Companies represent a business organisation that the agent ([customer](/platform-glossary#customer)) has a relationship with. Companies can be assigned a type which relates to the various roles they are able to fulfill such as solicitor or supplier, as well as being able to be involved in their own [property](/platform-glossary#property) transactions.

### Configuration

Configuration represents the customisation options relevant for a customers data set, as some data can differ depending on the configuration of the customer. For example, an agent may want to add to their list of [vendor](/platform-glossary#vendor) selling reasons so that it can be set against a particular [vendors ](/platform-glossary#vendor)`sellingReasonId`

We present lists like this as RESTful endpoints and document where a field references a configurable lists id. We also include links/embed options where appropriate to simplify consumption.

### Contact

Contacts represent the details of a person that the agent has a relationship with. Contact details are captured and managed centrally so that a single contact can fulfill multiple [vendor](/platform-glossary#vendor), [landlord](/platform-glossary#landlord), [applicant ](/platform-glossary#applicant)and [tenancy](/platform-glossary#tenancy) roles at the same time.

### Conveyancing

Conveyancing represents the process of progressing an accepted [offer ](/platform-glossary#offer)to the completion of the sale of a property.&#x20;

Submitting new offers and transitioning them to an accepted status is done using the Offers API. The Conveyancing API is responsible for transitioning that existing, accepted offer into a completed property sale.&#x20;

Our Conveyancing APIs also allow a chain to be managed, providing a means of linking dependant offers together. It's possible to link to offers added to other properties that the customer has instructed, as well as those that are external and instructed to another agent.

### Customer

Customers represent estate agents who use Reapit software. We do not provide an API to obtain details of our customers, instead, their details will be known to you at the point that they install your AppMarket application.&#x20;

### Department

Departments represent a set of descriptive attributes used to describe a [property](/platform-glossary#property). Departments are assigned to both [properties](/platform-glossary#property) and [applicants ](/platform-glossary#applicant)and are used to define which attributes can be used to describe a [property ](/platform-glossary#property)or an [applicant](/platform-glossary#applicant) property requirement.

A Department is most commonly used to ring fence groups of [properties](/platform-glossary#property) and [applicants](/platform-glossary#applicant), particularly when it comes to matching (the process of finding properties that meet specific applicant requirements and vice versa). Typically, customers dealing with only residential sales and lettings will have a single department as there is no real need to separate any of the data, however an example of where multiple departments might be configured would be a customer who deals with both residential and commercial property transactions. In this scenario, a separate Department would normally be setup to separate the two disparate sets of data, as it would be undesirable for residential applicants to be sent details of commercial properties.

#### Interpreting Department Data <a href="#interpreting-department-data" id="interpreting-department-data"></a>

Departments are completely customisable for each agent and subsequently it can be difficult to understand how to interpret this data as it comes out of the various APIs that expose it. As the APIs are standardised across all our customers, Department data has also been standardised where possible using a mapping mechanism to map the customisable values from our CRM into standard values in the API. Any options that do not have a corresponding mapping and are selected on a [Property ](#property)or [Applicant ](#applicant)entity will be included in the `unmappedAttributes` and `unmappedRequirements` collections in their respective APIs. Additionally, the *Special* attributes column in the CRM is mapped explicitly.&#x20;

The tabbed content below provides the latest version of the mappings

{% tabs %}
{% tab title="Type" %}
The following table shows the values exposed in the `type` collection returned by the [Applicant](#applicant), [Property ](#property)and [Department ](#department)APIs and their corresponding mappings back to the AgencyCloud CRM.

| Platform Value         | AgencyCloud Mapping                                                      |
| ---------------------- | ------------------------------------------------------------------------ |
| bungalow               | Bungalow                                                                 |
| commercial             | Commercial                                                               |
| cottage                | Cottage                                                                  |
| developmentOpportunity | Development Opportunity                                                  |
| developmentPlot        | Development Plot, Single Plot, Plot, Building Plot                       |
| estate                 | Estate, Farm/Estate, Residential Farm/Estate, Country Estate             |
| farm                   | Farm                                                                     |
| flatApartment          | Flat/Apartment, Flat / Apartment, Flat, Apartment, Unit/Apartment, Flats |
| garage                 | Garage, Garage Lockup, Lockup, Garage Only                               |
| hotel                  | Hotel, Hotels                                                            |
| house                  | House, House/Villa                                                       |
| industrial             | Industrial, Industrial/Storage                                           |
| land                   | Land                                                                     |
| leisure                | Leisure, Leisure Facility                                                |
| maisonette             | Maisonette                                                               |
| mixedUse               | Mixed Use, Mixed                                                         |
| office                 | Office, Offices                                                          |
| publicHouse            | Public House, Pub                                                        |
| retail                 | Retail                                                                   |
| shop                   | Shop                                                                     |
| smallHolding           | Small Holding                                                            |
| studio                 | Studio, Studio Flat                                                      |
| townhouse              | Townhouse, Town House                                                    |
| villa                  | Villa                                                                    |
| warehouse              | Warehouse, Warehouse/Distribution                                        |
| {% endtab %}           |                                                                          |

{% tab title="Style" %}
The following table shows the values exposed in the `style` collection returned by the [Applicant](#applicant), [Property ](#property)and [Department ](#department)APIs and their corresponding mappings back to the AgencyCloud CRM.

| Platform Value     | AgencyCloud Mapping                                            |
| ------------------ | -------------------------------------------------------------- |
| basement           | Basement                                                       |
| bungalow           | Bungalow                                                       |
| detached           | Detached                                                       |
| duplex             | Duplex                                                         |
| endTerrace         | End of Terrace                                                 |
| firstFloor         | First Floor                                                    |
| groundFloor        | Ground Floor                                                   |
| linkDetached       | Link Detached, Link-Detached                                   |
| lowerGroundFloor   | Lower Ground Floor, Lower Ground                               |
| mews               | Mews                                                           |
| penthouse          | Penthouse                                                      |
| semiDetached       | Semi Detached, Semi-Detached                                   |
| steading           | Steading                                                       |
| studio             | Studio, Studio Flat                                            |
| terraced           | Terraced, Terrace                                              |
| upperFloor         | Upper Floor, Upper Floor without Lift, Upper Floor w/out Lift  |
| upperFloorWithLift | Upper Floor with Lift, Upper Floor w/Lift, Upper Flr with Lift |
| {% endtab %}       |                                                                |

{% tab title="Situation" %}
The following table shows the values exposed in the `situation` collection returned by the [Applicant](#applicant), [Property ](#property)and [Department ](#department)APIs and their corresponding mappings back to the AgencyCloud CRM.

| Platform Value | AgencyCloud Mapping                         |
| -------------- | ------------------------------------------- |
| balcony        | Balcony                                     |
| communalGarden | Communal Garden                             |
| conservatory   | Conservatory                                |
| garden         | Garden                                      |
| julietBalcony  | Juliette Balcony                            |
| land           | Land/Paddock, Land / Paddock, Paddock Land  |
| outsideSpace   | Outside Space                               |
| patio          | Patio                                       |
| roofTerrace    | Roof Terrace, Terrace, Roof Terrace/Terrace |
| {% endtab %}   |                                             |

{% tab title="Locality" %}
The following table shows the values exposed in the `locality` collection returned by the [Applicant](#applicant), [Property ](#property)and [Department ](#department)APIs and their corresponding mappings back to the AgencyCloud CRM.

| Platform Value | AgencyCloud Mapping                                         |
| -------------- | ----------------------------------------------------------- |
| rural          | Rural                                                       |
| townCity       | Town/City, Town / City, Town, Town Centre, Town/City Centre |
| village        | Village                                                     |
| {% endtab %}   |                                                             |

{% tab title="Parking" %}
The following table shows the values exposed in the `parking` collection returned by the [Applicant](#applicant), [Property ](#property)and [Department ](#department)APIs and their corresponding mappings back to the AgencyCloud CRM.

| Platform Value | AgencyCloud Mapping                                                                                                                                       |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| carport        | Carport, Car Port                                                                                                                                         |
| doubleGarage   | Double Garage                                                                                                                                             |
| garage         | Garage                                                                                                                                                    |
| offStreet      | Off Street Parking, Off Road Parking, Driveway, Off Street                                                                                                |
| residents      | Residents Parking, Resident Parking, Parking, Allocated Parking, Permit Parking, Garage/Parking Space, Allocated Parking Space, Allocated/Private Parking |
| secure         | Secure Parking, Gated Parking                                                                                                                             |
| tripleGarage   | Triple Garage                                                                                                                                             |
| underground    | Underground, Underground Parking, Secure Underground Parking                                                                                              |
| {% endtab %}   |                                                                                                                                                           |

{% tab title="Age" %}
The following table shows the values exposed in the `age` collection returned by the [Applicant](#applicant), [Property ](#property)and [Department ](#department)APIs and their corresponding mappings back to the AgencyCloud CRM.

| Platform Value | AgencyCloud Mapping                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| modern         | Modern, Post War, Post-war, Modern (Post 1945), Modern (1920+)                                                |
| new            | New, New Build, New Homes, New Home, New (Off Plan), Newly Built, New Property, New Development, New Property |
| period         | Period, Pre-war, Period (to 1714), Period (Pre 1945), Period (Pre-1920)                                       |
| {% endtab %}   |                                                                                                               |
| {% endtabs %}  |                                                                                                               |

### Document

Documents represent the details of a file asset that has been added to our platform. Documents can be assigned a type to indicate its purpose (eg. a brochure) and associated to an associated entity (eg. a [property](/platform-glossary#property)).

When using the `GET /documents/{id}/download` endpoint to download the physical file asset, you must pass an `Accept` header with the value `application/octet-stream`

### Enquiry

Enquiries (Internet Registrations) represent a potential sales or lettings lead for the agent. An enquiry can either contain information about a valuation request from a [vendor](/platform-glossary#vendor)/[landlord](/platform-glossary#landlord) or can represent interest from a potential [applicant](/platform-glossary#applicant) such as a viewing request. Enquiries are vetted by the agent before they are promoted into [property](/platform-glossary#property) or [applicant ](/platform-glossary#applicant)entities. Enquiries will appear in AgencyCloud under the 'Internet Registrations' section.&#x20;

### Identity check

Identity checks represent the information captured to verify the identity of a [contact](/platform-glossary#contact) or [company](/platform-glossary#company). Agents must adhere to anti-money laundering regulations and are required to capture proof of identity and address for their customers. Identity checks can store textual information such as passport number as well as file assets associated as [documents](/platform-glossary#document) (such as scanned copies).

When a company Id is used to retrieve an identity check, the company Id is labelled `contactId` in the returning payload.

### Journal entry

Journal entries indicate that an event has occurred for an associated entity. For example, if a [property](/platform-glossary#property) asking price was changed, this event would be recorded as a timestamped journal entry. Journal entries are used to drive the various activity feeds in our CRM systems.

### Landlord

Landlords represent the details of one or more [contacts](/platform-glossary#contact) or [companies](/platform-glossary#company) that wish to rent out a [property](/platform-glossary#property). Landlords can have a portfolio of any number of [properties](/platform-glossary#property)[ ](https://foundations-documentation.reapit.cloud/platform-glossary#properties)on the system.

### Negotiator

Negotiators represent a member of staff working for an agent. Details about the individual negotiator are captured such as name, job title and email address – as well as the singular [office](/platform-glossary#office) to which they are assigned.

### Notification

A notification is an event that can be passed through to Reapit products in real-time to notify users that something has happened (or is happening). You can read more about the Notifications API and it's associated functionality [here](/api/notifications). Please note that this feature is currently in beta.

### Metadata

Our [metadata ](/api/api-documentation#metadata)system allows you to easily extend the data that our platform supports. Most of our POST and PATCH endpoints provide the ability to attach a JSON document to our entities which will be automatically included in future fetches of that entity.&#x20;

When using our specific metadata endpoints for more direct, granular control on the data you provide, you can also build new, standalone entities that are specific to your application without needing to hosting your own datastore.&#x20;

Metadata is specific to a developer and any data that your application sets will not be presented to other developers who build on the Foundations platform. We do not recommend using metadata storage for any sensitive information (personally identifiable details, bank accounts, etc).

### Offer

Offers represent the submission of an offer from an [applicant ](/platform-glossary#applicant)to purchase a [property](/platform-glossary#property). Offers are for property sales only and represent information such as monetary amount, date of submission and a status to indicate whether the offer can proceed or not.

### Office

Offices represent the details of a branch within an agency. Offices contain information about the office such as manager, contact details and address, though some offices may be virtual and not have a physical address. Each office can contain multiple [negotiators](/platform-glossary#negotiator).

### Property

Properties represent the details of a building that the agent has had an interaction with. Properties include specifics such as the number of rooms, asking price and descriptive marketing details. Properties can be flagged for both sales and lettings marketing concurrently and are associated to a single [vendor](/platform-glossary#vendor) and/or [landlord](/platform-glossary#landlord) entity.

### Property image

Property images represent a picture that has been taken of a [property](/platform-glossary#property) to be used for marketing purposes. Property images are most frequently used for display on portals, agent web sites and for generation of printed materials.

### Referral

A referral is the action of directing a [contact ](#contact)or [vendor ](#vendor)to a third party where there may be interest in the services on offer. This could be anything from a solicitor to a removals company. Users of the AgencyCloud CRM will typically be the ones to initiate a referral.

### Rest hook

Rest hooks are a [loose standard](https://resthooks.org/) for providing a set of APIs to create a [web hook](/api/webhooks) programmatically. If your application uses web hooks, this functionality can help you automate onboarding of customers and remove any manual steps needed in the portal.

### Source

Sources represent the origin of enquiry for a potential customer. Many entities such as [applicant](/platform-glossary#applicant), [landlord](/platform-glossary#landlord) and [contact](/platform-glossary#contact) can capture source information which allows the agent to understand where their business is coming from (for example, a portal or google search).

### Task

Tasks represent details on an action that should be performed by a given date. Tasks are categorised by type and can optionally be related to another entity (for example, a task to remind a [negotiator](/platform-glossary#negotiator) to call a [landlord](/platform-glossary#landlord)). If no activation date is specified, tasks can be used to send messages to and from [negotiators](/platform-glossary#negotiator)/[offices](/platform-glossary#office).

### Tenancy

Tenancies represent a [property](/platform-glossary#property) lease agreement between a [landlord](/platform-glossary#landlord) and one or more tenants. The role of the agent during the life-cycle of the tenancy will differ, depending on the agreement with the [landlord](/platform-glossary#landlord). The tenancy can be managed from offer submission/arranging stage right through until the tenancy is finished.

### Transaction

Transactions represent a financial transaction that can be associated to a [property](/platform-glossary#property), [landlord](/platform-glossary#landlord), [tenancy](/platform-glossary#tenancy), or [company](/platform-glossary#company). Examples of transactions are rent payments and supplier invoices. A transaction can be associated with one or more of the aforementioned related entities.

### Vendor

Vendors represents one or more [contact](/platform-glossary#contact) or [companies](/platform-glossary#company) who are interested in selling a [property](/platform-glossary#property). A vendor is always associated to a single [property](/platform-glossary#property) record and is automatically created when a [property](/platform-glossary#property) with sales marketing is added to the platform.

### Works order

Works orders represent one or more maintenance jobs that have been requested for a lettings [property](/platform-glossary#property). Works orders are usually reported by the [landlord](/platform-glossary#landlord) or [tenant ](/platform-glossary#tenancy)and can be tracked from approval until the work has been completed. Approved works orders are assigned to a [company](/platform-glossary#company) supplier who can then provide estimates and costings for the work.


# Permissions&#x20;

Please see the below list of permissions that 3rd parties can request to access - further broken down into 'Read' (ingest CRM information) and 'Write' (pushes new or amended data into CRM)

<table data-header-hidden><thead><tr><th valign="bottom"></th><th valign="bottom"></th></tr></thead><tbody><tr><td valign="bottom"><p> </p><p><strong>Permission</strong></p><p> </p></td><td valign="bottom"><p> </p><p><strong>Description</strong></p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Applicants</p><p> </p></td><td valign="bottom"><p> </p><p>Records data for potential buyers or renters, including their requirements, sources, and notes, linked to Contact or Company records.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Areas</p><p> </p></td><td valign="bottom"><p> </p><p>Geographical locations defined by agents for their coverage area, specified using longitude and latitude coordinates.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Appointments</p><p> </p></td><td valign="bottom"><p> </p><p>Diary data that includes appointment types, attendees, and inspection documents.</p><p> </p></td></tr><tr><td valign="bottom">Certificates</td><td valign="bottom">Records data added into 'Safety Checks, Certificates, Insurance &#x26; Warranties panel', including the type, start/expiry, status and reference number. </td></tr><tr><td valign="bottom"><p> </p><p>Companies</p><p> </p></td><td valign="bottom"><p> </p><p>Business organisations with which the agent maintains relationships. Companies can be assigned types corresponding to their roles (e.g., solicitor, supplier) and can participate in property transactions.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Contacts</p><p> </p></td><td valign="bottom"><p> </p><p>Primary records with associated roles such as Applicant, Vendor, Tenancy, or Landlord. Includes personal details and marketing/communication preferences.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Conveyancing</p><p> </p></td><td valign="bottom"><p> </p><p>Process for sales progression and transitioning accepted offers into completed property sales, including chain management as a sub-resource.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Documents</p><p> </p></td><td valign="bottom"><p> </p><p>Storage for file asset details that can be assigned types indicating purpose (e.g., brochure) and associated with specific entities (e.g., property).</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Enquiries</p><p> </p></td><td valign="bottom"><p> </p><p>Potential sales or lettings leads (shown as Internet Registrations in the CRM) representing interest from prospects, such as viewing or valuation requests, which are reviewed by negotiators before conversion.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Identity Checks</p><p> </p></td><td valign="bottom"><p> </p><p>Information collected to verify the identity of contacts or companies using primary and secondary identifiers with expiry dates and document links.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Invoices</p><p> </p></td><td valign="bottom"><p> </p><p>Records of charges issued against properties, including monetary values such as net and outstanding amounts.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Journal Entries</p><p> </p></td><td valign="bottom"><p> </p><p>Timestamped events relating to one or more entities that appear in various activity feeds within the CRM.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Keys</p><p> </p></td><td valign="bottom"><p> </p><p>Property key information stored within the properties data structure.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Landlords</p><p> </p></td><td valign="bottom"><p> </p><p>Records linked to contacts or companies wishing to rent properties, with potential one-to-many relationship with properties.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Negotiators</p><p> </p></td><td valign="bottom"><p> </p><p>CRM users or agency staff members, including their name, job title, email address, and office association.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Offers</p><p> </p></td><td valign="bottom"><p> </p><p>Records of monetary amounts proposed by applicants for sales properties, including submission dates, statuses, inclusions, exclusions, and conditions.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Offices</p><p> </p></td><td valign="bottom"><p> </p><p>Branch information for an agency, including office details, manager, contact information, and address.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Properties</p><p> </p></td><td valign="bottom"><p> </p><p>Comprehensive property record data including descriptions, notes, marketing materials, utilities information, keys, certificates, developments, and images such as EPCs, floorplans, and maps.</p><p> </p></td></tr><tr><td valign="bottom">Property Alarm Data</td><td valign="bottom">Records data related to a property records alarm data, including; gategory, type, location, checks, service data &#x26; expiry dates. </td></tr><tr><td valign="bottom"><p> </p><p>Referrals</p><p> </p></td><td valign="bottom"><p> </p><p>Records of contacts directed to third-party services offered through the agency, ranging from solicitors to removals companies.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Sources</p><p> </p></td><td valign="bottom"><p> </p><p>Origin points for customer enquiries that can be associated with various CRM records such as applicants, landlords, and vendors.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Tasks</p><p> </p></td><td valign="bottom"><p> </p><p>Action items for CRM users with specified dates, categorised by type and potentially related to other entities.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Telephony Notifications</p><p> </p></td><td valign="bottom"><p> </p><p>Real-time CRM events that notify users when something has occurred, currently restricted to specific permissions.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Tenancies</p><p> </p></td><td valign="bottom"><p> </p><p>Property lease agreements between landlords and tenants/applicants, including dates, utility readings, fees, and deposit details.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Transactions</p><p> </p></td><td valign="bottom"><p> </p><p>Records of financial activities against properties, including lettings transactions and works orders.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Vendors</p><p> </p></td><td valign="bottom"><p> </p><p>Records of contacts or companies selling properties, with each vendor associated with a specific property, including selling reason and source.</p><p> </p></td></tr><tr><td valign="bottom"><p> </p><p>Works Orders</p><p> </p></td><td valign="bottom"><p> </p><p>Maintenance job records for lettings properties, typically reported by landlords or tenants and assigned to supplier companies once approved.</p><p> </p></td></tr></tbody></table>

&#x20;


# Developer Terms and Conditions

These Terms and Conditions govern access to and of Reapit’s Foundations Platform.

### Versions&#x20;

| 1st December 2025  | [Terms and Conditions.pdf](https://reapit-marketplace-app-media-prod.s3.eu-west-2.amazonaws.com/foundations-terms-011225.pdf) |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| 1st September 2025 | [Terms and Conditions.pdf](https://reapit-marketplace-app-media-prod.s3.eu-west-2.amazonaws.com/Foundations-terms-010925.pdf) |
| 25th June 2021     | [Terms and Conditions.pdf](https://reapit-marketplace-app-media-prod.s3.eu-west-2.amazonaws.com/Foundations-terms-250621.pdf) |
| 17th November 2020 | [Terms and Conditions.pdf](https://reapit-marketplace-app-media-prod.s3.eu-west-2.amazonaws.com/foundations-terms-171120.pdf) |
| 16th June 2020     | [Terms and Conditions.pdf](https://reapit-marketplace-app-media-prod.s3.eu-west-2.amazonaws.com/foundations-terms-160620.pdf) |

Version Date: 1st December 2025

### 1 DEFINITIONS AND INTERPRETATION&#x20;

1.1 The following words and expressions have the following meaning:&#x20;

| Agreement                                                | <p>means the Reapit User Terms and Conditions, together with the Registration Details. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API Call                                                 | <p>means the messenger that delivers the Developer’s request to the Platform and then delivers the response back to the Developer. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| <p>API or Application Programming Interface </p><p> </p> | means a programming interface used to pass data back and forth between software applications and programs in a formalised way.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| App Marketplace                                          | <p>means the online marketplace through which Reapit makes available Applications and which is part of the Platform. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Applicable Laws                                          | <p>means, in relation to a Party, all applicable laws, enactments, regulations, regulatory policies, binding industry codes, regulatory permits and regulatory licences which are in force from time to time during the term of this Agreement and that apply to the performance of that Party’s obligations pursuant to this Agreement. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Application                                              | <p>means a software application made available from the App Marketplace. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Application User Terms                                   | <p>means the terms of use for an Application on the App Marketplace. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| <p>Application User Terms Principles </p><p> </p>        | means the principles set out in Schedule 1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Approved Application                                     | <p>means an Application which has been approved by Reapit in accordance with clause 2.5. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Business Day                                             | <p>means a day (other than a Saturday or Sunday) on which banks are generally open in London for normal business. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Client Side Application                                  | <p>means an Application that (i) uses Reapit Connect and (ii) is a web application (either a single page application or server rendered site). </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Commencement Date                                        | <p>means the date on which Reapit grants the Developers access to the Platform. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Consequential Loss                                       | <p>includes any loss of revenue, loss of profit, loss or corruption of data, loss of bargain, loss of actual or anticipated savings or business, loss of value of equipment, loss of opportunities (including opportunities to enter arrangements with third parties), and any other form of consequential, incidental, exemplary, punitive, special or indirect loss, but in the case of Reapit expressly excludes loss of contract, loss of actual or anticipated business and loss of opportunities in connection with or with respect to any future or prospective clients. </p><p> </p>                                                                                                                                                                                          |
| Contract Year                                            | <p>means each period of one year commencing on the Commencement Date (for the first Contract Year) or each anniversary of the Commencement Date.  </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Customer Developer                                       | means a Developer whose organisation has an active customer contract with Reapit for the use of any Reapit Software                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Data                                                     | <p>means any data that a Developer can access in an Application or otherwise by accessing the Platform and may include Personal Data. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Data Protection Laws                                     | <p>means any applicable laws and regulations relating to privacy or the use or processing of data relating to natural persons, including: (a) the 2018 Data Protection Act (the <strong>DPA</strong> including the <strong>UK GDPR</strong>;) (b) the Privacy and Electronic Communications (EC Directive) Regulations 2003; and (c) the General Data Protection Regulation (EU Regulation 2016/679) (<strong>GDPR</strong>); and (d) any laws or regulations ratifying, implementing, adopting, supplementing or replacing the DPA, UK GDPR, or GDPR and in each case as amended or replaced from time to time, together with any binding guidance and codes of practice issued from time to time by relevant supervisory authorities. </p><p> </p>                                  |
| Developer                                                | <p>means the entity identified as such in the Registration Details. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Developer Edition                                        | <p>means a single user downloadable version of the Reapit CRM software for the purpose of testing integrations and Applications in the Developer environment by the Developer. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| <p>Developer Edition Licence </p><p> </p>                | means a non-exclusive, royalty-free, worldwide licence to access a Developer Edition for the purpose of developing and testing Applications.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Developer Feedback                                       | <p>means any data, information, text, drawings, records, documents and other materials provided pursuant to clause 4.2.2. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| <p>Developer IPR Claim </p><p> </p>                      | is defined in clause 4.3.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| <p>Developer Obligations </p><p> </p>                    | means the requirements set out in Schedule 3.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| <p>Dispute Resolution Procedure </p><p> </p>             | means the procedure for the resolution of Disputes specified in clause 15.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Documentation                                            | <p>means any technical information and documentation necessary for the use of the Application. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| External Developer                                       | means a Developer that is not a Customer Developer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Fees                                                     | <p>means the fees which are set out in Schedules 2 and 4, or as otherwise agreed in writing between the Parties from time to time and which can include the following: </p><p>(a) Annual Registration Fee;  </p><p>(b) Annual Application Listing Fees;  </p><p>(c) API Consumption Fees;  </p><p>(d) Administration Fees;  </p><p>(e) Interest charges. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Force Majeure Event                                      | <p>means any cause or causes beyond the reasonable control of the Party claiming to be subject to it, including: any extremely severe weather, landslide, storm, lightning, fire, subsidence, epidemic, outbreak of military hostilities (whether or not war is declared), expropriation by governmental authorities, act of God, governmental act (other than a Regulatory Change), act of terrorism, earthquake, flood, embargo, riot, sabotage, strike (other than of its own Staff), failures of Third Parties (other than Subcontractors), explosion or civil commotion as well as any Applicable Laws which were enacted as a result of a Force Majeure Event. </p><p> </p>                                                                                                     |
| Initial Term                                             | <p>means one Contract Year from the Commencement Date. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Insolvency Event                                         | <p>means in relation to a Party, the convening of a meeting of its creditors or if a proposal is made for a voluntary arrangement within Part I Insolvency Act 1986 or a proposal for any other composition scheme or arrangement with (or assignment for the benefit of) its creditors or if the other is unable to pay its debts within the meaning of s.123 Insolvency Act 1986 or if a trustee receiver administrative receiver or similar officer is appointed in respect of its business or assets or if a petition is presented or a meeting is convened for the purpose of considering a resolution or other steps are taken for its winding or for the making of an administration order (otherwise than for the purpose of an amalgamation or reconstruction). </p><p> </p> |
| Intellectual Property Rights                             | <p>means: </p><p>(a) copyright, patents, database rights, trade marks, rights in designs, rights in know-how and confidential information (in each case whether registered or unregistered); </p><p>(b) applications for registration, and the right to apply for registration, for any of these rights; and </p><p>(c) all other intellectual property rights and equivalent or similar forms of protection existing anywhere in the world. </p><p> </p>                                                                                                                                                                                                                                                                                                                             |
| Loss                                                     | <p>means claims, demands, actions, awards, judgments, settlements, costs, expenses, liabilities, damages and losses (including all interest, fines, penalties, management time and legal and other professional costs and expenses). </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Party                                                    | <p>means Reapit or the Developer (as the case may be) and Parties means Reapit and the Developer. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Personal Data                                            | <p>has the meaning set out in the Data Protection Act 2018. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Platform                                                 | <p>means Reapit’s App Marketplace and online portal of developer tools, documentation and other reference materials which facilitate the development of Applications and their integration with Reapit Software. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Reapit                                                   | <p>means Reapit Limited, registered in England (registered number 03483017) whose registered office is at 67 – 74 Saffron Hill, London, EC1N 8QX. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Staff                                                    | <p>means, in respect of either party, that party’s employees, agents and sub-contractors and any other person working on that party’s behalf. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Reapit Software                                          | <p>means any platforms, solutions, services or other products operated by Reapit. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Registration Details                                     | <p>means the data required to be entered by the Developer in order to be permitted to use the Platform. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Regulator                                                | <p>means any person having regulatory or supervisory authority over all or any part of (a) the Services or (b) the business of Reapit or (c) the business of Developer. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Server Side Application                                  | <p>means authentication using a REST service on the server, typically pulling Data into an existing Application. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Services                                                 | <p>means the services to be provided by Reapit to the Developer under this Agreement. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Term                                                     | <p>means the duration of the Agreement, as determined in accordance with the terms of clause 11. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Third Party                                              | <p>means any person which is not a Party. </p><p> </p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

1.2 The words “including” and “include” mean “including without limitation” and “include without limitation”, respectively.&#x20;

1.3 Any reference to a time of day is to United Kingdom time.&#x20;

1.4 The Schedules form part of this Agreement.&#x20;

1.5 The headings do not affect the interpretation of this Agreement.&#x20;

1.6 Any reference to a statute or statutory provision includes, unless the context otherwise requires, a reference to that statute or statutory provision as from time to time amended, consolidated, extended, re-enacted, or replaced and to all statutory instruments, orders, regulations or rules made pursuant to it. &#x20;

1.7 All references to the Parties include their permitted successors and assigns.&#x20;

### **2 PLATFORM AND APPLICATIONS**&#x20;

2.1 Reapit hereby grants the Developer access to the Platform for the purpose of:&#x20;

2.1.1 developing Applications;&#x20;

2.1.2 publishing Approved Applications; and&#x20;

2.1.3 accessing any other features and services that Reapit may choose to make available through the Platform from time to time.&#x20;

2.2 As a condition of such continuing access, the Developer agrees that it:&#x20;

2.2.1 will comply with the Developer Obligations. &#x20;

2.2.2 must not reverse engineer, create derivative works from, or exceed permitted usage limits of the Reapit API.&#x20;

2.2.3 must not pass on the costs associated with accessing or using the Reapit API directly to Reapit customers. If any costs are incorporated into the Developer’s pricing model, the Developer must not present, describe, or otherwise refer to such costs as being related to 'Reapit integration fees,' 'Reapit API fees,' or similar terms that imply direct charges from Reapit;&#x20;

2.2.4 accepts full responsibility for onboarding, negotiating, and managing its customer contracts. Reapit will not be liable for any obligations or disputes arising from these contracts, and all contractual relationships with customers will be attributed to the Developer;&#x20;

2.2.5 bears sole responsibility for integrating its systems with the App Marketplace and any request for technical support or assistance beyond standard documentation will require a separate written agreement and may incur additional Fees.&#x20;

#### 2.3 Working with other developers&#x20;

2.3.1 The Developer may, solely at its own risk, permit other developers to work on an Application on behalf of the Developer, provided that such other developer enters into a developer agreement on the same terms as this Agreement with Reapit.&#x20;

2.3.2 The Developer must not in any manner or by any means:&#x20;

(a) facilitate or permit any third party to access or use Data; or&#x20;

(b) share, sublicense, sell, or otherwise transfer any Data to any third party;&#x20;

outside an Approved Application and the purposes of that Approved Application. &#x20;

2.3.3 All Applications must be owned, managed, and operated solely by the Developer using its approved account. &#x20;

#### 2.4 Application Development-Requirements&#x20;

2.4.1 Each Application must be developed in accordance with:&#x20;

(a) any guidelines published by Reapit from time to time; and &#x20;

(b) Reapit’s “Developer Requirements” as updated and made available to the Developer from time to time;&#x20;

and the relevant Application User Terms must comply with the Application User Terms Principles.&#x20;

2.4.2 The scope of each Application must conform to the permissions requested by the Developer in relation to that Application.&#x20;

2.4.3 The functionality of each Application must correspond to the description provided by the Developer in relation to that Application.&#x20;

2.4.4 Each Application must consume APIs in line with the description of the Application.&#x20;

#### 2.5 Application Approval-First Approval&#x20;

2.5.1 Each Application must be submitted to Reapit for approval:&#x20;

(a) prior to being published on the Reapit Platform; &#x20;

(b) in the case of an Approved Application, after making any changes to its functionality, features, operating model or description.&#x20;

2.5.2 The Developer must submit the relevant Application to Reapit by completing the “Submit the Application” (or equivalent) process within the Platform.&#x20;

2.5.3 Upon receipt of the submission, Reapit will review the Application (which may include, at Reapit’s sole discretion, a full code review) and either:&#x20;

(a) approve the Application outright, in which case Reapit will notify the Developer electronically that the Application is an Approved Application and the Approved Application will be published by Reapit on the App Marketplace in accordance with Reapit’s usual processes; or &#x20;

(b) notify the Developer of any remedial actions or further development work required by Reapit (whether in relation to scope, functionality, or description) before the Application can be resubmitted for approval; or &#x20;

(c) notify the Developer, at Reapit’s sole discretion, that the Application is not approved and that Reapit does not wish to proceed any further with that Application. &#x20;

2.5.4 If Reapit requires remedial work or further development, in accordance with clause 2.5.3(b), the Developer must resubmit the Application in accordance with clause 2.5.2 or as otherwise directed by Reapit and the terms of clause 2.5.3 will apply to any re-submission.&#x20;

2.5.5 For the avoidance of doubt, no Application will be listed by Reapit in the App Marketplace unless it has been explicitly approved by Reapit in writing and such approval will never be deemed. &#x20;

#### 2.6 Reapit’s Right of Approvals and Review-After First Approval&#x20;

2.6.1 Notwithstanding that an Application has been approved by Reapit in accordance with the terms of clause 2.5, Reapit reserves the right to:&#x20;

(a) require that an Approved Application (or any part thereof) be re-submitted for approval in accordance with the terms of clause 2.5.4 if Reapit: &#x20;

(i) reasonably believes that the Approved Application breaches or may breach any term of this Agreement; &#x20;

(ii) wishes to review the scope or permissions of the Approved Application; &#x20;

(iii) wishes to conduct a random spot-check to assess whether the Approved Application complies with its approved scope and permissions; and/or &#x20;

(b) revoke an Approved Application’s approval (in part or in whole and including any scope or permissions previously agreed) and delete its listing from the App Marketplace.&#x20;

2.6.2 Without prejudice to clause 2.6.1, an Application must be re-submitted for approval in accordance with the terms of clause 2.5.4 if there is any change to an Approved Application’s functionality, features, operating model or description.&#x20;

2.7 A breach by the Developer of any term of this clause 2 will be deemed to be a material breach and will entitle Reapit to charge Administration Fees. &#x20;

2.8 For the avoidance of doubt, this Agreement does not restrict Reapit, its affiliates, or its partners from: &#x20;

(a) offering, developing, or promoting products or services that may compete with any Developer Application; or &#x20;

(b) engaging in commercial relationships with other third-party developers, partners, or entities, whether or not they offer similar integrations or products.&#x20;

2.9 The Developer agrees that during the Term of this Agreement and for a period of six (6) months following termination, the Developer must not, directly or indirectly: &#x20;

(a) solicit or attempt to solicit for employment, hire, or otherwise engage any Reapit employees, contractors, or subcontractors; &#x20;

(b) induce or attempt to induce any Reapit employees, contractors, or subcontractors to terminate or alter their business relationship with Reapit.&#x20;

### 3 FEES AND PAYMENT&#x20;

3.1 Reapit will calculate the Fees in accordance with Schedules 2 and 4, and invoice the Fees to the Developer in accordance with this clause 3. The Developer must pay Reapit the Fees. The Fees will not include value added tax or any locally applicable equivalent sales tax, which the Developer must pay in addition to the Fees at the prevailing rate, and in the manner prescribed by applicable law. Without prejudice to the foregoing, Reapit reserves the right to invoice the Developer for any API calls in excess of the Monthly API Call Limit set out in Schedule 2.&#x20;

3.2 Fees will be collected by direct debit in accordance with the Direct Debit mandate that the Developer must complete at the same time as providing the Registration Details.&#x20;

3.3 If the Developer wishes to dispute all or part of an invoice, the Developer must:&#x20;

3.3.1 notify Reapit in writing, within 5 Business Days of receipt of the invoice, such notice to set out the reasons for the dispute; and &#x20;

3.3.2 pay any undisputed part by the due date.&#x20;

3.4 Upon receipt of the notice from Developer pursuant to clause 3.3.1, the Parties must commence discussing the dispute in good faith for a period of 30 days and if the dispute is not resolved at the end of such period, it will be referred to the Dispute Resolution Procedure.&#x20;

3.5 Without prejudice to any other right or remedy Reapit may have, and subject to the terms of clause 3.3, if the Developer fails to pay Reapit the Fees on or before the due date in respect of a valid and undisputed invoice, Reapit may charge interest on such sum from the due date for payment at the annual rate of 5% above the base lending rate from time to time of Barclays Bank accruing on a daily basis until payment is made whether before or after any judgment.&#x20;

3.6 Notwithstanding the foregoing, Reapit reserves the right to vary the Fees (or any element of the Fees, such as the thresholds applicable to the “Number of Endpoints” or “Monthly API Calls” which are used to calculate the Total Consumption Cost), provided that Reapit must notify the Developer 60 days prior to such change taking effect. Following receipt of such notice from Reapit, the Developer has the right to terminate this Agreement by written notice to Reapit, such notice to be received by Reapit no later than 30 days prior the change taking effect. &#x20;

3.7 The Developer must pay the Minimum Guarantee in respect of each Approved Application as set out in Schedule 2.&#x20;

3.8 Reapit reserves the right, upon 14 days’ notice, to audit the Developer’s compliance with this Agreement, including: &#x20;

(a) verification of API usage and fees; &#x20;

(b) review of data handling, retention, and protection practices; &#x20;

(c) confirmation that the Developer’s Applications comply with approved permissions and usage policies. &#x20;

The Developer must provide Reapit or its auditors with reasonable access to its premises, systems, records, and personnel for such purposes. Where discrepancies are identified, the Developer must immediately rectify non-compliance and reimburse Reapit for any underpaid amounts or losses incurred.&#x20;

### 4 INTELLECTUAL PROPERTY RIGHTS AND INDEMNITY&#x20;

4.1 All Intellectual Property Rights belonging to a Party prior to the Commencement Date, including all enhancements and modifications to those Intellectual Property Rights, will remain vested in that Party. Unless expressly agreed in writing in an Order Form, the Parties do not intend that the ownership of any Intellectual Property Rights will transfer from one Party to another as a result of entering into this Agreement.&#x20;

4.2 The Developer hereby grants Reapit&#x20;

an exclusive, worldwide, royalty-free licence for the Term to make all Approved Applications available for sale, download and use on the App Marketplace. &#x20;

#### 4.3 Developer Edition Licence&#x20;

4.3.1 Reapit grants the Developer a Developer Edition Licence.&#x20;

4.3.2 Except as expressly permitted by this Agreement or authorised in writing by Reapit, the Developer must not (and must not permit others to) use, copy, modify, or otherwise translate or convert, create derivative works from, decode, reverse engineer, disassemble, decompile or otherwise translate or convert, sub-licence or distribute the Developer Edition, any part of it, or any copy, adaptation, transcription, or merged portion of it, except to the extent permitted by Applicable Law.&#x20;

4.3.3 The licence granted in clause 4.3.1 will terminate automatically on the earlier of:&#x20;

(a) termination of this Agreement; &#x20;

(b) breach by the Developer of clause 4.3.2; &#x20;

(c) written cancellation by either party of the Developer Edition Licence.&#x20;

4.4 Subject to clause 4.2, no Intellectual Property Rights in or to either Party’s trade marks or brands will be used by the other Party for any purpose without the other Party’s prior written consent. If that consent is given, the relevant Party must use the relevant trade marks or brands only in compliance with the consenting Party’s brand guidelines and in accordance with the terms and conditions of the relevant trade mark licence between the Parties (if any). The Developer agrees not to represent itself as an authorised partner or affiliate of Reapit without Reapit’s written consent.&#x20;

#### **IPR Indemnity**&#x20;

4.5 The Developer agrees to indemnify and hold harmless Reapit on demand for all Loss incurred by Reapit in connection with any claim or action against Reapit by any Third Party which alleges that the exercise by Reapit of its rights pursuant to this Agreement infringes either (i) the Intellectual Property Rights, other than patents, of that Third Party or (ii) any United Kingdom patent of that Third Party existing as at the Commencement Date (**Developer IPR Claim**) and to take all steps necessary to defend or settle any Developer IPR Claim.&#x20;

4.6 If any Developer IPR Claim is made against Reapit which results in Reapit being prevented from exercising its rights pursuant to this Agreement, the Developer must at its cost and expense either:&#x20;

4.6.1 obtain for Reapit the right to continue exercising its rights in the manner permitted under this Agreement; or&#x20;

4.6.2 modify or replace the infringing part of the relevant Application or other subject of the Developer IPR Claim so as to avoid the infringement or alleged infringement.&#x20;

#### Conduct of Developer IPR Claim&#x20;

4.7 The Parties agree that in respect of any Developer IPR Claim:&#x20;

4.7.1 Reapit must notify Developer promptly in writing of any Developer IPR Claim of which Reapit has notice (and in any event within 2 Business Days);&#x20;

4.7.2 the Developer will by written notice to Reapit assume exclusive conduct of the Developer IPR Claim (which will include the exclusive right to conduct any proceedings or action, negotiate the settlement of the Developer IPR Claim and conduct all discussions and dispute resolution efforts in connection with the Developer IPR Claim);&#x20;

4.7.3 Reapit must not admit any liability or agree to any settlement or compromise of the Developer IPR Claim without the prior written consent of the Developer; and&#x20;

4.7.4 Reapit must (at the Developer’s request, cost and expense) give the Developer all required assistance in connection with the conduct of the Developer IPR Claim including access to personnel and provision of documents.&#x20;

### 5 DEVELOPER FEEDBACK&#x20;

5.1 The Developer grants Reapit a worldwide, perpetual, royalty-free, irrevocable, non-exclusive, fully sublicensable licence to use edit, reproduce, modify and adapt any Developer Feedback in any form, medium, or technology now known or later developed for the purposes of:&#x20;

5.1.1 operating the Platform;&#x20;

5.1.2 enabling the further development of the Platform’s functionality;&#x20;

5.1.3 ensuring that an Application is integrated with the Reapit Software;&#x20;

5.1.4 ensuring that an Application can be published on the App Marketplace; and&#x20;

5.1.5 for any purpose, commercial or otherwise.&#x20;

### 6 DATA AND DATA PROTECTION&#x20;

**6.1 Data**&#x20;

6.1.1 Data which the Developer accesses in connection with an Application and/or the App Marketplace is accessed at the Developer’s sole risk, and Reapit is not liable for all or any part of that Data.&#x20;

6.1.2 Without prejudice to the generality of clause 6.1.1, the Developer acknowledges that Data may not be provided or updated in real-time and that Reapit is not liable for the accuracy, completeness or ownership of all or any part of the Data. &#x20;

6.1.3 The Developer represents and warrants that:&#x20;

(a) it has the unqualified permission, licence and/or right (as applicable) to make Data available to other users of the Platform and any applications listed on the Application Marketplace;&#x20;

(b) it will not use or permit the use of any Data for any purpose other than the development, testing and operation of an Application; &#x20;

(c)  it will not use or permit the use of any Data in infringement of a Third Party’s Intellectual Property Rights or other proprietary rights.&#x20;

6.1.4 The Developer’s rights to use Data and/or to make Data available via an Application will cease:&#x20;

(a) upon termination of this Agreement; &#x20;

(b) in respect of an individual end-user, when an App is uninstalled by that end-user.&#x20;

6.1.5 Without prejudice to the foregoing clauses, Reapit reserves the right to suspend the Developer’s access to Data at any time. &#x20;

#### 6.2 Data Protection&#x20;

6.2.1 Each Party must comply (and the Developer must ensure that ends-users of its Applications must comply) with the provisions imposed on them by the Data Protection Laws, including in relation to:&#x20;

(a) the use of Personal Data in an Application; &#x20;

(b) the collection of Personal Data by or on behalf of the Developer for use in an Application; &#x20;

(c) the addition of Personal Data to Data; &#x20;

(d) the transfer of Personal Data to Reapit; and/or &#x20;

(e) the making available of Personal Data to an end-user of an Application.&#x20;

6.2.2 Each Party must maintain records of all processing operations relating to this Agreement under its responsibility that contain at least the minimum information required by the Data Protection Laws and must make such information available to the applicable Regulator on request.&#x20;

6.2.3 If either Party receives any complaint, notice or communication which relates directly or indirectly to the processing of Personal Data by the other Party or to either Party's compliance with the Data Protection Laws, it must promptly notify the other Party and it must provide the other Party with reasonable co-operation and assistance in relation to any such complaint, notice or communication.&#x20;

6.2.4 The Developer will indemnify and hold harmless Reapit on demand for any Loss incurred by Reapit which arises out of or relates to a breach by the Developer (or any third party acting on the Developer’s behalf) of Data Protection Laws. &#x20;

6.2.5 - The Developer acknowledges and agrees that, under applicable Data Protection Laws, it may act as a data processor or data controller. The Developer must comply with all obligations under Data Protection Laws applicable to processors, including implementing appropriate technical and organisational measures to ensure the security, integrity and confidentiality of personal data.&#x20;

6.2.6 Without prejudice to the generality of clause 6.2.5, the Developer must ensure that: &#x20;

(a) all Data accessed via the API is encrypted both in transit and at rest; &#x20;

(b) up-to-date industry-standard security policies, including incident response and breach notification processes, are in place and a qualified security manager appointed to oversee compliance; &#x20;

(c) Developer systems used for API access are maintained with up-to-date security patches and monitoring; &#x20;

(d) only authorised users and personnel have access to customer data, with access appropriately logged and reviewed, and secure user access controls are implemented, and operating systems regularly updated to ensure ongoing protection; &#x20;

(e) incident response procedures, including breach notification protocols, are established and maintained and Reapit is notified immediately in the event of any security breach or unauthorised access affecting any Data.&#x20;

6.2.7 The Developer acknowledges and agrees that Reapit will act only as a data processor in connection with this Agreement.&#x20;

### 7 CONFIDENTIALITY&#x20;

7.1 Each Party (a Recipient) undertakes to the other Party (each, a **Disclosing Party**) to treat as confidential all information, whether commercial, financial, technical or otherwise, in any medium or format, which the Recipient receives from the Disclosing Party, either directly or from any other person, which concerns the business, operations, Developers or suppliers of the Disclosing Party (**Confidential Information**). The terms and conditions of this Agreement  constitute Confidential Information of each Party.&#x20;

7.2 The Recipient may use the Confidential Information only in accordance with this Agreement and must treat the Confidential Information with the same standard of care that it holds its own Confidential Information. The Recipient may provide its Staff and professional advisers (**Permitted Users**) with access to the Confidential Information to the extent reasonably necessary in order for Recipient to perform or receive the Services only. The Recipient must ensure that each of its Permitted Users is bound to hold all Confidential Information in confidence to the standard required under this Agreement. Where a Permitted User is not a member of the Recipient’s Staff (and is not under a professional duty to protect confidentiality), the Recipient must ensure that the Permitted User will be subject to the same duty of care as the Recipient is under the terms to this Agreement,&#x20;

7.3 This clause 7 will not apply to any information which:&#x20;

7.3.1 is in or subsequently enters the public domain other than as a result of a breach of this clause 7;&#x20;

7.3.2 has been or is subsequently received by the Recipient from a Third Party which is under no confidentiality obligation in respect of that information;&#x20;

7.3.3 has been or is subsequently independently developed by the Recipient without use of the Disclosing Party’s Confidential Information; or&#x20;

7.3.4 was previously known to the Recipient free of any obligation to keep it confidential.&#x20;

7.4 Each Permitted User may disclose Confidential Information where that Permitted User (or, where the Permitted User is an individual, his or her employer) is required to do so by law or by any competent regulatory authority. In these circumstances the Recipient must give the Disclosing Party prompt advance written notice of the disclosure (where lawful and practical to do so) so that the Disclosing Party has sufficient opportunity (where possible) to prevent or control the manner of disclosure by appropriate legal means.&#x20;

7.5 This clause 7 will remain in full force and effect notwithstanding any termination of this Agreement. Upon termination or expiration of this Agreement: &#x20;

(a) the Developer must immediately cease use of any Reapit Confidential Information or Data; &#x20;

(b) All Reapit Data stored within the Developer’s systems must be securely and irretrievably deleted within 30 days of termination (and the Developer must provide written certification of such deletion upon Reapit's request).&#x20;

### 8 REPRESENTATIONS, WARRANTIES AND UNDERTAKINGS&#x20;

8.1 Each Party represents and warrants to the other Party that:&#x20;

8.1.1 it has the power to execute and deliver this Agreement and to perform its obligations under it and has taken all action necessary to authorise execution and delivery and the performance of its obligations;&#x20;

8.1.2 all authorisations, licences or consents from, and notices or filings with, any relevant Regulator or other governmental or other authority that are necessary to enable it to execute, deliver and perform its obligations under this Agreement have been obtained or made (as the case may be) and are in full force and effect and all conditions of each authorisation, licence, consent, notice or filing have been complied with.&#x20;

8.2 In addition:&#x20;

8.2.1 the Developer warrants that:&#x20;

(a) nothing will be inserted or entered into the Application which is intended by any person to impair the operation of the Application or the Reapit Software; and &#x20;

(b) the Application will operate in accordance with any documented functionality in all material respects.&#x20;

8.3 Reapit expressly disclaims any warranty as to the operation of the Developer Edition:&#x20;

8.3.1 being error-free or uninterrupted; or&#x20;

8.3.2 complying with any specifications; or&#x20;

8.3.3 being fit for any specific purpose. &#x20;

8.4 Save as provided in this Agreement, no representations, warranties or other terms, express or implied, statutory or otherwise, as to condition, quality, performance, or fitness for purpose are given or assumed by Reapit in respect of the Services, and all those representations, warranties and terms are excluded save to the extent that any exclusion is prohibited by law.&#x20;

### 9 FORCE MAJEURE&#x20;

9.1 Subject to clause 10.1, neither Party will be liable to the other Party for any delay or non-performance of its obligations under this Agreement arising directly from a Force Majeure Event, provided that the affected Party:&#x20;

9.1.1 promptly notifies the other Party in writing of the cause of the delay or non-performance and the likely duration of the delay or non-performance; and&#x20;

9.1.2 uses reasonable endeavours to limit the effect of that delay or non-performance on the other Party.&#x20;

9.2 In any such case, the performance of the affected Party’s obligations, to the extent affected by the cause, will be suspended during the period that the cause persists.&#x20;

9.3 If a Force Majeure Event occurs and Reapit has not restored full and uninterrupted Services within 72 hours, Developer will not be required to pay, and Reapit will not be entitled to charge, for Services affected by that Force Majeure Event for the duration of the period commencing on the date the Force Majeure Event occurred and ending on the date full and uninterrupted Services are resumed.&#x20;

### 10 LIMITATION OF LIABILITY&#x20;

10.1 Nothing in this Agreement excludes or limits either Party’s liability:&#x20;

10.1.1 for fraud by it or its Staff; or&#x20;

10.1.2 for death or personal injury caused by its negligence or that of its Staff; or&#x20;

10.1.3 to the extent that any Applicable Laws and Regulations precludes or prohibits any exclusion or limitation of liability.&#x20;

10.2 Subject to clauses 10.1 and 10.4, Reapit’s total aggregate liability to the Developer in any single Contract Year arising from breach of contract, negligence, or under any indemnity, or otherwise under or in connection with this Agreement will not exceed 100% of the Fees paid and payable by the Developer in the 6 months preceding the event giving rise to the liability.&#x20;

10.3 Subject to clauses 10.1, 10.2 and 10.4, neither Party will be liable to the other Party for any Consequential Loss in connection with this Agreement however caused (including through negligence).&#x20;

10.4 The following types of Loss will not be subject to the exclusions set out in clause 10.3:&#x20;

10.4.1 the termination of or failure to renewal any contract with Reapit by any customer of Reapit as a result of or related to their use of an Application which is defective;&#x20;

10.4.2 the unauthorised use of Data or any other data submitted by an end-user of an Application by or on behalf of the Developer; and&#x20;

10.4.3 any Loss arising out of or related to a breach by the Developer of clauses 2.2, 2.3 and/or 2.4.&#x20;

10.5 Without prejudice to the terms of clause 10.3, Reapit will not be liable (whether in negligence or under any other rule of law or equity) for any Loss arising out of or related to:&#x20;

10.5.1 the use or deployment of the Application by or on behalf of the Developer;&#x20;

10.5.2 the use of Data by the Developer;&#x20;

10.5.3 the use of the Developer Edition (other than any Loss arising directly out of Reapit’s negligence);&#x20;

10.5.4 the use of other Developer tooling provided by Reapit (e.g. Reapit Connect, Reapit Elements, any open-source code);&#x20;

10.5.5 the accuracy, completeness or ownership of the Data;&#x20;

10.5.6 the Developer’s use of any feature which is part of the Platform; and/or&#x20;

10.5.7 any claim made by an end-user of an Application against the Developer or against Reapit; and/or&#x20;

10.5.8 any Loss incurred by the Developer as a result of or related to an act or an omission of a co-developer in relation to an Application. &#x20;

10.6 The Developer agrees to indemnify and hold harmless Reapit on demand for any Loss incurred by Reapit as a result of or arising out of any claims made by an end-user of an Application, where such claim relates to or arises out of that end-user’s use of an Application. &#x20;

10.7 Nothing in this clause 10 will in any way reduce or affect each Party’s general duty to mitigate loss suffered by it.&#x20;

10.8 The Parties agree that they have negotiated this clause 10 and that it represents a fair and equitable position.&#x20;

### 11 TERM AND TERMINATION&#x20;

11.1 The Agreement comes into effect on the Commencement Date and, subject to early termination in accordance with the terms of clause 11.3, will continue to be in force until the expiry of the Initial Term. Once the Developer achieves a cumulative total of 40 agent company installations, both Parties agree to enter into good faith negotiations to review and, if necessary, renegotiate the commercial terms of this Agreement. Such renegotiation may include adjustments to revenue shares, commission rates, or other financial terms. &#x20;

11.2 Upon expiry of the Initial Term and on each anniversary of the Commencement Date, the Agreement will automatically renew for a subsequent Contract Year, subject to:&#x20;

11.2.1 early termination in accordance with the terms of clause 11.3; and&#x20;

11.2.2 a Party giving at least 1 month’s written notice to the other Party not to renew the Agreement, save that:&#x20;

(a) the Developer’s right to give such notice is subject to the Developer having paid all invoiced and non-disputed amounts on the date the notice is given; and&#x20;

(b) the notice cannot take effect before expiry of the Initial Term.&#x20;

11.3 This Agreement may be terminated:&#x20;

11.3.1 by Reapit on immediate written notice if the Developer: &#x20;

(a) fails to pay an undisputed, invoiced amount within 30 days following receipt of an initial written notice from Reapit stating that the amount is due and is unpaid; or&#x20;

(b) breaches a Developer Obligation; or&#x20;

(c) commits any other material breach of this Agreement which (in the case of a breach capable of being remedied) is not remedied within 7 days of notice of the breach; or &#x20;

(d) undergoes a change of control (and the Developer must notify Reapit in writing within 14 days of any such change of control);&#x20;

11.3.2 by written notice from the Developer if Reapit commits a material breach of this Agreement and which (in the case of a breach capable of being remedied) has not been remedied within 30 days of a written notice of the breach (setting out the specific breaches and suggested steps to remedy the breach, if applicable);&#x20;

11.3.3 by immediate written notice from either Party if the other Party is subject to an Insolvency Event.&#x20;

11.4 Any termination of this Agreement pursuant to this clause will be without prejudice to any other rights or remedies a Party may be entitled to hereunder or at law and will not affect any accrued rights or liabilities of either Party nor the coming into or continuance in force of any provision hereof which is expressly or by implication intended to come into or continue in force on or after such termination.&#x20;

### 12 CONSEQUENCES OF TERMINATION&#x20;

12.1 The following clauses will survive termination or expiry of this Agreement: 3, 4, 5, 6, 7, 10, 12, 13, 15 and 16.&#x20;

12.2 Upon termination or expiry of this Agreement: &#x20;

(a) the licence granted by the Developer in clause 4.2.1 will terminate automatically and Reapit must cease using, and permitting the use of, and marketing the Application(s) from the effective date of termination or expiry; &#x20;

(b) by the Developer pursuant to clause 11.3.2, Reapit must refund the Developer on a pro-rata basis any pre-paid Fees that apply from the period starting on the effective date of termination until the date that applied to the pre-paid Fees;&#x20;

(c) on termination of this Agreement, the Developer must continue to pay referral fees for the duration of existing customer contracts signed before termination. This obligation will survive the termination or expiry of the Agreement.&#x20;

12.3 Termination of this Agreement in accordance with its terms will not relieve the Developer of its payment obligations and all sums that would otherwise be due from the Developer to Reapit under this Agreement will be payable on the date that they would otherwise become due and the number of Users applicable to any termination notice period (whether early termination in accordance with the terms of clause 11.3 or a notice to prevent automatic renewal in accordance with clause 11.2.2) will be deemed to be the number of Users as at the date the applicable termination notice is sent.&#x20;

### 13 NOTICES&#x20;

13.1 Any notice request instruction or other document to be given under this Agreement must be in writing and will be deemed to have been duly given if left at or sent by hand or by registered post or by e-mail to (i) a Party at its registered company address in England; or (ii) e-mail address set out below for such Party or such other address as one Party may from time to time designate by written notice to the other.&#x20;

13.2 Any such notice, request, instruction or other document will be deemed to have been received by the addressee two Business Days following the date of dispatch if the notice or other document is sent by registered post, or simultaneously with the delivery or transmission if sent by hand or if given by e-mail or other electronic means.&#x20;

13.3 Notwithstanding the provisions above, a copy of any written notice sent by the Developer to Reapit must be sent by e-mail to Reapit at the e-mail to the address below:&#x20;

13.3.1 Notices to Reapit:&#x20;

(a) Address: 67 – 74 Saffron Hill, London, EC1N 8QX; and &#x20;

(b) e-mail address: <reapitcontracts@reapit.com>.&#x20;

13.3.2 Notices to the Developer must be sent to the e-mail address submitted by the Developer as part of the Registration Details.&#x20;

### 14 MISCELLANEOUS&#x20;

14.1 **Announcements**: Each Party must not:&#x20;

14.1.1 make or authorise any public or private announcement or communication concerning this Agreement; or&#x20;

14.1.2 refer to or use any business name or trade mark of the other Party in any promotional communications,&#x20;

without the prior written consent of the other Party.&#x20;

14.2 **Further Assurance**: Each Party must, at its own cost, promptly execute and deliver all such documents, and do all such things, as the other Party may from time to time reasonably require for the purpose of giving full effect to the provisions of this Agreement and to secure for the other Party the full benefit of the rights, powers and remedies conferred upon it under this Agreement.&#x20;

14.3 **Entire Agreement**:&#x20;

14.3.1 The Agreement sets out the entire agreement between the Parties relating to its subject matter and, save to the extent expressly set out in this Agreement, supersede and extinguish any prior drafts, agreements, undertakings, representations, warranties, promises, assurances and arrangements of any nature whatsoever, whether or not in writing, relating thereto.&#x20;

14.3.2 Neither Party has entered into this Agreement in reliance upon (and neither Party will have any claim or remedy in respect of) any statement, representation, warranty, undertaking, assurance, promise, understanding or other provision made by or on behalf of the other Party, any of its representatives or any other person which is not expressly set out in this Agreement.&#x20;

14.3.3 This clause 14.3 (Entire Agreement) will not exclude any liability for or remedy in respect of fraudulent misrepresentation.&#x20;

14.4 **Waiver and Variation:**&#x20;

14.4.1 A failure or delay by a Party to exercise any right or remedy provided under this Agreement or by Law, whether by conduct or otherwise, will not constitute a waiver of that or any other right or remedy, nor will it preclude or restrict any further exercise of that or any other right or remedy. No single or partial exercise of any right or remedy provided under this Agreement or by Law, whether by conduct or otherwise, will preclude or restrict the further exercise of that or any other right or remedy.&#x20;

14.4.2 A waiver of any right or remedy under this Agreement will only be effective if given in writing and will not be deemed a waiver of any subsequent breach or default. A Party that waives a right or remedy provided under this Agreement or by Law in relation to another Party does not affect its rights in relation to any other Party.&#x20;

14.4.3 Reapit reserves the right to amend this Agreement at any time by notice to the Developer. Upon receipt of a notice of variation, the Developer will have the right to terminate his Agreement for a period of 10 Business Days, after which the applicable variations will be deemed to have been accepted by the Developer. &#x20;

14.5 Invalidity: Where any provision of this Agreement is or becomes illegal, invalid or unenforceable in any respect under the Applicable Law of any jurisdiction then such provision will be deemed to be severed from this Agreement and, if possible, replaced with a lawful provision which, as closely as possible, gives effect to the intention of the Parties and, where permissible, that will not affect or impair the legality, validity or enforceability in that, or any other, jurisdiction of any other provision of this Agreement.&#x20;

14.6 **Assignment:**&#x20;

14.6.1 The Developer must not assign, transfer, mortgage, charge, declare a trust over or deal in any other manner with any or all of its rights and obligations under this Agreement without Reapit’s prior written consent.&#x20;

14.6.2 Reapit will be entitled, after having given prior written notice to the Developer, to:&#x20;

(a) assign its rights under this Agreement to any person to which it transfers that part of its business to which this Agreement relates; or &#x20;

(b) assign or novate this Agreement to a purchaser of the whole or substantially the whole of the business of Reapit.&#x20;

14.7 **No Partnership or Agency**: Nothing in this Agreement is intended to, or will be deemed to, establish any partnership or joint venture between any of the Parties, constitute any Party the agent of another Party, or authorise any Party to make or enter into any commitments for or on behalf of any other Party.&#x20;

14.8 **Third Party Rights**: A person who is not a Party to this Agreement may not enforce any of its terms under the Contracts (Rights of Third Parties) Act 1999.&#x20;

14.9 **Costs**: Except as otherwise provided in this Agreement, each Party must bear its own costs arising out of or in connection with the preparation, negotiation and implementation of this Agreement.&#x20;

14.10 **Counterparts**: This Agreement may be executed in any number of counterparts. Each counterpart will constitute an original of this Agreement, but all the counterparts together will constitute but one and the same instrument.&#x20;

### 15 DISPUTES&#x20;

15.1 Any Dispute must be referred for resolution by each Party’s Key Contact.&#x20;

15.2 If the Dispute cannot be resolved by the persons referred to in clause 15.1 within 5 Business Days after the Dispute has arisen, either Party may give written notice to the other Party that a Dispute has arisen (Dispute Notice). Within 3 Business Days after receipt of the Dispute Notice, the Dispute must be referred to each Party’s Chief Executive Officer (or nominated representative) for resolution. If the Dispute is not resolved by agreement in writing between the Parties within 21 days of receipt of the Dispute Notice, the Dispute must be resolved in accordance with the remaining provisions of this clause 15.&#x20;

15.3 Either Party may refer the Dispute for final resolution by arbitration under the LCIA (London Court of International Arbitration) Rules, which Rules are deemed to be incorporated by reference into this clause 15. The number of arbitrators will be 3 (**Tribunal**). Each of the Parties will appoint one arbitrator. The 2 arbitrators so appointed will choose the third arbitrator who will act as the Chairman of the Tribunal. The seat, or legal place, of arbitration will be London, United Kingdom. The language to be used in the arbitral proceedings will be English.&#x20;

15.4 This clause 15 is without prejudice to either Party’s right to seek interim relief against the other Party (such as an injunction) through the English courts to protect its rights and interests, or to enforce the obligations of the other Party.&#x20;

### 16 GOVERNING LAW AND JURISDICTION&#x20;

16.1 This Agreement will be governed by, construed and interpreted in accordance with English law and the Parties hereby agree, for the purposes of this Agreement only and subject to the provisions of clause 15, to submit themselves and any claim or matter arising under or in connection with this Agreement to the exclusive jurisdiction of the English courts. &#x20;

&#x20;

### SCHEDULE 1 – APPLICATION USER TERMS PRINCIPLES&#x20;

**1** **GENERAL**&#x20;

1.1 The Developer must not include any terms in the Application User Terms, which conflict with the Developer’s obligations pursuant to this Agreement.&#x20;

1.2 The Developer must ensure that the Application:&#x20;

1.2.1 should access only the minimum data fields which that Application needs to work properly; and&#x20;

1.2.2 ensure any data is collected, processed, transmitted, maintained and used in accordance with the Application User Terms, all applicable laws and reasonable measures that protect the privacy and security of the relevant end user (including at a minimum those set out below at Paragraph 2).&#x20;

1.3 Without prejudice to the foregoing, the Application User Terms must contain clear and legally adequate disclosures about the nature of the Application’s integration with the Reapit Software (and any other software) and the User Data collected by the Application, as well as the Developer’s intended use of it.&#x20;

1.4 The Application User Terms should include a clear statement that the Application has not been developed by Reapit and that Reapit bears no responsibility or liability for the Application and does not warrant that it does (or will in the future) function and integrate with the Reapit Software.&#x20;

1.5 The Developer acknowledges that certain functionalities of the Reapit Platform may depend on third-party services or components ("Third-Party Components"). Reapit reserves the right to update or replace these components without prior notice. Reapit will not be liable for any direct or indirect losses caused by changes, outages, or discontinuation of such Third-Party Components.&#x20;

### 2 DATA PROTECTION&#x20;

2.1  The Application User Terms must comply fully with Data Protection Laws.&#x20;

2.2 Without prejudice to the generality of the paragraph 2.1, the Developer must clearly notify the end users of the relevant Application as to:&#x20;

2.2.1 the types of personal data collected or processed by the Developer and the intended processing purposes of that personal data;&#x20;

2.2.2 where such Personal Data is stored (identity and location of entity maintaining the relevant database); and&#x20;

2.2.3 whether any third parties are involved as sub-processors of the Personal Data. &#x20;

&#x20;

### SCHEDULE 2 – FEES

1\. External Developer Fees

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FMGVj50k2tgJyqeKUlQXC%2FScreenshot%202025-11-25%20at%2014.09.36.png?alt=media&amp;token=ed3ef67a-43b6-4301-813e-3932735ffc1a" alt=""><figcaption></figcaption></figure>

**External Developer Minimum Guarantee**&#x20;

The External Developer must ensure that its total monthly consumption cost for each of its Approved Applications is at least £200.00 per month. Where the Developer fails to meet this minimum in respect of any Approved Application, the Developer must pay (and Reapit will invoice) the balance of this minimum, in addition to all other applicable Fees.

Example calculation of total monthly API consumption cost for an External Developer as representative purpose only:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FC6ZUdMnE5aUtJEFkAvky%2FScreenshot%202025-11-25%20at%2014.12.36.png?alt=media&amp;token=32c75df7-1f2e-439e-8785-39f69122bcca" alt=""><figcaption></figcaption></figure>

2\. Customer Developer Fees

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FAXL6YsKv1uacZ869pPNP%2FScreenshot%202025-11-25%20at%2014.14.18.png?alt=media&amp;token=c3646232-4acb-4b67-945d-b051dc6159b2" alt=""><figcaption></figcaption></figure>

Example calculation of total monthly API consumption cost for a Customer Developer as representative purpose only:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FKocfOvbYL4I0BBoIuPAh%2FScreenshot%202025-11-25%20at%2014.14.40.png?alt=media&amp;token=d9c21c33-5dc6-4900-b997-814c8c36c8df" alt=""><figcaption></figcaption></figure>

### **SCHEDULE 3 - DEVELOPER OBLIGATIONS**&#x20;

1\. The Developer agrees that:&#x20;

* access to the Platform is solely for the purpose of developing Applications and/or accessing Reapit’s Application Programming Interfaces;&#x20;
* it will not interfere with or access any other developer’s Application, without that developer and Reapit’s express prior written permission;&#x20;
* it will not interfere with or disrupt the Platform, or any services or network used to provide access to the Platform;&#x20;
* it will not collect any data or Personal Data on the Platform, other than through its Application and in accordance with the Application User Terms Principles;&#x20;
* it will not re-identify (or seek to re-identify) any anonymised data;&#x20;
* it will provide feedback when requested by Reapit, in relation to the performance of the Platform;&#x20;
* it will co-operate in all matters relating to this Agreement with Reapit;&#x20;
* it will not provide access to the Platform to anyone who has not entered into a direct agreement with Reapit on the same terms as this Agreement and, without prejudice to the foregoing, it will not share (i) any API access credentials provided by Reapit and/or (ii) the Registration Details with any third party;&#x20;
* it will conduct an industry-standard penetration test on each Application at least once every calendar year and provide Reapit with the results of such test;&#x20;
* it will not use the Platform in a manner, develop an Application, or share any content or Developer Feedback, that (in Reapit’s reasonable opinion): \
  \
  \- is false or misleading; \
  \- is defamatory, derogatory, degrading or harassing of another or constitutes a personal attack; \
  \- invades another’s privacy or includes, copies or transmits another’s confidential, sensitive or personal information;\
  \- promotes bigotry, racism, hatred or harm against any group or individual; \
  \- is obscene or not in good taste; \
  \- infringes or promotes the infringement of a Third Party’s rights, including Intellectual Property Rights; \
  \- promotes the infringement of any Applicable Laws; \
  \- contains a solicitation of funds, goods or services, or promotes or advertises goods or services (other than the Application itself); or \
  \- contains any viruses, Trojan horses, or other components designed to limit or harm the functionality of a computer.&#x20;

2\. The Developer must make available upon request access to the Application in both test and production environments for Reapit to conduct random spot-checks.&#x20;

3\. When reading Data from end points the Developer must update those end points and write back associated Data, including the “Negotiators diary” in order to ensure that the Platform remains the Single source of truth for the benefit of all Marketplace Applications&#x20;

4\. Server Side Applications that are not a companion to a Client Side Application listed on the Marketplace must use Reapit Connect in their non-Marketplace application(s).&#x20;

5\. The Developer must use Reapit Connect and Reapit Elements UI component library when building Client Side Applications for the Marketplace.&#x20;

6\. The Developer must not exceed or circumvent (or seek to circumvent) the Monthly API Call Limit as updated and communicated by Reapit from time to time and the Developer is solely responsible for ensuring that it keeps track of its current consumption of Monthly API Calls.&#x20;

7\. The developer must not exceed, the API call request either on monthly per second or concurrent request basis. For clarification, please refer to API documentation or contact a member of the partner team.&#x20;

8\. The Developer must maintain no more than 5 API interaction threads in respect of any one Approved Application and must await completion of one or more previous requests before submitting new ones.&#x20;

### SCHEDULE 4 – ADMINISTRATION FEES AND INTEREST&#x20;

In the following events, the Developer must pay Reapit on demand the following Administration Fees by way of liquidated damages for all loss and damage caused. The parties agree and acknowledge that these liquidated damages are reasonable and proportionate to cover the costs of dealing with the following events and to protect Reapit’s legitimate interest in its Intellectual Property Rights and the App Marketplace.&#x20;

1. Breach of approval process - £595&#x20;
2. Breach of support ticket process\
   (i)   Selecting wrong impact level - Initial incident £50 thereafter £200 \
   (ii)  Incorrectly describing the incident - Initial incident £50 thereafter £200 \
   (iii) Inflating the number of clients/agents affected - Initial incident £50 thereafter £200&#x20;
3. Interest on late payment of Fees - As outlined in this agreement regarding interest at 5% above the bank of England rate, all Fees not paid within 30 days will be subject to the same interest adjustment.&#x20;
4. Termination for repeat breaches- Developers that are found to persistently breach the rules of this Agreement and incur Administration Fees (even if paid) may be subject to Reapit terminating this Agreement.&#x20;

<br>

<br>


# Troubleshooting

This Troubleshooting guide is intended to provide guidance to our Developers when building apps and integrations through the Developer Portal. We will continue to refine and provide additional guidance where applicable.

We have also included a FAQ section, which can be found [here](/faqs).

If you are having an issue not covered in the documentation or you have discovered a bug, please raise an issue on our public board by clicking [here](https://github.com/reapit/foundations/issues/new?assignees=\&labels=bug%2C+needs-triage\&template=bug_report.md\&title=).

Please select from the topics below:&#x20;

{% content-ref url="/pages/-MeyvppPHry2pB9SbaMd" %}
[Accessing Customer Data](/troubleshooting/accessing-customer-data)
{% endcontent-ref %}

{% content-ref url="/pages/-MeyveCI5zAmxZCN2PNi" %}
[Authentication Issues](/troubleshooting/authentication-issues)
{% endcontent-ref %}

{% content-ref url="/pages/-Meyza4RwwlzcmZG5A7b" %}
[REST API](/troubleshooting/platform-api)
{% endcontent-ref %}

{% content-ref url="/pages/-MeywQEhdrcujjQ42tOm" %}
[Reapit Connect](/troubleshooting/reapit-connect)
{% endcontent-ref %}


# Accessing Customer Data

### **Error:** “The request could not be fulfilled as the reapit customer specified by the provided credentials does not have the application installed”

### **Error:** “Unauthorized: 401 Unauthorized”

When making a request to our Platform API’s using the Client Credentials Flow and you receive the above error, it maybe related to the incorrect Client ID you have provided in your ‘reapit-customer’ header.

How to verify the Customer ID:

* Ask the agent to confirm their Customer ID – click [here ](/faqs#how-do-i-find-a-customer-id)for more information on how to obtain the Customer ID
* View the [email ](/faqs#installation)notification you received when the app was installed&#x20;
* View the [installations ](/faqs#installations-table)table on your app listing
* If you had setup a [webhook ](/faqs#webhooks)for application.install, the payload will have included the ‘customerId’

or&#x20;

The Reapit Customer ID you have provided in your ‘reapit-customer’ header has not yet installed your application from the AppMarket. The installation process is the step that grants you access to live data (not Sandbox).

If you are a Reapit Agent looking to interact with your own data, you will still need to list (privately) and install your own app.

For more information on how to list your app in the AppMarket, please click [here](https://foundations-documentation.reapit.cloud/listing-your-app)


# Authentication Issues

## **Client Credentials Flow -** Authentication Issues

### **Error: "invalid\_client"**

* Check you have provided the correct ‘Client ID’ in your request payload using the header ‘client\_id’. Your Client ID is available on your app listing in the [Developer Portal](https://developers.reapit.cloud/apps)
* It’s possible that the ‘Authorization’ base64 secret you have provided maybe invalid.
* Ensure you have provided the encoded version as the value for the Authorization header set to ‘Basic’ (Basic XBASE64SECRETX)

For more information on Authentication (using the Client Credentials Flow), please click [here](https://foundations-documentation.reapit.cloud/api/api-documentation#client-credentials-flow)

Screenshot showing how to find your ‘Client ID’ and ‘Secret’ on your App listing:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FW69ND2SwQzgc6siEEOhb%2FAuthError.jpg?alt=media&amp;token=8bb4f7e7-a33a-4045-aa5b-294d51973556" alt=""><figcaption></figcaption></figure>

### **Error:** "invalid\_request"

* Check you have provided the following values and headings:\
  \
  grant\_type=client\_credentials\
  client\_id=XCLIENTIDX\
  Authorization: Basic XBASE64SECRETX\
  content-type: application/x-www-form-urlencoded

### **Example POST Request (**&#x6F;nly applies to client\_credentials flow)

You can use the example `POST` request to obtain an access token, simply replace XCLIENTIDX with your client ID and XBASE64SECRETX with your encoded Client ID and Secret:

```
curl --request POST \
  --url 'https://connect.reapit.cloud/token?grant_type=client_credentials&client_id=XCLIENTIDX' \
  --header 'Authorization: Basic XBASE64SECRETX' \
  --header 'content-type: application/x-www-form-urlencoded' \

```

&#x20;


# Reapit Connect

## **Reapit Connect**

### **Error: “Redirect Mismatch”**

* Check you have provided the correct Redirect URL(s) and Sign Out URL(s) on your app listing under the 'Authentication' section. \
  \
  When a user logs in, Reapit Connect will need to know where to direct the user. This is your Redirect URL(s). Reapit Connect will also need to know where to route your user if they logout. This is your Sign Out URL(s).

To test your application locally, you can provide the following (example):

**Redirect URI:** <http://localhost:8080>

**Signout URI:** <http://localhost:8080/login>

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2Fd8uorn5b2CbJezVJz210%2Fimage.png?alt=media&amp;token=a84dc41e-19bc-4e69-a0e4-606a5422fc85" alt=""><figcaption></figcaption></figure>

For more information on Reapit Connect, please [click here](https://foundations-documentation.reapit.cloud/api/reapit-connect).&#x20;


# REST API

### &#xD;**Error: “Precondition failed: The ETag provided does not match the current version of this resource. Re-fetch the latest version of this resource before attempting to update it."**

* The most common reason is that the resource has been updated since it was fetched
* The Etag should be provided in a quotation marks\
  Example "If-Match": "\\"3B1D7563C34EE44E5D5B4E2AB99E288F\\""

For more information on Etags, please click [here](https://foundations-documentation.reapit.cloud/api/api-documentation#optimistic-concurrency).


# Feature Requests

Feature requests relating to the DeveloperPortal and Platform APIs will need to be raised as defined below:&#x20;

**Reapit Customers:** The process for logging a feature request ticket relating to the DeveloperPortal and/or the Platform API is the same as you do for other services provided by Reapit. Log into the Reapit Service Desk Portal via [direct link](https://reapitsupport.refined.site/) or through the Reapit Reapit Service Desk Portal link within the Reapit desktop app.&#x20;

**External Developers/Partners:** To submit a feature request, please email <partners@reapit.com>. The Partnerships team will validate your request and, if appropriate, log a ticket on your behalf. Full details of response and resolution times are for requests are dependant on your partner tier, and can be found in the [Partner Business Services Catalogue (BSC)](https://www.reapit.com/legal/terms-and-conditions/reapit-partner-business-service-catalogue). \ <br>

**Feature Visibility**

External developers, Partners, and Customers can view our latest Release Notes that outline the latest additions and enhancements to the Reapit desktop CRM here: [Release Notes index](https://reapit.atlassian.net/wiki/x/UoBHC)

[What's New](https://foundations-documentation.reapit.cloud/whats-new) section details the latest updates to our Public Platform APIs. Have a look to see what new features and fixes have been released.&#x20;


# FAQ's

## **General**

### How do I find a ‘Customer ID’?

An agent can locate their Customer ID via the AppMarket inside of AgencyCloud:

* Within AgencyCloud, click on ‘Apps’ and select ‘Browse’
* Click on the profile icon (top right) and select 'Profile'
* The Customer ID (customer code) will be displayed under 'Your Details'

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FNrC3gmlskjn11GCKcA19%2FCustomerCode.jpg?alt=media&amp;token=8655afb6-5eef-4b54-b0d8-6005360044a3" alt=""><figcaption></figcaption></figure>

### I just want to access my data, do I still need to create an app?&#x20;

Yes, the app registration process gives you the required authentication, either to use as a client side/server-side integration or as an app that launches inside of the Desktop CRM (AgencyCloud).

In order to access customer data, an installation will need to occur. This is done by creating and listing an app in the AppMarket. It can either be public or private to a specific agent.&#x20;

Please [click here](/faqs#listing-your-app) for more information on Listing an App in AppMarket.

### How to privately list your app/integration in the AppMarket

If you are building an app or integration for a specific customer or a subset of customers, you can set your app as a ‘Private App’. This means it will only be visible in the AppMarket to those customers.

To set your app to private, you will need to navigate to the ‘Permissions’ tab which can be accessed when you ‘Edit App’: &#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FR09jXTKOmxu6COoUGa5C%2FPrivate.jpg?alt=media&amp;token=9251a6d3-ea40-4ee3-beaa-d0e919d88347" alt=""><figcaption></figcaption></figure>

Simply set the toggle to ‘Yes’ and enter the client IDs (Customer IDs), for more information on how to obtain Customer IDs, please [click here](#how-do-i-find-a-customer-id).

You will still need to submit your app for approval and once approved, the app will be visible for the customer to install.

For more information on listing your app, please [click here.](/listing-your-app)

### What are ‘Office Groups’?

Office Groups are present when an organisation is using the Reapit Marketplace Management App They will setup specific office groups that provide data boundaries between offices. The management app also allows organisational level control for installations.

Offices that are part of a group will have a distinct ‘Customer ID’. For example, Reapit Sales is an organisation comprised of 20 offices. Their customer ID is ‘RES’. However, they wish to set data boundaries between certain offices and create 2 office groups:

**Office Group 1**

This contains a list of 8 offices/branches within the organisation.

The customer ID is now RES-GOGO

**Office Group 2**

This contains a list of 12 offices/branches within the organisation

The customer ID is now RES-GOGT

Using either the Management App or via the AppMarket, an Admin can choose to install an app for the whole organisation (Customer ID: RES) which will grant access to all 20 offices, or a specific group.

If they choose to install for Office Group 1 (Customer ID: RES-GOGO) for example, an app will only have access to data for those 8 offices.

They can install for multiple groups but the data boundaries for each group will be respected and exist across our core entities.

You will be notified of the Customer ID at the point of installation. For more information, please [click here](https://foundations-documentation.reapit.cloud/faqs#installation).

## Registration

### We have created multiple accounts but want to work on the same app, what can we do?&#x20;

You can invite members to collaboratively work within the same Developer Portal organisation from the '[Organisations](https://developers.reapit.cloud/settings/organisation)' page using the 'Invite Member' option.

### **Notification Email**

The email address you entered when registering for the Developer Portal, is used by default to receive email notifications,. For example, when your app is installed from the AppMarket, you will receive an email with the details (see more information [here](https://foundations-documentation.reapit.cloud/faqs#installation))

As you cannot change the email address that registered your organisation, we have now provided the ability to supply an alternative ‘Notifications Email’.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MjYcr4Q9LksyDhZ79Hs%2F-MjYdgZRuEzMXZmXRlnX%2Fimage.png?alt=media\&token=74a44ad1-f0bc-4430-9075-f78db446231a)

If you want to setup an alternative email address, simply go to ‘[Organisation](https://developers.reapit.cloud/settings/organisation)’ page.&#x20;

**Please note:** Only an Admin will have the correct permissions to update this information.

### **How to Invite New Members**

To invite members to join your organisation, simply click on the ‘Invite Developer’ button from the '[Members](https://developers.reapit.cloud/settings/members)' page in the DeveloperPortal. The recipient will receive your invitation via email and will have the option to reject or accept. You can track the status of any members in the ‘Members’ table:

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F2bLTpRKIbfJtGGgWqUu8%2Fimage.png?alt=media&amp;token=e292f34e-6ee9-40f0-bc66-1afcbcbdd06d" alt=""><figcaption></figcaption></figure>

Within the members section you will also have the ability to disable members and to set other members as ‘Admins’.

**Please note:** Only Admins of the Developer Organisation will have access to the Organisation page.

### How to delete a member&#x20;

As an admin of a developer organisation, you have the ability to delete members from the ‘[members](https://developers.reapit.cloud/settings/members)’ section.

Simply navigate to the members section, expand the user and click ‘Delete’. This will immediately remove the user from your organisation.&#x20;

**Please note:** Only Admins of the Developer Organisation will have access to the members page.

## **Testing**

### **How can I test my App or Integration?**

The Developer Edition of AgencyCloud allows you to test your apps/integration within the desktop application using Sandbox data.

Please [click here](https://developers.reapit.cloud/desktop) for more information on testing your App or Integration.

### How can I test my Integration without a customer installation?

You can use **authorization code flow** by providing your developer portal credentials to our Reapit Connect service

You can use **client credentials flow** by providing `SBOX` as your `reapit-customer` request header

Please [click here](https://foundations-documentation.reapit.cloud/api/api-documentation#sandbox-mode) for more information on using Sandbox data

### How do I Test my App/Integration with a specific agent?

To test with a specific agent your app will need to be set to private and submitted for approval.

Using the ‘Private App’ section on your app listing, you will need to provide the Customer ID of the agent. However, it will first need to be approved and tested by our Admin department.&#x20;

Once the app has been approved it will be available to the selected agent(s) to ‘Install’ from the AppMarket.

Please [click here](/faqs#how-do-i-find-a-customer-id) for information on finding the Customer ID\
Please [click here](/faqs#listing-your-app) for more information on Listing your app\
Please [click here](/faqs#app-approvals) for more information on App Approvals

## **Developer Edition of AgencyCloud**

### How can I update details of a Negotiator in AgencyCloud using the desktop application?&#x20;

You cannot update negotiator information using the desktop CRM as Negotiator information is part of the the system configuration and is not available in the Developer Edition. However, you can use the Negotiators `PATCH`endpoint to update the required fields. Once you have made a valid request, you may need to restart AgencyCloud to see the changes reflected.&#x20;

### How do I download the Developer Edition?

Navigate to <https://developers.reapit.cloud/desktop>, click 'Subscribe' and follow the instructions. If you already created a subscription, you will be presented with the option to 'Download' a copy.&#x20;

## **Listing your App in the AppMarket**

### I’m ready to list my app, what do I need to do?

When you are ready to list your app in the AppMarket, either publicly or as a private app, it will first need to be submitted for approval privately to our testing environment 'RES'. \
\
First, ensure your app is ready to be listed, please [click here](/listing-your-app) to see a guide on what information is required.&#x20;

Once the content of your app has been added:&#x20;

* Enter Customer ID 'RES-GTRA' in the 'Private Apps' section on your app listing
* Select the 'Submit for Approval' check box and 'Submit'&#x20;

Please [click here ](https://foundations-documentation.reapit.cloud/listing-your-app#apps-launchable-inside-of-agency-cloud)for more information on testing

## **App Approvals**

### I have submitted my App for approval. How long is the approval process?

Depending on your app listing or integration and its complexity, from start to finish can typically take between 2-7 weeks.  A member of the reviewal team will make direct contact with you within 24 – 48 hours. &#x20;

Please [click here](https://foundations-documentation.reapit.cloud/listing-your-app#2-submit-for-approval) for more information on the App Approval Process&#x20;

## **Authentication**

### How do I change the authentication method on my app?

Once your app has been created, you cannot change the authentication flow. You will need to register a new app using your preferred flow.

Please [click here](https://foundations-documentation.reapit.cloud/api/reapit-connect#authentication-flow) for more information on Authentication Flows

## **Webhooks**

### How can I setup an alert to know when a new action or information has occurred or been added?

Our Webhooks system allows your application to directly subscribe to events happening in our customers data. You can manage Webhook subscriptions [here](https://developers.reapit.cloud/webhooks).

Please [click here](https://foundations-documentation.reapit.cloud/api/webhooks) to see more information on Webhooks

## **Billing/Accounts**

### What is a Reapit Account Reference?

It is a reference that is assigned to your organisation/company and would have been setup with our Accounts Department. If you have an existing relationship with Reapit, you should be able to obtain your reference on previous correspondence. If you do not have an existing relationship, you will be required to complete a Direct Debit mandate.

### My billing information is with accounts - how long will this take to process?

Once you have submitted your billing information, it will be sent to our Accounts Department to verify/setup and your account status will be set to 'Pending'.&#x20;

This setup process is usually completed within 24-48 hours. Once the information has been verified you will receive an email confirmation and your account status will be set to 'Confirmed'

## Pricing/Costs

### Do you have information regarding pricing?

You can find information regarding pricing using either the documentation listed below or on the [Analytics](https://developers.reapit.cloud/analytics/costexplorer) page.

Please [click here](/developer-terms-and-conditions#schedule-2-fees) to see pricing information on our Terms and Conditions

### I have looked at your pricing information and I have a query - who do I speak to?

Should you have any questions or queries regarding the cost or pricing structure, please [click here ](mailto:partners@reapit.com)to contact a member of the team

## Reapit Connect

### &#xD;**How do I find out information about a user?**

When a user successfully logs in using Reapit Connect and your application has performed the code exchange, you will receive a JSON payload which will include an ‘id\_token’.

The ID Token will contain information about the user and their organisation.

See an example below for user <hollyjoyphillips+res@gmail.com>, you can obtain the following information:

* Email Address ‘email’
* Negotiator ID ‘userCode’
* Customer ID ‘clientCode’
* Office ID ‘officeId’

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MexzjRpvH3GljTLST2S%2F-Mey-FAWeC0Uybz_vgd2%2FIDtoken.png?alt=media\&token=a5762ce6-b212-4cde-b5a9-5a70bcc34a1e)

For more information on Reapit Connect, please click [here](https://foundations-documentation.reapit.cloud/api/reapit-connect)

If you want to find out more information about an office, you can use the ‘officeId’ and make a request to the GET /offices/{id}

If you want to find out more information about an individual negotiator, you can use the ‘userCode’ and make a request to GET /negotiators/{id}

### &#xD;**I’m unsure what some of the fields in the id\_token relate to?**

**Cognito Groups**

**Reapit User**\
A level 1 user in AgencyCloud. Will have access to the AppMarket but do not have permissions to install or uninstall apps.

**Reapit User Admin**\
A level 2 user in AgencyCloud. Will have the permissions to install and uninstall apps from the AppMarket.

**Organisation Admin**\
Users assigned to this group will have the same permissions as a Reapit User Admin/Marketplace Admin but will also have access to the Reapit Marketplace Management App

**Marketplace Admin**\
Will have permissions to install and uninstall apps from the AppMarket

**offGrouping**\
‘offGrouping’ refers to Office Grouping. If present and set to ‘True’, the organisation will be using the Reapit Marketplace Management App. The app provides organisations the ability to control app visibility, setup office groups (setup data boundaries between offices) and control installs and uninstalls at an organisation level.

**officeID**\
The ID of the induvial office the user is associated to.

**orgName**\
The name of the organisation.

**orgID**\
The ID of the organisation (mainly used for internal services)

**clientCode**\
The Customer ID of the organisation

**userCode**\
The ID of the user in Reapit Connect

**agencyCloudNegId**\
The ID of the user in AgencyCloud

**agenyCloudId**\
The ID of the organisation in AgencyCloud

## Installation

### &#xD;W**hat information can I obtain when my app is installed?**

You will receive (at the point of installation) the following information:

### **Email**

An email will be sent to the email address used to register your [developer organisation](https://developers.reapit.cloud/settings/organisation) (office email) and to the support email address you have provided on your app listing. It will contain the following:

* The Name of the organisation
* The Customer ID of the organisation
* The Address of the organisation
* The Email Address of the user who installed your app

**Example Email:**

*Hi Joe Blogs,*

*We just wanted to let you know that ‘Your App Name’ has just been installed by '*[*example@email.com*](mailto:example@email.com%20)*' for the following client:*

*Sandbox Estates (SBOX)*\
*Third Floor, 67-74 Saffron Hill, London, EC1N 8QX, GB*

*A record of all installations can be viewed on your app in the Developers Portal under 'Installations'.*

*Best Regards,*\
*Reapit Team*

### **Webhook**

If you have setup a webhook for 'Application Install', you will receive a payload with the following information:

* The Name of the organisation (customerName)
* The Customer ID of the organisation (customerID)
* The Name of the application that has been installed (applicationName)
* The Address of the organisation (customerAddress)
* The Email Address of the user who installed your app (customerEmail)

**Example payload:**

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LzfbZymENafdjBels04%2F-MeyLPHxHQZAQfLt92mR%2F-MeyRvNCwmx-Cidwb-Hq%2Fimage.png?alt=media\&token=26366629-1068-4698-92de-f01eb7b6ab02)

For more information on webhooks, please click [here](https://foundations-documentation.reapit.cloud/api/webhooks)

### **Installations Table**

On your app listing in the Developer Portal (Apps > My Apps > Select App > Installations), you will see a full record of all installations. The table will contain the following information:

* The Name of the organisation (Customer Name)
* The Reapit Customer Code (Client ID)
* The Address of the organisation (Customer Address)
* The Date the installation occurred (Date Installed)
* The Email Address of the user who installed your app (Installed By)
* The option to terminate the installation (Uninstall)  <br>

**Example Installations table:**

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FS4nhvnuUlIqkn4dKENdC%2Fimage.png?alt=media&amp;token=06d2fac7-c795-43fa-a660-1fc90a599839" alt=""><figcaption></figcaption></figure>

## AppMarket

### Why is my app not showing in the AppMarket?&#x20;

Before your app can be listed in the AppMarket, it first needs to be submitted for approval, please see more information on listing your app [here](/listing-your-app).&#x20;

If your app has been approved and you have chosen to list it privately, ensure the Customer ID you have provided in the 'Private Apps' section is correct. For more information on obtaining a Customer ID, please click [here](/faqs#how-do-i-find-a-customer-id).&#x20;

### Launching an App

AgencyCloud apps (an an app that loads inside of the AgencyCloud desktop application), can be launched direct from the 'My Apps' page. This is also true when viewing the app within a web browser. AgencyCloud apps also work standalone. This means that you can still benefit from the product or service when out of the office and from outside of the Agency cloud desktop application.&#x20;

To launch an app, click on 'Apps' and 'My Apps'. Click on the app to launch.&#x20;

'Integrations' will not be launched from the 'My Apps' page and instead will be accessed by a URL provided by the third-party.&#x20;

As an 'Admin' (Reapit User Admin) you can view and manage your integrations from the '[Installation](https://marketplace.reapit.cloud/settings/installed)' section.

## What is an API call?&#x20;

There are 3 ways to interact with our Platform API:

* A direct request to the Platform API using one of the following methods:\
  GET, POST, PUT, PATCH & DELETE
* Receiving a payload via a Webhook
* Embedding data in a request

All methods to interact with our Platform API are API calls and are chargeable in accordance with our [Terms and Conditions](https://foundations-documentation.reapit.cloud/developer-terms-and-conditions#schedule-2-fees).&#x20;

&#x20;

### **API Direct Requests**

As an example, a single request might be to call our ‘Properties’ endpoint (GET /Properties). This is calculated as follows:

1-5 Endpoints & 1 Request

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2F2dEjR7CQ3N2Xjs2eILE1%2Fapi1.png?alt=media\&token=c07ee7ea-a401-43a1-8953-098a4dbbc4ed)

When you increase the amount of requests you make and the number of endpoints you are using, the cost of an API call will decrease.

For example, multiple requests would be calculated as follows:

1-5 Endpoints & 50,000 Requests

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FQcOUCjfXZmCRbGNhK6tY%2Fapi2.png?alt=media\&token=0c7b860e-6244-4710-9dd7-02f3dba13efc)

This is because you will be charged a certain rate for the first 1000 requests, a reduced rate for the next 2500 and so on.

&#x20;

### **Webhooks**

Webhooks are calculated the same as making a request. It’s important to note, that when making a direct request to our Platform API, you are in control of how many requests you are making. Webhooks, however, are events that are emitted and controlled by the end user (the customer).

We provide the ability to set general and granular levels of topics (events that you are interested in). For example, ‘Properties Modified’ will send an event when *any* property has been modified. Or you could set a more specific request such as ‘Selling Property Exchanged’, which will emit a webhook when a property status has been set to ‘Exchanged’.

As mentioned above, the rate and number of events that are emitted are based on the customer and their negotiators. It’s worth being mindful that bulk updates do occur. For example, if you are listening on event’s for ‘Properties Modified’ and a negotiator leaves that company, all of their properties will be transferred to a new negotiator, resulting in several properties being ‘Modified’.

&#x20;

### **Embedding**

Embedding data allows to you make a single query to our Platform and also include related data from other endpoints.

For example, you can make a query to our ‘Properties’ endpoint to search for a single property:

‘GET /properties{ID}’ & also embed ‘Appointments’. This will show you all appointments related to that property.

The core request to ‘Properties’ would be 1 endpoint and the embed ‘Appointments’ endpoint would be 1 endpoint, but the default page size for data returned is 25. If there are more than 25 associated appointments for that property, each page request is calculated as an additional request.

You can reduce this by applying the maximum page size on the initial request, for example:

‘Get /properties?pageSize=100\&embed=appointments’

The page size you set would also be applied to any endpoints you have embedded. You will not be able to pass any other query string parameters to your embedded endpoints.

This is apparent if you were, for example, only interested in associated appointments with the type ‘Viewings’, as it will return all appointments associated to that property.

Therefore, it’s important to note that whilst using this mechanism can result in improved application performance with less API interaction code required, when embedding data, you will not know how many pages of data (requests) are required and therefore will not be able to forecast the API consumption accurately.

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FRpS4FTwvcEwm8u9BAfFr%2FEmbed.png?alt=media\&token=f61cfcfe-5417-44b8-896e-294414dd74aa)

### My app is live and has been installed, how do I request a new permission?

When your app is installed, the end user agrees to the permissions you have specified at the point of installation. If you later need/request new additional permissions, we must give the end user the ability to agree to the new data requirements to ensure we adhere to client data protection.

When you select a new permission and submit your changes for ‘Review’, a modal will pop up providing the ability to send a request to the person that installed your app. Once all who have installed your app have agreed, you’re app will be approved. You can monitor the status of each request by visiting ‘App Consents’ on your app listing.

Please note, if you have submitted any other changes, the normal approval process will still be applied.

For more information, please [click here](/listing-your-app/app-permissions).

### I have an issue that requires sharing private/sensitive information that I do not wish to be made public? &#x20;

We understand that in some cases you may need to share screenshots and or personal information which may aid in the resolution of an issue or feature request.  \
&#x20;\
You must still raise the issue on GitHub first excluding any sensitive information, but highlighting you wish to share this information securely; after we have reviewed your issue, we will then ask you to send an accompanying email with the GitHub issue number as the subject.&#x20;

Please note, the GitHub issue will be the main form of communication. The secure mailbox should only be used for sharing information that cannot be publicly visible. The address of this mailbox will be provided to you once we have reviewed your GitHub issue as above. When sharing sensitive information using this mailbox, your issue will still be prioritised as per our [documented Development Processes.](https://foundations-documentation.reapit.cloud/dev-requests)&#x20;

**What is considered private/sensitive data:** &#x20;

Any personal, personally identifiable, financial, sensitive or regulated information (including credit or debit card information, bank account information or usernames and passwords).&#x20;

### **Certain fields are not exposed by default in the Platform**

Platform APIs are designed to be customer agnostic to make them easier for multiple external developers to work with them across different customers, unlike our legacy APIs which had customer specific customisations.

Therefore, to ensure we adhere to this design, we do not automatically expose customers custom fields. Custom data is stored in a different place called ‘Extras’ and are stored as semi structured fields. They are unique to the customer.

If you require access to those fields, you will need to raise a ticket [here ](https://reapitsupport.refined.site/login)(please ensure you select 'Reapit API' from the product types). We will then make the fields available to that customer only.

We will provide you the field name which you can add to your query as an additional parameter using the filter ‘extrasfield=FIELDNAME’

Example query: <https://platform.reapit.cloud/properties/ABC00000?extrasfield=pDirections>

{% hint style="warning" %}
Semi structured data which has been made available as 'extrasfield' in the REST API can be configured to be included within webhook event payloads. More info [here](https://foundations-documentation.reapit.cloud/api/webhooks#including-semi-structured-data-in-webhook-events).&#x20;
{% endhint %}

### Why can I not see the option to 'Install App' or 'Enable Integration'?&#x20;

If you cannot see the option to 'Install App' or for integrations 'Enable Integration', it will most likely be that you do not have the correct user permissions.&#x20;

Only 'ReapitUserAdmins' (a 'Level 2' user in AgencyCloud) or a 'MarketplaceAdmin' can install/enable and uninstall/disable apps and integrations from the AppMarket.&#x20;

A user can check their user role by going to the profile icon (top right) and clicking on 'Profile' from within the AppMarket.&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FCAwBQ57fQHfGzT6gUOgJ%2Fimage.png?alt=media&amp;token=8e959d06-512a-40a4-809d-ba3028718b9a" alt=""><figcaption></figcaption></figure>

### Are your resource identifiers globally unique?

Resource identifiers are unique to a specific customer and *not* globally unique as some of the underlying systems are single tenant to provide adequate data separation for our customers. Uniqueness can be determined by creating a compose key of the customer id and resource identifier. &#x20;

### How do I delete an app from the DeveloperPortal?

* Go to ‘[My Apps](https://developers.reapit.cloud/apps)’ and select the app you want to delete and click ‘Delete App’ from the left-hand panel:

![](https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FiUmigVMv5mZJ3NI90bOB%2Fimage.png?alt=media\&token=057a448a-2165-4238-bfa4-7aee4b3760bb)

* Confirming deletion by clicking ‘Delete’.&#x20;

**Please note:**  Only admins will see the option to delete an app. Also, if an app has been tagged with the 'delete prevention' option, you will be unable to delete it. However, the information presented on screen will show you where to deselect this option before you can delete.


# Reapit Connect Emails

### I have received a ‘Suspicious Account Activity’ email

If Reapit Connect detects multiple failed login attempts against your account, you will be notified via email (see example below).

Failed login attempts are categorized as one of the of the following events, occurring more than 10 times:

* Entering the wrong password&#x20;
* Clicking on ‘Forgot Password’

If the login attempts were made by you, you do not need to do anything.

However, if you have not entered an incorrect password or clicked on forgot password multiple times, we suggest sharing the IP address contained within the email with your IT department and changing your password and/or enrolling in Multi Factor Authentication (MFA) for an added level of security.

**Checking your IP Address:**

You can use various websites to check your IP Address against the one provided in the email or by simply typing into Google ‘what is my IP’. However, some businesses use VPN’s or public networks so if you are concerned and do not recognise the IP provided in the email, please speak with your IT department.  &#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FN6LN631rkNGGsIcNqBZK%2FSAA.png?alt=media&amp;token=f6fe74ea-b35e-49bb-8f8e-3c62242c5a9e" alt=""><figcaption><p>Example 'Suspicious Account Activity' email</p></figcaption></figure>

&#x20;

### I have received a ‘Reset your password’ email that I did not request

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FaatXfVkUjCjQA74Hp8TE%2FRYP.png?alt=media&amp;token=538f08a7-601f-4006-96d4-b30382418457" alt=""><figcaption><p>Example 'Reset your Password' email</p></figcaption></figure>

If you have received a 'Reset your Password’ email that you did not request, it’s possible that someone accidentally entered your email address while trying to reset their own password, or it could be an automated attempt by someone trying to access your account.

Rest assured, your account remains secure unless the reset link in the email is used to change your password. If you’re concerned, you can update your password and enable additional security measures like two-factor authentication to further protect your account via the secure ‘My Account’ section in Reapit Connect.

To change your password, log in to ‘[My Account](https://connect.reapit.cloud/my-account/)’ and select ‘Change Password’.&#x20;

<figure><img src="https://255058560-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LzfbZymENafdjBels04%2Fuploads%2FTwENn95rGmpdAWNk9C5l%2FMA.png?alt=media&amp;token=6153ec0e-8478-4523-9aa0-a4664a6a6ef4" alt=""><figcaption><p>Example ‘My Account’ page</p></figcaption></figure>

\
\
&#x20;


# Help

**How do I request a new feature or report a bug?**&#x20;

The process depends on the impact level of your request. Full details of response and resolution times can be found in the [Partner Business Services Catalogue (BSC)](https://www.reapit.com/legal/terms-and-conditions/reapit-partner-business-service-catalogue)

Critical (P1) or High (P2) issues \
Log a ticket via the Reapit Service Desk Portal: <https://reapitsupport.refined.site/>&#x20;

* Select the correct impact level and product type as ‘Reapit API’ so your request is routed to the right team.&#x20;
* Please note: Reapit will downgrade issues that are incorrectly logged as P1 or P2. Penalties will apply in line with Schedule 4 of the Developer Portal Terms & Conditions.&#x20;
* New users will need to create an account. Setup guidance is here: <https://reapit.atlassian.net/wiki/spaces/RW/pages/1432912084/Using+the+Reapit+Service+Desk+Portal>&#x20;

Medium (P3) or Low (P4) issues, and all feature requests \
Email <partners@reapit.com>. The Partnerships team will validate your request and, if appropriate, log a ticket on your behalf and provide a ticket reference number.&#x20;

&#x20;

&#x20;


# Reapit Connect Updates

{% hint style="info" %}
The following documentation does not come into effect until 18th November 2024 at 20:00 GMT. No changes should be made to your applications prior to this date
{% endhint %}

### Overview

In November 2024 we migrated to a new identity provider. To make the migration process easier for developers, a compatibility layer was built so that there wasn't a requirement for all integrating partners to update the way they interact with Reapit Connect to sign users in and obtain short lived access tokens. After an appropriate time, the compatibility layer will be removed and it is expected that all applications will have been updated. There are various logging points that will allow us to engage with you directly if we detect that your application has not been updated well ahead of the compatibility layer being sunset.

The following changes should be planned in your next round of application updates taking place after the release of our new identity provider. Please ensure you refer to the relevant section(s) for your use case, in addition to the [General Changes](#general-changes) section which includes information that applies to all applications.

### React Developers using connect-session

Applications using the [connect-session](https://www.npmjs.com/package/@reapit/connect-session) NPM package should update to a version >= 6.1.3. The updated package targets the new endpoints and also leverages [PKCE](https://oauth.net/2/pkce/) by default, enhancing the security of your application.&#x20;

Please ensure you update connect-session regularly as we will publish versions that slowly deprecate the legacy functionality that targets the compatibility layer.

The local development portion of the [Authorisation Code flow Applications (client side) section](#authorisation-code-flow-applications-client-side) also applies to React developers using the connect-session library

### Authorisation Code flow Applications (client side)

#### Changes to URLs /Endpoints

Instead of calling \`GET /logout\` use \`GET /oidc/logout\` with your client\_id and desired post\_logout\_redirect\_uri. The post\_logout\_redirect\_uri must be  registered against your app in the DeveloperPortal as one of the logout urls. For example `GET /logout?client_id=12345&logout_uri=https://myapp.io` becomes `GET /oidc/logout?client_id=12345&post_logout_redirect_uri=https://myapp.io`.

Instead of calling /login call /oauth/authorize.

When calling /oauth/authorize you should explicitly specify the space-separated scopes that you want the token to contain. Product-specific scopes need to be added for use in your application via your app listing in the developer portal. To obtain a refresh token request the `offline_access` scope. To obtain an ID token request `openid profile email` in addition to any product specific scopes.

#### Changes to refresh tokens

Applications registered after 4th November 2024 will have refresh token rotation enabled. This means a single use fresh refresh token will be returned from the token endpoint, each time a fresh access token is requested. In addition, refresh tokens will be subject to an idle timeout of 15 days (half the overall lifetime of a refresh token). If a refresh token is not used within this period it will expire.

The connect-session library handles this as part of the `ReapitConnectBrowserSession` class. If your application manages it's own Reapit Connect session, ensure logic is in place to update the session's refresh token when using this endpoint. Using token rotation makes your applications more secure and keeps customer data safe.

#### Local Development

When developing client side applications locally that use the authorization code authentication flow, you may see a consent prompt appear if targeting a localhost address. This occurs because of additional security controls in place in the new identity provider. The easiest thing to do is to accept the prompt. Alternatively, we have update the DeveloperPortal to allow you to register redirect and signout URIs using <http://dev.reapit>. This can be configured as a local DNS entry added to your system's `hosts` file and will allow your app to be trusted so that the consent prompt is not displayed.

The hosts file can be found in the following locations depending on your operating system:

| Operating System | Hosts File Location                   |
| ---------------- | ------------------------------------- |
| Windows          | C:\Windows\System32\Drivers\etc\hosts |
| Linux            | /etc/hosts                            |
| MacOS            | /etc/hosts                            |

The format of the file is the same in each operating system. To add an entry for `dev.reapit`open the hosts file in an editor with Administrative permissions and add the following line (note: if you develop inside a container, for instance using Visual Studio Code with Ubuntu from a Windows machine, you should use the IP address of your container and NOT 127.0.0.1)

`127.0.0.1    dev.reapit`

Save the file and close the editor. Confirm your changes by running `ping dev.reapit`. You should see that domain resolve to `127.0.0.1`. Note that you may need to reboot to reload your hosts configuration, depending on your operating system.

If you are using our [Vite template](/app-development/vite-template) you can update the server's configuration to open your browser automatically at`http://dev.reapit` by making the following changes to `vite.config.ts`

```typescript
server: {
    host: true,
    port: 8080
  },
```

to

```typescript
server: {
    host: true,
    port: 8080,
    open: 'http://dev.reapit:8080'
  },
```

Finally, update your app's configuration in the DeveloperPortal to use`http://dev.reapit` instead of `http://localhost`  for the redirect and signout urls.

### Machine to Machine flow Applications (server side)

#### Token caching

In response to developers not caching tokens locally, particularly where machine to machine applications are concerned, a server side caching layer has now been introduced. Repeated calls to `POST /oauth/token` will now return cached tokens where appropriate. The expiry of tokens is indicated by the `expires_in` property in the response payload. A five minute overlap is used in the server side caching layer to prevent any issues with imminently expiring tokens being returned back to your application. Only cached tokens with >= 5 minutes lifetime remaining will be returned, else a new access token will be issued. It is good practice to cache tokens locally to reduce round trips to the server.

#### Access tokens

Two minor changes are needed to any system using either the *client\_id* or *token\_use* claim returned in access tokens for machine to machine applications:

* If using the *client\_id* claim, please update your application to use the *azp* claim. The values are the same
* Remove any references to the *token\_use* claim, which will eventually be removed from access tokens for machine to machine applications, since only an access token will ever be generated for applications using this authentication type.

### General Changes

#### Changes to URLs/Endpoints

When calling `POST /oauth/token` parameters should be sent in the request body and not as query string parameters.

There are some subtle changes to the endpoints used for signing users in/out and generating tokens. The compatibility layer takes care of redirecting these requests to the new identity provider in the background, but you are encouraged to make the following changes to your application code if required:

| Old URL/Path                               | New URL/Path                                   |
| ------------------------------------------ | ---------------------------------------------- |
| <https://connect.reapit.cloud/oauth2/\\>\* | <https://connect.reapit.cloud/oauth/\\>\*      |
| <https://connect.reapit.cloud/token>       | <https://connect.reapit.cloud/oauth/token>     |
| <https://connect.reapit.cloud/login>       | <https://connect.reapit.cloud/oauth/authorize> |
| <https://connect.reapit.cloud/authorize>   | <https://connect.reapit.cloud/oauth/authorize> |
| <https://connect.reapit.cloud/logout>      | <https://connect.reapit.cloud/oidc/logout>     |