Reapit Foundations

https://foundations-documentation.reapit.cloud
Admin
Reapit Foundations provides APIs and open-source packages for developers to query the Reapit data...
Tokens:124,084
Snippets:899
Trust Score:6
Update:9 months ago
Show doc for...
Tokens:
Raw
### Direct API Request Example (GET /Properties)

Source: https://foundations-documentation.reapit.cloud/faqs

Demonstrates a direct API call to the 'Properties' endpoint using the GET method. This is a fundamental way to retrieve data from the Platform API. The cost is calculated based on the number of endpoints and requests made.

```HTTP
GET /Properties
```

--------------------------------

### Contact Resource Example with Links (JSON)

Source: https://foundations-documentation.reapit.cloud/api/api-documentation

Demonstrates the structure of a GET response for a contact resource, including the `_links` object which details related resources like documents, identity checks, offices, and negotiators.

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

--------------------------------

### Direct API Request with Embed Example (GET /properties?pageSize=100&embed=appointments)

Source: https://foundations-documentation.reapit.cloud/faqs

Shows an example of making a direct API request to the 'Properties' endpoint while embedding 'Appointments' data. This can improve performance by reducing separate API calls. The `pageSize` parameter controls the number of embedded records per page.

```HTTP
GET /properties?pageSize=100&embed=appointments
```

--------------------------------

### Renaming Configuration File Example

Source: https://foundations-documentation.reapit.cloud/app-development/contributing

An example of renaming a configuration file. This is an alternative method to `yarn conf-all` for setting up local configuration by copying and modifying the example file.

```bash
mv config.example.json config.json
```

--------------------------------

### Installing Project Dependencies with Yarn

Source: https://foundations-documentation.reapit.cloud/app-development/contributing

After cloning the repository, this command installs all necessary project dependencies using Yarn. Ensure you have Yarn installed globally.

```bash
yarn
```

--------------------------------

### Retrieve paginated data with GET request

Source: https://foundations-documentation.reapit.cloud/api/api-documentation

APIs support resource retrieval using the GET verb. Successful requests return a 200 OK response with a JSON payload. Paging is enforced with `pageSize` and `pageNumber` query strings. URL encoding of parameters is recommended.

```plaintext
GET /contacts?pageSize=10&pageNumber=2
```

--------------------------------

### Install Reapit Login Component

Source: https://foundations-documentation.reapit.cloud/app-development/web

Instructions for installing the Reapit Login component using Yarn or NPM package managers. This component is essential for integrating Reapit's authentication flow into your application.

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

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

--------------------------------

### NodeJS Webhook Verification Example

Source: https://foundations-documentation.reapit.cloud/api/webhooks

Example code demonstrating how to verify webhook signatures in a NodeJS Express application using cryptographic signing.

```APIDOC
## NodeJS Webhook Verification Example

### Description
This example demonstrates how to verify incoming webhook signatures in a NodeJS application using Express, Body Parser, and the Node Forge library. It shows how to extract the signature, retrieve the public key, and verify the message authenticity.

### Method
POST

### Endpoint
`/` (Example root endpoint for receiving webhooks)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **(Raw Body)** - Required - The raw JSON payload of the webhook.

### Request Example
*(The request body will be the raw JSON payload sent by Reapit Platform)*

### Response
#### Success Response (200)
- **Message** (string) - Confirmation that webhook processing is complete (regardless of verification success in this example).

#### Response Example
```
Webhook processing complete
```

### Code Example
```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
    // In a real application, you would fetch this using GET https://platform.reapit.cloud/webhooks/signing/{keyId}
    // and ensure it's the correct key for the given keyId.
    const publicKeyBase64 = "ijz3_2n1gmlfhqAa2XH_5uYmcL2L2VHb1IqDbRDLBnU"; // Example public key

    // Verify the signature
    try {
        const verified = ED25519.verify({
            message: msgToVerify,
            encoding: "utf8",
            signature: Buffer.from(signature, "base64"),
            publicKey: Buffer.from(publicKeyBase64, "base64") // Ensure this is the correct public key for the keyId
        });

        if (verified) {
            console.log("Signature is valid");
            // Continue to process webhook
            // Parse req.body as JSON here if needed after verification
            // const webhookData = JSON.parse(req.body.toString());
            // ... process webhookData ...
        }
        else {
            console.log("Signature is invalid");
            // Handle invalid signature - e.g., return 401 Unauthorized
            res.status(401).send("Invalid signature");
            return;
        }
    } catch (error) {
        console.error("Error during signature verification:", error);
        res.status(500).send("Error verifying signature");
        return;
    }

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

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

--------------------------------

### Install Reapit Elements v2

Source: https://foundations-documentation.reapit.cloud/app-development/elements

Install the specific version of the Reapit Elements library using Yarn. This command ensures you are using version 2.1.0.

```bash
yarn add @reapit/elements@2.1.0
```

--------------------------------

### Contact Resource Example with Embedded Data (JSON)

Source: https://foundations-documentation.reapit.cloud/api/api-documentation

Shows a condensed GET response for a contact resource when related data (offices and negotiators) has been embedded using the `embed` parameter. The related data is presented within the `_embedded` attribute.

```json
{
  "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 Calculation Example

Source: https://foundations-documentation.reapit.cloud/api/api-documentation

Demonstrates how API requests, particularly those using the embed feature, are calculated for billing purposes.

```APIDOC
## Billing Calculation Example

### Description
This section illustrates how the embed mechanism impacts your usage and billing. Requests made via the embed feature are billed as if they were made directly by you. All embed operations default to a maximum page size of 100 resources to minimize background API calls.

### Method
GET

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

### Parameters
#### Query Parameters
- **embed** (string) - Optional - Specifies related resources to embed in the response (e.g., `images`).
- **pageSize** (integer) - Optional - The number of resources to return per page. Defaults to 100 for embed operations.

### Request Example
(No specific request body for this GET example)

### Response
#### Success Response (200)
- **properties** (array) - An array of property resources.
- **images** (array) - An array of image resources associated with properties (when `embed=images` is used).

#### Response Example
```json
{
  "properties": [
    {
      "propertyId": "PRO123",
      "images": [
        { "imageId": "IMG001" },
        { "imageId": "IMG002" },
        // ... up to 15 images per property
      ]
    },
    // ... 49 more properties
  ]
}
```

### Billing Calculation Breakdown
**Scenario:** The request `GET https://platform.reapit.cloud/properties?embed=images&pageSize=50` returns 50 properties, and each property has 15 images.

1.  **Direct Request:** 1 billable call to the properties endpoint.
2.  **Embedded Images:**
    *   Total images: 50 properties * 15 images/property = 750 images.
    *   Page size for embed operations: 100.
    *   Calculated requests for images: (750 images) / 100 = 7.5. This rounds up to 8 requests to the property images endpoint (7 full pages of 100 images, and 1 partial page).
3.  **Total Billable Calls:** 1 (properties) + 8 (images) = 9 calls.
```

--------------------------------

### HTML - Integrate Login With Reapit Component

Source: https://foundations-documentation.reapit.cloud/app-development/web

Example of integrating the 'Login With Reapit' component into a single HTML page. It demonstrates how to include the script, initialize the component with necessary credentials and callbacks, and handle session data.

```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+ - Integrate Login With Reapit Component

Source: https://foundations-documentation.reapit.cloud/app-development/web

Example of integrating the 'Login With Reapit' component using ES6+ syntax. This illustrates importing the component and initializing it with configuration options, including a callback for session management.

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

--------------------------------

### Configure rootElement for Reapit Component

Source: https://foundations-documentation.reapit.cloud/app-development/web

Demonstrates how to configure the `rootElement` property for the Reapit Connect component. This example shows passing a DOM element obtained via `document.getElementById` for precise DOM manipulation.

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

--------------------------------

### GET /properties (Initial Seed)

Source: https://foundations-documentation.reapit.cloud/app-development/website-development

Fetches all properties with specified criteria, including embedded images, for initial data seeding. This is recommended for populating your database.

```APIDOC
## GET /properties (Initial Seed)

### Description
Fetches all properties that match the specified selling and letting statuses, and are marked for internet advertising. It also embeds property images, which should be stored separately. This is intended for an initial data seed into your own database.

### Method
GET

### Endpoint
`https://platform.reapit.cloud/properties`

### Query Parameters
- **sellingStatus** (string) - Required - The selling status of the property (e.g., `forSale`).
- **lettingStatus** (string) - Required - The letting status of the property (e.g., `toLet`, `tenancyCurrent`). Can be specified multiple times.
- **internetAdvertising** (boolean) - Required - Indicates if the property is advertised online.
- **embed** (string) - Optional - Specifies related resources to embed in the response (e.g., `images`).
- **pageSize** (integer) - Optional - The number of results per page. Maximum is 100.
- **pageNumber** (integer) - Optional - The page number to retrieve.

### Request Example
```
https://platform.reapit.cloud/properties?sellingStatus=forSale&lettingStatus=toLet&lettingStatus=tenancyCurrent&internetAdvertising=true&embed=images&pageSize=100&pageNumber=1
```

### Response
#### Success Response (200)
- **string** - A paginated list of property objects, including embedded images if requested.
```

--------------------------------

### Foundations API - Introduction

Source: https://foundations-documentation.reapit.cloud/api/api-documentation

Overview of the Foundations API, its RESTful nature, and how to obtain an access token for authentication.

```APIDOC
## Foundations API - Introduction

### Description
The Foundations API is organized around REST principles, featuring predictable resource-oriented URLs, standard HTTP response codes, and verbs. All requests and responses are JSON-encoded. You can test the APIs in sandbox mode using the Interactive API Explorer. The API version is 2020-01-31 and should be included in the `api-version` request header.

### Authentication Service Location
`https://connect.reapit.cloud/`

### Platform Services Location
`https://platform.reapit.cloud/`

### Key Information
- **API Version**: 2020-01-31
- **Authentication**: Use the authentication service to obtain an access token and include it in the header of subsequent requests.
- **Testing**: Utilize the [Interactive API Explorer](https://developers.reapit.cloud/swagger) for sandbox testing.
```

--------------------------------

### Launch Web Browser with Desktop API

Source: https://foundations-documentation.reapit.cloud/whats-new

This snippet shows how to use the 'agencycloud://process/webpage?' scheme to open a URL in the user's default web browser. The 'url' parameter must be provided and must start with 'http' for the link to function correctly. This enables apps to link to external websites.

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

--------------------------------

### Node.js Usage: Getting Access Token with Reapit Connect Server Session

Source: https://foundations-documentation.reapit.cloud/app-development/connect-session

This Node.js example shows how to use the `ReapitConnectServerSession` to obtain an access token for server-side authentication. It sets up an Express application to handle requests, retrieves necessary configuration from `config.json`, instantiates the server session, and provides an endpoint to fetch the access token. The module automatically handles token refreshing and caching.

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

--------------------------------

### Launch Webpage

Source: https://foundations-documentation.reapit.cloud/api/desktop-api

Allows launching a webpage in the local default browser using a specific URL.

```APIDOC
## Launch Webpage

### Description
Allows you to launch a webpage in the local default browser.

### Method
GET

### Endpoint
agencycloud://process/webpage

### Query Parameters
- **url** (string) - Required - The URL of the webpage to launch. Must start with http.

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

### Response
This action launches the specified URL in the default browser. No specific response body is returned.
```

--------------------------------

### Local Development Setup for Authorization Code Flow

Source: https://foundations-documentation.reapit.cloud/reapit-connect-updates

Instructions for configuring local development environments to avoid consent prompts when using the authorization code authentication flow. This involves updating the hosts file and optionally the Vite server configuration.

```APIDOC
## Local Development - Authorization Code Flow

### Description
This section details how to configure your local development environment to work with the authorization code authentication flow, specifically addressing the consent prompt that may appear when targeting localhost. It involves modifying your system's hosts file and potentially your Vite server configuration.

### Method
N/A (Configuration Guide)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (N/A)
N/A

#### Response Example
N/A

### Configuration Steps:
1.  **Update Hosts File:**
    *   Locate your system's hosts file:
        *   Windows: `C:\Windows\System32\Drivers\etc\hosts`
        *   Linux: `/etc/hosts`
        *   MacOS: `/etc/hosts`
    *   Open the hosts file with administrative permissions.
    *   Add the following line:
        `127.0.0.1    dev.reapit`
    *   Save the file. Note: If developing in a container, use the container's IP address instead of `127.0.0.1`.
2.  **Verify Hosts File:**
    *   Run `ping dev.reapit`. It should resolve to `127.0.0.1`.
    *   A reboot might be necessary for changes to take effect.
3.  **Update Vite Server Configuration (Optional):**
    *   Modify `vite.config.ts` to automatically open the browser at `http://dev.reapit:8080`.
    *   **From:**
        ```typescript
        server: {
            host: true,
            port: 8080
        },
        ```
    *   **To:**
        ```typescript
        server: {
            host: true,
            port: 8080,
            open: 'http://dev.reapit:8080'
        },
        ```
4.  **Update DeveloperPortal Configuration:**
    *   Change redirect and signout URIs in the DeveloperPortal from `http://localhost` to `http://dev.reapit`.
```

--------------------------------

### GET /resources

Source: https://foundations-documentation.reapit.cloud/api/api-documentation

Retrieve resources using the GET verb. Supports URL encoding for parameters and standard paging with pageSize and pageNumber.

```APIDOC
## GET /resources

### Description
Retrieves a collection of resources. Parameters should be URL encoded. Paging is enforced using `pageSize` and `pageNumber` query parameters.

### Method
GET

### Endpoint
`/resources`

### Parameters
#### Query Parameters
- **pageSize** (integer) - Optional - The number of records to return per page. Default is 25, maximum is 100.
- **pageNumber** (integer) - Optional - The page number to retrieve. 
- **[boolean_parameter]** (boolean) - Optional - If not provided, no filter is applied. If provided, filters the dataset.

### Request Example
```
GET /contacts?pageSize=10&pageNumber=2
```

### Response
#### Success Response (200)
- **pageSize** (integer) - The requested number of records per page.
- **pageNumber** (integer) - The current page number.
- **pageCount** (integer) - The number of records on the current page.
- **totalPageCount** (integer) - The total number of pages available.
- **totalCount** (integer) - The total number of resources matching the criteria.
- **_embedded** (object) - Contains the list of resources returned.

#### Response Example
```json
{
  "pageSize": 10,
  "pageNumber": 2,
  "pageCount": 10,
  "totalPageCount": 5,
  "totalCount": 50,
  "_embedded": [
    {
      "id": "resource-id-1",
      "name": "Example Resource 1"
    },
    {
      "id": "resource-id-2",
      "name": "Example Resource 2"
    }
  ]
}
```
```

--------------------------------

### Launch Email Client with Desktop API

Source: https://foundations-documentation.reapit.cloud/whats-new

This snippet demonstrates how to use the 'agencycloud://process/email?' scheme to open the user's default email client. It requires the 'address' parameter to specify the recipient. This functionality allows applications to initiate email composition.

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

--------------------------------

### Launch Company Application with cmpCode

Source: https://foundations-documentation.reapit.cloud/api/desktop-api

This snippet explains the launch process for an application of type 'Company' from AgencyCloud. It details the 'cmpCode' global parameter, which is the primary key for the company. This parameter is crucial for the app's initialization when launched via the desktop route, but might be absent if launched from the AppMarket.

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

--------------------------------

### GET /contact/{id} - Retrieving a Contact

Source: https://foundations-documentation.reapit.cloud/api/api-documentation

Demonstrates the structure of a GET response for a contact resource, including the `_links` collection which details related resources.

```APIDOC
## GET /contact/{id}

### Description
Retrieves a specific contact resource and provides links to related data.

### Method
GET

### Endpoint
`/contact/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the contact.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the contact.
- **created** (string) - The timestamp when the contact was created.
- **modified** (string) - The timestamp when the contact was last modified.
- **title** (string) - The title of the contact (e.g., Mr, Ms).
- **forename** (string) - The forename of the contact.
- **surname** (string) - The surname of the contact.
- **dateOfBirth** (string) - The date of birth of the contact.
- **homePhone** (string) - The home phone number of the contact.
- **mobilePhone** (string) - The mobile phone number of the contact.
- **email** (string) - The email address of the contact.
- **officeIds** (array) - An array of office identifiers associated with the contact.
- **negotiatorIds** (array) - An array of negotiator identifiers associated with the contact.
- **_eTag** (string) - An entity tag for optimistic concurrency control.
- **_links** (object) - A collection of links to related resources.
  - **self** (object) - Link to the contact resource itself.
    - **href** (string) - The URL to the contact resource.
  - **documents** (object) - Link to related documents.
    - **href** (string) - The URL to retrieve related documents.
  - **identityChecks** (object) - Link to related identity checks.
    - **href** (string) - The URL to retrieve related identity checks.
  - **offices** (object) - Link to related offices.
    - **href** (string) - The URL to retrieve related offices.
  - **negotiators** (object) - Link to related negotiators.
    - **href** (string) - The URL to retrieve related negotiators.

#### Response Example
```json
{
  "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
}
```
```

--------------------------------

### Landlord Application Launch

Source: https://foundations-documentation.reapit.cloud/api/desktop-api

Details on how applications are launched for a specific landlord from AgencyCloud. The `lldCode` is provided in the globals dictionary.

```APIDOC
## Launch Application for Landlord

### Description
Applications of type 'Landlord' can be launched directly from AgencyCloud for a specific landlord. Upon launch, the `lldCode` for the target landlord is provided within the application's globals dictionary.

### Method
GET (Implicit, when launched from AgencyCloud)

### Endpoint
`/` (Root endpoint of the application)

### Parameters
#### Query Parameters
None

#### Request Body
None

### Globals Dictionary (provided by AgencyCloud)
```json
{
  "lldCode": "ABC200123"
}
```

#### Path Parameters
None

### Request Example
(No direct request, launched via AgencyCloud)

### Response
(Application-specific response, depends on the launched app)

#### Success Response (200)
(Application-specific success response)

#### Response Example
(Application-specific example)

### Notes
- The `lldCode` parameter is required when an app is launched for a specific landlord via AgencyCloud.
- This parameter might not be present if the app is launched from the AppMarket.
```

--------------------------------

### Install and Import Reapit Foundations TS Definitions

Source: https://foundations-documentation.reapit.cloud/app-development/foundations-ts-defintions

This snippet shows how to install the '@reapit/foundations-ts-definitions' package using yarn and then import types like 'AppModel' using either ES6 Modules or CommonJS syntax.

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

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

// Or

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

--------------------------------

### Incoming Call Notification Payload Example

Source: https://foundations-documentation.reapit.cloud/api/notifications

Example payload for an 'incomingCall' notification. This includes an optional 'id' for correlating events, timestamp, caller ID, destination ID, and a 'huntGroup' flag that can alter notification display in some Reapit products.

```json
{
    "id": "ax2uyio8p",
    "created": "2023-11-01T10:28:00",
    "callerId": "07123 456789",
    "destinationId": "01234 567890",
    "huntGroup": false
}
```

--------------------------------

### Ended Call Notification Payload Example

Source: https://foundations-documentation.reapit.cloud/api/notifications

Example payload for an 'endedCall' notification. This payload structure is consistent with 'incomingCall' and 'answeredCall', including the event correlation 'id', timestamp, caller ID, destination ID, and 'huntGroup' flag. The 'answeredById' field may also be present.

```json
{
    "id": "ax2uyio8p",
    "created": "2023-11-01T10:28:00",
    "callerId": "07123 456789",
    "destinationId": "01234 567890",
    "huntGroup": false,
    "answeredById": "TST"
}
```

--------------------------------

### Company Application Launch

Source: https://foundations-documentation.reapit.cloud/api/desktop-api

Details on how applications are launched for a specific company from AgencyCloud. The `cmpCode` is provided in the globals dictionary.

```APIDOC
## Launch Application for Company

### Description
Applications of type 'Company' can be launched directly from AgencyCloud for a specific company. Upon launch, the `cmpCode` for the target company is provided within the application's globals dictionary.

### Method
GET (Implicit, when launched from AgencyCloud)

### Endpoint
`/` (Root endpoint of the application)

### Parameters
#### Query Parameters
None

#### Request Body
None

### Globals Dictionary (provided by AgencyCloud)
```json
{
  "cmpCode": "ABC20012345"
}
```

#### Path Parameters
None

### Request Example
(No direct request, launched via AgencyCloud)

### Response
(Application-specific response, depends on the launched app)

#### Success Response (200)
(Application-specific success response)

#### Response Example
(Application-specific example)

### Notes
- The `cmpCode` parameter is required when an app is launched for a specific company via AgencyCloud.
- This parameter might not be present if the app is launched from the AppMarket.
```

--------------------------------

### Utilities API

Source: https://foundations-documentation.reapit.cloud/whats-new

Retrieve (GET) and update (PATCH) utility types for a specific property.

```APIDOC
## GET /properties/{id}/utilities

### Description
Retrieves the utility information for a specific property, including types like Water, Electrical, Sewerage, Heating, Broadband, and Parking.

### Method
GET

### Endpoint
/properties/{id}/utilities

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the property.

### Response
#### Success Response (200)
- **utilities** (object) - Contains details about various utility types.
    - **water** (object) - Information about water utility.
    - **electrical** (object) - Information about electrical utility.
    - **sewerage** (object) - Information about sewerage utility.
    - **heating** (object) - Information about heating utility.
    - **broadband** (object) - Information about broadband utility.
    - **parking** (object) - Information about parking utility.

#### Response Example
```json
{
  "utilities": {
    "water": { "type": "other", "details": "..." },
    "electrical": { "type": "other", "details": "..." },
    "sewerage": { "type": "other", "details": "..." },
    "heating": { "type": "other", "details": "..." },
    "broadband": { "type": "other", "details": "..." },
    "parking": { "type": "other", "details": "..." }
  }
}
```

## PATCH /properties/{id}/utilities

### Description
Updates the utility information for a specific property. Allows modification of types like Water, Electrical, Sewerage, Heating, Broadband, and Parking.

### Method
PATCH

### Endpoint
/properties/{id}/utilities

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the property.

#### Request Body
- **utilities** (object) - Required - An object containing the utility types to update.
    - **water** (object) - Optional - The updated water utility information.
    - **electrical** (object) - Optional - The updated electrical utility information.
    - **sewerage** (object) - Optional - The updated sewerage utility information.
    - **heating** (object) - Optional - The updated heating utility information.
    - **broadband** (object) - Optional - The updated broadband utility information.
    - **parking** (object) - Optional - The updated parking utility information.

### Request Example
```json
{
  "utilities": {
    "electrical": {
      "type": "other",
      "details": "Special electrical meter installed"
    }
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the utilities were updated successfully.

#### Response Example
```json
{
  "message": "Utilities updated successfully."
}
```
```

--------------------------------

### Launch Landlord Application with lldCode

Source: https://foundations-documentation.reapit.cloud/api/desktop-api

This snippet demonstrates how an application of type 'Landlord' is launched from AgencyCloud. It specifies that the 'lldCode' global parameter, representing the landlord's primary key, will be available in the globals dictionary. This parameter is required for the app to load correctly when launched via the desktop route.

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

--------------------------------

### Answered Call Notification Payload Example

Source: https://foundations-documentation.reapit.cloud/api/notifications

Example payload for an 'answeredCall' notification. Similar to 'incomingCall', it includes event correlation 'id', timestamp, caller ID, destination ID, and 'huntGroup' flag. It also features an optional 'answeredById' property to indicate which user in a hunt group answered the call.

```json
{
   "id": "ax2uyio8p",
   "created": "2023-11-01T10:28:00",
    "callerId": "07123 456789",
    "destinationId": "01234 567890",
    "huntGroup": false,
    "answeredById": "TST"
}
```

--------------------------------

### Example Notification Payload Structure (JSON)

Source: https://foundations-documentation.reapit.cloud/api/notifications

This JSON structure represents an example payload for the Notifications API. It includes fields for event type, subtype, target products, specific targets within those products, and the actual message payload. The 'type' and 'subType' fields determine the expected structure of the 'payload'.

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

--------------------------------

### Instantiate ReapitConnectBrowserSession in TypeScript

Source: https://foundations-documentation.reapit.cloud/app-development/connect-session

This snippet shows how to instantiate the ReapitConnectBrowserSession class as a singleton in your JavaScript application. It outlines the required and optional parameters for configuring the session, such as client ID, OAuth URL, user pool ID, and redirect paths. Ensure you obtain the correct connectUserPoolId for your environment from the Reapit documentation.

```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/n
  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
})
```

--------------------------------

### GET /properties/{id}

Source: https://foundations-documentation.reapit.cloud/whats-new

Retrieves property details, including converted room dimensions in 'dimensionsAlt'.

```APIDOC
## GET /properties/{id}

### Description
Retrieves details for a specific property. Converted room dimensions are now available under the `dimensionsAlt` field.

### Method
GET

### Endpoint
/properties/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the property to retrieve.

### Request Example
```
GET /properties/prop_456
```

### Response
#### Success Response (200)
- **propertyId** (string) - Unique identifier for the property.
- **address** (string) - The address of the property.
- **dimensionsAlt** (object) - Converted room dimensions.
  - **bedrooms** (number) - Converted number of bedrooms.
  - **bathrooms** (number) - Converted number of bathrooms.
  - **receptionRooms** (number) - Converted number of reception rooms.

#### Response Example
```json
{
  "propertyId": "prop_456",
  "address": "123 Main St",
  "dimensionsAlt": {
    "bedrooms": 3,
    "bathrooms": 2,
    "receptionRooms": 1
  }
}
```
```

--------------------------------

### GET /tenancies/{id}

Source: https://foundations-documentation.reapit.cloud/whats-new

Retrieves tenancy details, exposing associated contacts when the tenancy is in an arranging status.

```APIDOC
## GET /tenancies/{id}

### Description
Retrieves details for a specific tenancy. If the tenancy is in an 'arranging' status, the contacts associated with the applicant are included in the `related` collection.

### Method
GET

### Endpoint
/tenancies/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the tenancy to retrieve.

### Request Example
```
GET /tenancies/ten_101
```

### Response
#### Success Response (200)
- **tenancyId** (string) - Unique identifier for the tenancy.
- **status** (string) - The current status of the tenancy (e.g., 'arranging', 'active', 'completed').
- **related** (object) - Contains related information, including contacts if status is 'arranging'.
  - **contacts** (array of objects) - List of contacts associated with the applicant.
    - **contactId** (string) - Unique identifier for the contact.
    - **name** (string) - Name of the contact.

#### Response Example
```json
{
  "tenancyId": "ten_101",
  "status": "arranging",
  "related": {
    "contacts": [
      {
        "contactId": "cont_111",
        "name": "Jane Smith"
      }
    ]
  }
}
```
```

--------------------------------

### GET /configuration/preTenancyCheckTypes

Source: https://foundations-documentation.reapit.cloud/whats-new

Retrieves pre-tenancy check types with additional details on their active status and associated offices.

```APIDOC
## GET /configuration/preTenancyCheckTypes

### Description
Retrieves a list of pre-tenancy check types. Includes information on whether each check is active and the offices it applies to.

### Method
GET

### Endpoint
/configuration/preTenancyCheckTypes

### Parameters
*No specific parameters for this endpoint in the provided text.*

### Request Example
```
GET /configuration/preTenancyCheckTypes
```

### Response
#### Success Response (200)
- **checkTypeId** (string) - Unique identifier for the check type.
- **name** (string) - Name of the check type.
- **active** (boolean) - Indicates if the check type is currently active.
- **officeIds** (array of strings) - List of office IDs to which this check applies.

#### Response Example
```json
{
  "preTenancyCheckTypes": [
    {
      "checkTypeId": "ct_abc",
      "name": "Credit Check",
      "active": true,
      "officeIds": ["OXF", "MKN"]
    },
    {
      "checkTypeId": "ct_xyz",
      "name": "Right to Rent Check",
      "active": false,
      "officeIds": ["OXF"]
    }
  ]
}
```
```

--------------------------------

### Contact Application Launch

Source: https://foundations-documentation.reapit.cloud/api/desktop-api

Details on how applications are launched for a specific contact from AgencyCloud. The `cntCode` is provided in the globals dictionary.

```APIDOC
## Launch Application for Contact

### Description
Applications of type 'Contact' can be launched directly from AgencyCloud for a specific contact. Upon launch, the `cntCode` for the target contact is provided within the application's globals dictionary.

### Method
GET (Implicit, when launched from AgencyCloud)

### Endpoint
`/` (Root endpoint of the application)

### Parameters
#### Query Parameters
None

#### Request Body
None

### Globals Dictionary (provided by AgencyCloud)
```json
{
  "cntCode": "ABC20012345"
}
```

#### Path Parameters
None

### Request Example
(No direct request, launched via AgencyCloud)

### Response
(Application-specific response, depends on the launched app)

#### Success Response (200)
(Application-specific success response)

#### Response Example
(Application-specific example)

### Notes
- The `cntCode` parameter is required when an app is launched for a specific contact via AgencyCloud.
- This parameter might not be present if the app is launched from the AppMarket.
```

--------------------------------

### GET /applicants

Source: https://foundations-documentation.reapit.cloud/whats-new

Retrieves a list of applicants with new filtering options for 'Last Call' and 'Next Call'.

```APIDOC
## GET /applicants

### Description
Retrieves a list of applicants. Supports filtering by the 'Last Call' and 'Next Call' status.

### Method
GET

### Endpoint
/applicants

### Parameters
#### Query Parameters
- **hasLastCall** (boolean) - Optional - Filters applicants who have had a last call.
- **hasNextCall** (boolean) - Optional - Filters applicants who have a next call scheduled.

### Request Example
```
GET /applicants?hasLastCall=true&hasNextCall=false
```

### Response
#### Success Response (200)
- **applicantId** (string) - Unique identifier for the applicant.
- **name** (string) - Name of the applicant.
- **lastCall** (object) - Details about the last call made to the applicant.
- **nextCall** (object) - Details about the next scheduled call for the applicant.

#### Response Example
```json
{
  "applicants": [
    {
      "applicantId": "app_123",
      "name": "John Doe",
      "lastCall": {
        "date": "2023-02-27T10:00:00Z"
      },
      "nextCall": {
        "date": "2023-03-01T14:00:00Z"
      }
    }
  ]
}
```
```
Tokens:
Raw