### Project Setup and Dependency Installation for Next.js

Source: https://github.com/EverRealGMBH/everreal-nextjs-nextauth-oauth2-example

This snippet outlines the basic commands required to set up and run the Next.js project. It includes installing project dependencies using npm and starting the development server. Ensure Node.js and npm are installed on your system before executing these commands.

```bash
npm install
npm run dev
```

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

### Data Import Flow Overview

Source: https://api-docs.everreal.co/how-to-guide/master-data

Provides a visual and textual guide to the recommended order for importing master data into EverReal, starting with owners and progressing through properties, units, tenants, and bank accounts.

```APIDOC
## Data Import via GraphQL

Master data is the information related to Owner, Property, Unit, Tenant and Bank Account. To request these information it is required to have authorization tokens. For importing master data to EverReal it is required to keep the following order:

1. **Owners Mutation**: First, the owners should be created/imported.
2. **Property Groups (Optional)**: Creating Property groups is recommended for bulk inheritance of descriptions to several properties, but it's not necessary or a precondition for creating properties.
3. **Property Mutation**: Properties should be created, considering the checklist for potential issues like address formatting, duplicate properties, and property vs. property group distinction.
4. **Units Mutation**: Units can be created and assigned to associated properties. Considerations include formatting for unit names, storage, and floor numbers for stacking plan generation.
5. **Tenants Mutation**: Tenants can be created and assigned to units. Tenant import updates unit status automatically based on contract dates.
6. **Bank Accounts Mutation (Optional)**: If importing bank account data, use this mutation after core entities are created. Each bank account must be linked to at least one of `owner_id`, `property_id`, or `unit_id`.
```

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

### User Authentication Response Example

Source: https://context7_llms

Example response structure for a successful user authentication or retrieval.

```APIDOC
## User Authentication Response Example

### Success Response (200)

- **id** (string) - Unique identifier for the user.
- **email** (string) - User's email address.
- **isActive** (boolean) - Indicates if the user account is active.
- **firstName** (string) - User's first name (can be null).
- **lastName** (string) - User's last name (can be null).
- **profilePhoto** (string) - URL to the user's profile photo (can be null).
- **profileData** (object) - Object containing user-specific profile data.
  - **language** (string) - User's preferred language.
- **isTenant** (boolean) - Indicates if the user is a tenant.
- **createdAt** (string) - Timestamp when the user was created.
- **updatedAt** (string) - Timestamp when the user was last updated.
- **areTermsAccepted** (boolean) - Indicates if the user has accepted the terms.
- **companies** (array) - List of companies the user is associated with.
  - **id** (string) - Company ID.
  - **name** (string) - Company name.
  - **isDefault** (boolean) - Indicates if this is the user's default company.
- **currentCompany** (object) - The user's currently active company.
  - **id** (string) - Company ID.
  - **name** (string) - Company name.
  - **partner** (object) - Details of the company's partner.
    - **id** (string) - Partner ID.
    - **name** (string) - Partner name.
    - **subdomain** (string) - Partner's subdomain.
  - **isDefault** (boolean) - Indicates if this is the default company.
- **tokenInfo** (object) - Information about the authentication token.
  - **audience** (string) - Token audience.
  - **scope** (array) - List of granted scopes.
  - **user_id** (string) - The ID of the user associated with the token.
  - **expires_in** (integer) - Token expiration time in seconds.

### Response Example
```json
{
  "id": "76dccab0-652e-4543-802c-7c701c098ad3",
  "email": "john.doe@ovooovo.com",
  "isActive": true,
  "firstName": null,
  "lastName": null,
  "profilePhoto": null,
  "profileData": {
    "language": "en-US"
  },
  "isTenant": false,
  "createdAt": "2021-07-19T14:21:50.215Z",
  "updatedAt": "2021-07-19T14:21:50.215Z",
  "areTermsAccepted": true,
  "companies": [
    {
      "id": "76dccab0-652e-4543-802c-7c701c0b3bb3",
      "name": "automation-reporting-qa",
      "isDefault": true
    }
  ],
  "currentCompany": {
    "id": "76dccab0-652e-4543-802c-7c701c0b3bb3",
    "name": "automation-reporting-qa",
    "partner": {
      "id": "76dccab0-652e-4543-802c-7c701c046579",
      "name": "test-documentation",
      "subdomain": "test-documentation"
    },
    "isDefault": true
  },
  "tokenInfo": {
    "audience": "76dccab0-652e-4543-802c-7c701c0a68f6",
    "scope": [
      "offline_access",
      "company_contracting_edit_contract",
      "message_templates_all",
      "company_portfolio_all",
      "company_user",
      "email_templates_all"
    ],
    "user_id": "76dccab0-652e-4543-802c-7c701c097b81",
    "expires_in": 3571
  }
}
```
```

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

### GraphQL Example for Creating a Candidate

Source: https://context7_llms

Demonstrates how to use the `upsertCandidateInitialApplication` mutation to create or update a candidate in the EverReal system. This example includes all required parameters and several optional ones.

```graphql
mutation {
  upsertCandidateInitialApplication(
  listingId:"1eb2ad05-e692-4439-9ee9-2f61f3ff64bb",
  candidate:{
  email:"liviu+candidateintegration3@ignat.email"
  firstName:"Liviu"
  lastName:"from integrations",
  message: "Hi, how are u mate",
  currency: EUR,
  phoneNumber: "+49123456",
  desiredStartDate: "2022-12-01",
  noTotalPeopleMovingIn: 3,
  netMonthlyIncomeRanges: {from: 3000, to: 4000},
  employmentType: CLERK
  }
){
  success
}
```

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

### JavaScript Example of Handling Property Created Event

Source: https://context7_llms

Illustrates how to handle the PROPERTY_CREATED webhook event. This example assumes an Express.js environment and demonstrates basic logging of the event payload. It is a foundational example for integrating EverReal webhooks.

```javascript
app.post('/webhook/property-created', (req, res) => {
  const event = req.body;
  console.log('Received PROPERTY_CREATED event:', event);
  // Process the event data here
  res.sendStatus(200);
});
```

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

### Interactive GraphQL Query Example

Source: https://graphql.org/learn

Provides an example of an interactive GraphQL query within a learning environment, suggesting how to add fields like `id` and `appearsIn` to an object to observe updated results.

```graphql
Operation {
  hero {
    name
    # add additional fields here!
  }
}
```

```json
Response {
  "data": {
    "hero": {
      "name": "R2-D2"
    }
  }
}
```

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

### Webhook Registration Example (cURL)

Source: https://api-docs.everreal.co/webhooks

Provides a cURL command example for registering a new webhook.

```APIDOC
## Webhook Registration Example

### Description
Below we are providing a full example how to create webhook using cURL.

### Request Example (cURL)
```bash
curl --location --request POST 'https://acme-qa.everreal.co/api/external-integrations/webhooks' \
--header 'Authorization: Bearer eyJhbGciOiJ...' \
--header 'Content-Type: application/json' \
--data-raw '{ "type":"LISTING_CANDIDATE_APPLIED", "url":"https:///" }'
```
```

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

### Update Listing Mutation Example

Source: https://context7_llms

Demonstrates how to perform an update listing mutation. It shows the GraphQL query structure, including the 'updateListing' field with the 'listing' input object. This example requires 'id' and 'action' fields.

```graphql
mutation {
  updateListing(
  listing: {
  id: "42b751a6-3eb6-4e48-a0d1-8e9959151672"
  action: ACTIVATE_LISTING
  }
  ) {
  id
  }
 }
```

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

### Authenticate and Get Token using Python Requests

Source: https://context7_llms

This Python example shows how to authenticate with the Everreal API using the `requests` library. It constructs a POST request with the authentication payload and necessary headers. The response text, containing the authentication tokens, is then printed.

```python
import requests
import json

url = "https://{{custom_subdomain}}.everreal.co/accounts/oauth/token"

payload = json.dumps({
  "username": "john.doe@everreal.co",
  "password": "Password",
  "client_id": "<Client_iD>",
  "client_secret": "<Client Secret>",
  "scope": "offline_access *",
  "grant_type": "password"
})
headers = {
  'Content-Type': 'application/json',
  'Cookie': 'accept-language=de-DE'
}

response = requests.post(url, headers=headers, data=payload)

print(response.text)
```

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

### Create or Update Tenant Example (JavaScript)

Source: https://api-docs.everreal.co/endpoints/tenants/tenant-mutation

Provides a JavaScript example for performing a tenant upsert operation using the EverReal API. This includes setting up headers and constructing the GraphQL mutation payload.

```javascript
var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer ....
");
myHeaders.append("Content-Type", "application/json");

var graphql = JSON.stringify({
    query: '\r\n mutation {\r\n upsertTenant(\r\n tenant: {\r\n meta: { source: "INTEGRATION_SOURCE" }\r\n externalTenantId: "91001+0069330"\r\n exte'
```

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

### GraphQL Example Tenant Query

Source: https://api-docs.everreal.co/endpoints/tenants/tenants-query

An example of how to use the 'tenants' query in GraphQL to fetch a list of tenants. This example demonstrates filtering by 'externalId' and applying pagination.

```graphql
{
  tenants( input: { filter: { externalId: "external-tenant-3" } paging: { skip: 0, take: 20 } } )
  {
    id
    firstName
    lastName
    externalId
    email
    company {
      id
    }
    createdAt
    updatedAt
  }
}
```

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

### Webhook Registration Success Response Header Example

Source: https://context7_llms

This example shows a response header that might be returned upon successful registration of a new webhook, often containing a unique identifier for the created webhook.

```http
{ "Location": "d32d5912-4496-4398-814e-a734ccadb615" }
```

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

### GraphQL Query Example for Candidates

Source: https://api-docs.everreal.co/endpoints/candidates/candidates-query

An example of how to query candidates using GraphQL, specifying filters for company ID, property ID, and applicant status. This demonstrates practical usage of the 'candidates' query.

```graphql
query candidates($companyId: String, $propertyId: String, $isApplicant: Boolean) {
  candidates(input: {
    paging: { take: 100, skip: 0 }
    filter: {
      companyId: $companyId
      propertyId: $propertyId
      isApplicant: $isApplicant
    }
  }) {
    id
    email
    firstName
    lastName
    fullName
    rating
    candidateSource
    isApplicant
    isDisabled
    isPendingCandidate
    isFromInvestment
    hasSharedDataRoom
    hadAcceptedSellingCancelationNotice
    viewingStartDate
    disabledReason {
      reason
      message
    }
    statuses {
      scheduledStatus
      vettingStatus
      disabledStatus
    }
    notificationStatuses {
      hasReceivedStep2InviteEmail
      hasReceivedStep2InvitationFromAdmi
```

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

### JavaScript Fetch Example for Upserting an Owner

Source: https://api-docs.everreal.co/endpoints/owners/owners-mutation

Provides a JavaScript example using the `fetch` API to execute the `upsertOwner` GraphQL mutation. This includes setting up headers, constructing the JSON payload, and handling the response.

```javascript
var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer .... ");
myHeaders.append("Content-Type", "application/json");

var graphql = JSON.stringify({
  query: "mutation {\r\n upsertOwner(\r\n owner: {\r\n meta: { source: \"INTEGRATION_SOURCE\" }\r\n externalOwnerId: \"91001+002242\"\r\n firstName: \"Ivana\"\r\n lastName: \"Maric\"\r\n email: \"ivana.maric@everreal.com\"\r\n companyName: \"Everreal Gmbh\"\r\n phoneNo: \"+49 123 1231 1237\"\r\n address: {\r\n streetName: \"Villenallee\"\r\n streetNumber: \"21\"\r\n zipCode: \"40211\"\r\n city: \"Düsseldorf\"\r\n country: \"DE\"\r\n }\r\n }\r\n ) {\r\n id\r\n }\r\n}\r\n\r\n",
  variables: {}
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: graphql,
  redirect: 'follow'
};

fetch("http://{subdomain}.everreal.co/api/reporting/graphql", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error))
```

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

### Create or Update Tenant Example (GraphQL)

Source: https://api-docs.everreal.co/endpoints/tenants/tenant-mutation

Demonstrates how to use the `upsertTenant` mutation to create or update a tenant record in EverReal. This example includes common fields required for tenant creation.

```graphql
mutation {
  upsertTenant(
    tenant: {
      meta: { source: "INTEGRATION_SOURCE" }
      externalTenantId: "91001+006"
      externalUnitId: "11092+1101"
      firstName: "Ivana"
      lastName: "Maric"
      email: "ivanamaric@everreal.co"
      coldRent: "900.00"
      serviceCharges: "880.00"
      heatingCosts: "3.00"
      totalRent: "500"
      securityDeposit: "500"
      contractStartDate: "01.01.2020"
      contractEndDate: "01.01.2024"
      companyName: "gmbh"
    }
  ) {
    id
  }
}
```

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

### Python Example - Handling Rate Limiting

Source: https://api-docs.everreal.co/rate-limiting

Illustrates how to handle rate limiting in Python using the `requests` library. The example checks the rate limit headers and sleeps when the limit is reached.

```APIDOC
## Python Example

### Description
This example demonstrates how to handle rate limiting using Python and the `requests` library.

### Code
```python
#make sure you have requests installed or run the following
# pip3 install requests
from datetime import datetime
from time import sleep
import requests

url = "https://{subdomain}.everreal-dev.co/api/reporting/graphql"
token = 'ey...'
payload="{\"query\\":\\"query {\\\\r\\\\n users(input: { paging: { take: 10, skip: 0 }, filter: { email: \\\\"email@domain.com\\\\" } }) {\\\\r\\\\n id\\\\r\\\\n email\\\\r\\\\n }\\\\r\\\\n}\",\"variables\\":{}}"
headers = {
 'Authorization': f'Bearer {token}',
 'Content-Type': 'application/json',
}

for i in range(0,100):
 response = requests.request("POST", url, headers=headers, data=payload)
 print(f"response code {response.status_code} at {datetime.now()}")
 print("remaining", response.headers['X-RateLimit-Remaining'])
 if(response.headers['X-RateLimit-Remaining'] == '0'):
 print(f"Sleeping {response.headers['X-RateLimit-Reset']}")
 sleep(int(response.headers['X-RateLimit-Reset']))
 print("-------------------------------------------------------")
```
```

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

### GraphQL Example for Activating a Listing

Source: https://api-docs.everreal.co/endpoints/listing/listing-mutation

An example demonstrating how to use the 'updateListing' mutation to activate a specific listing using its ID. This snippet shows the basic structure for performing an update operation.

```graphql
mutation {
  updateListing(
    listing: {
      id: "42b751a6-3eb6-4e48-a0d1-8e9959151672"
      action: ACTIVATE_LISTING
    }
  ) {
    id
  }
}
```

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

### GraphQL Query cURL Example

Source: https://context7_llms

Example of how to send a GraphQL query using cURL to fetch listing data. This demonstrates the HTTP POST request structure, including the 'query' payload and necessary headers for specifying the content type and acceptance of JSON responses.

```curl
curl -X POST \
  http://localhost:4000/graphql \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "query { listings { id title } }"
  }'
```

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

### Get All Documents Metadata (Example Response)

Source: https://api-docs.everreal.co/endpoints/document-management/document-management

An example JSON response for retrieving all documents' metadata from a company. This response can be used to display a list of documents or query for specific files.

```json
[{
  "id": "f2d8b7a5-9e58-4347-8864-35243fd952b0",
  "resourcePath": "subdomain/116aeae1-615a-11e7-97db-257f422c1234/properties/117ff3a1-6f1b-4da8-a3da-208d2e6f5ac4/f2d8b7a5-9e58-4347-8864-35243fd952b0",
  "title": "Floor plans",
  "companyId": "116aeae1-615a-11e7-97db-257f422c1234",
  "type": "DOCUMENT",
  "propertyId": "117ff3a1-6f1b-4da8-a3da-208d2e6f5ac4",
  "propertyGroupId": null,
  "unitId": null,
  "tenantId": null,
  "candidateId": "3512f79f-5c99-49ce-a517-df838cce75b7",
  "email": null,
  "mediaType": "image/png",
  "size": 10473459,
  "createdAt": "2023-05-24T09:43:19.043Z",
  "updatedAt": "2023-05-24T09:43:19.043Z"
}]
```

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

### GraphQL Pagination Example

Source: https://context7_llms

Demonstrates how to implement pagination in GraphQL queries by utilizing 'take' and 'skip' parameters within the 'paging' input object. This allows for efficient retrieval of large datasets by fetching data in chunks.

```graphql
{
  owners(input: {filter: <your filters>, paging: {skip:0, take:50}}) {
    id
  }
}
```

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

### GraphQL Query and Response Example

Source: https://graphql.org/learn

Demonstrates a simple GraphQL query to fetch a user's name and the corresponding JSON response. This highlights how GraphQL allows clients to request data in a structure that matches their needs.

```graphql
{
  me {
    name
  }
}
```

```json
{
  "data": {
    "me": {
      "name": "Luke Skywalker"
    }
  }
}
```

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

### Authenticate and Get Token using C# RestSharp

Source: https://context7_llms

This code example shows how to authenticate with the Everreal API and retrieve an access token using the RestSharp library in C#. It constructs a POST request with the necessary JSON payload and headers. The response content, containing the authentication tokens, is then printed to the console.

```csharp
var client = new RestClient($"https://{{custom_subdomain}}.everreal.co/accounts/oauth/token");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Cookie", "accept-language=de-DE");
var body = @"{  " + "\n" + @"\"username\": \"john.doe@everreal.co\",  " + "\n" + @"\"password\": \"Password\",  " + "\n" + @"\"client_id\": \"<Client_iD>\",  " + "\n" + @"\"client_secret\": \"<Client Secret>\",  " + "\n" + @"\"scope\": \"offline_access *\",  " + "\n" + @"\"grant_type\": \"password\"  " + "\n" + @"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
```

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

### Example Property Group Query - GraphQL

Source: https://api-docs.everreal.co/endpoints/property-groups/property-groups-query

An example demonstrating how to query a list of property groups using the EverReal API. This example shows filtering by `externalId` and specifying pagination options.

```graphql
{
  propertyGroups( input: { filter: { externalId: "iPG-32" }, paging: { skip: 0, take: 10 } } )
  {
    name
    externalId
    properties {
      id
      objectId
      name
      category
      subtype
      type
    }
  }
}
```

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

### JavaScript Fetch API for Tenant Mutation

Source: https://context7_llms

A JavaScript example using the `fetch` API to send a `upsertTenant` GraphQL mutation. It includes setting up headers for authorization and content type, and handling the response.

```javascript
var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer ....
");
myHeaders.append("Content-Type", "application/json");

var graphql = JSON.stringify({
  query: "\r\n mutation {\r\n upsertTenant(\r\n tenant: {\r\n meta: { source: \"INTEGRATION_SOURCE\" }\r\n externalTenantId: \"91001+0069330\"\r\n externalUnitId: \"11092+1101122211s\"\r\n firstName: \"Ivana\"\r\n lastName: \"Maric\"\r\n email: \"ivana@masssric.de\"\r\n coldRent: \"900.00\"\r\n serviceCharges: \"880.00\"\r\n heatingCosts: \"3.00\"\r\n totalRent: \"500\"\r\n securityDeposit: \"500\"\r\n contractStartDate: \"01.01.2020\"\r\n contractEndDate: \"01.01.2024\"\r\n placeOfBirth: \"thotta\"\r\n companyName: \"Everreal Gmbh\"\r\n }\r\n ) {\r\n id\r\n }\r\n}",
  variables: {},
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: graphql,
  redirect: 'follow'
};

fetch("http://{subdomain}.everreal.co/api/reporting/graphql", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
```

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

### Example JWT Claims Set

Source: https://datatracker.ietf.org/doc/html/rfc7519

This example shows a typical JWT Claims Set containing standard claims like issuer ('iss'), expiration time ('exp'), and a custom claim ('http://example.com/is_root').

```json
{
  "iss": "joe",
  "exp": 1300819380,
  "http://example.com/is_root": true
}
```

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

### GraphQL Example for Contact Query

Source: https://api-docs.everreal.co/endpoints/contacts/contact-query

Provides an example of a GraphQL query to retrieve a list of contacts. The example demonstrates filtering by email and specifying pagination details (skip and take) to fetch a specific subset of contacts.

```graphql
{
  contacts(input: { filter: { email: "test@acme.com"}, paging: {skip: 0, take: 5}}) {
    id
    firstName
    lastName
    salutation
    title
    email
    createdAt
    updatedAt
  }
}
```

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

### JWT Claims Set Example

Source: https://datatracker.ietf.org/doc/html/rfc7519

Presents an example of a JWT Claims Set, including its JSON representation and the corresponding UTF-8 octet sequence. It highlights common claims like issuer ('iss') and expiration ('exp').

```json
{
  "iss": "joe",
  "exp": 1300819380,
  "http://example.com/is_root": true
}
```

```text
[123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 111, 116, 34, 58, 116, 114, 117, 101, 125]
```

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

### Recommended Tenant File Structure

Source: https://context7_llms

This section details the required fields for the tenant module, including their data types, requirements, and descriptions. Key fields include tenant ID, unit ID, first name, last name, email, rent details, and contract dates.

```APIDOC
## Recommended Tenant File Structure

This documentation describes the structure and fields required for the tenant module data import.

### Parameters

#### Request Body

- **tenantId** (String) - Required - External tenant ID reference.
- **unitId** (String) - Required - External unit ID reference.
- **firstName** (String) - Required - Tenant's first name.
- **lastName** (String) - Required - Tenant's last name.
- **email** (Email) - Optional - Tenant's email address.
- **basicRent** (Decimal) - Optional - Contract's basic rent.
- **utilityCosts** (Decimal) - Optional - Contract's utility costs.
- **heatingCosts** (Decimal) - Optional - Contract's heating cost.
- **totalRent** (Decimal) - Required - Contract's total rent.
- **deposit** (Decimal) - Required - Contract's deposit.
- **contractStartDate** (String) - Required - Contract start date.
- **contractEndDate** (String) - Optional - Contract end date.

### Response

#### Success Response (200)

- **message** (String) - Confirmation message indicating successful data import.

#### Response Example

```json
{
  "message": "Tenant data imported successfully."
}
```
```

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

### GraphQL Tenant Query Example

Source: https://context7_llms

An example demonstrating how to query tenant information using the EverReal API. It specifies filtering by external ID and setting pagination limits. The query returns tenant details including ID, names, external ID, email, company information, and timestamps.

```graphql
{
  tenants(
  input: { 
  filter: { externalId: "external-tenant-3" } 
  paging: { skip: 0, take: 20 } 
  }
  ) {
  id
  firstName
  lastName
  externalId
  email
  company {
  id
  }
  createdAt
  updatedAt
  }
}
```

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

### Example Property Upsert Mutation (GraphQL)

Source: https://api-docs.everreal.co/endpoints/properties/properties-mutation

Provides a complete GraphQL mutation example for creating or updating a property. It demonstrates how to populate the 'upsertProperty' mutation with necessary fields from 'PropertyInput', including nested 'MetaInformation' and 'AddressInput'. This example shows required fields and some optional ones.

```graphql
mutation {
  upsertProperty(
    property: {
      meta: { source: "INTEGRATION_SOURCE" }
      name: "Munich Appartment"
      type: BUILDING
      externalPropertyId: "9098/501"
      ownerId: "b8559500-bb35-11ec-a64e-4b00ff3d25d5"
      externalOwnerId: "981/2"d
      category: RESIDENTIAL
      subtype: BUILDING
      noOfStories: 10
      address: {
        city: "Ludwigshafen a. Rhein"
        country: "DE"
        streetNumber: "44 - 68"
        streetName: "
```

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

### Example GraphQL Query for Owners

Source: https://api-docs.everreal.co/endpoints/owners/owners-query

An example of how to query for a list of owners, filtering by externalId and specifying pagination.

```graphql
{
  owners(
    input: {
      filter: { externalId: "iE-32" },
      paging: { skip: 0, take: 50 }
    }
  ) {
    id
    email
    firstName
    lastName
    address {
      city
    }
    bankInformation {
      iban
    }
  }
}
```

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

### GraphQL Pagination Example

Source: https://api-docs.everreal.co/helpers/pagination

Demonstrates how to use pagination with the owners query in GraphQL. The 'take' parameter specifies the number of items per response, and 'skip' determines the number of items to skip from the beginning of the dataset.

```graphql
{
  owners(input: {filter: , paging: {skip:0, take:50}}) {
    id
  }
}
```

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

### Python Example for Handling Rate Limiting

Source: https://context7_llms

A Python code snippet demonstrating how to check rate limit headers and pause execution when the limit is reached.

```APIDOC
## Python Rate Limiting Handler

### Description
This example shows how to use the `requests` library in Python to make API calls, check rate limit headers, and implement a sleep mechanism when the rate limit is approached or exceeded.

### Method
POST

### Endpoint
`https://{subdomain}.everreal-dev.co/api/reporting/graphql`

### Parameters
#### Request Body
- **payload** (string) - JSON string representing the GraphQL query and variables.

#### Headers
- **Authorization** (string) - Bearer token for authentication.
- **Content-Type** (string) - `application/json`

### Request Example
```python
# make sure you have requests installed or run the following pip3 install requests
from datetime import datetime
from time import sleep
import requests

url = "https://{subdomain}.everreal-dev.co/api/reporting/graphql"
token = 'ey...' # Replace with your actual token

payload="{\"query\":\"query {\r\n users(input: { paging: { take: 10, skip: 0 }, filter: { email: \"email@domain.com\" } }) {\r\n id\r\n email\r\n }\r\n}\",\"variables\":{}}"

headers = {
  'Authorization': f'Bearer {token}',
  'Content-Type': 'application/json',
}

for i in range(0,100):
  response = requests.request("POST", url, headers=headers, data=payload)
  print(f"response code {response.status_code} at {datetime.now()}")
  print("remaining", response.headers['X-RateLimit-Remaining'])
  if(response.headers['X-RateLimit-Remaining'] == '0'): # Check as string as headers are strings
    print(f"Sleeping {response.headers['X-RateLimit-Reset']}")
    sleep(int(response.headers['X-RateLimit-Reset']))
  print("-------------------------------------------------------")
```

### Response
#### Success Response (200)
- **response.status_code** (integer) - The HTTP status code of the response.
- **response.headers['X-RateLimit-Remaining']** (string) - The number of requests remaining.
- **response.headers['X-RateLimit-Reset']** (string) - The number of seconds until the rate limit resets.

#### Response Example
```
response code 200 at 2023-10-27 10:00:00.123456
remaining 299
-------------------------------------------------------
```

#### Error Response (429)
- **response.status_code** (integer) - 429 indicates rate limit exceeded.
- **response.headers['X-RateLimit-Remaining']** (string) - Usually '0' when 429 is returned.
- **response.headers['X-RateLimit-Reset']** (string) - The time in seconds until the limit resets.

#### Error Response Example
```
response code 429 at 2023-10-27 10:01:00.123456
remaining 0
Sleeping 55
-------------------------------------------------------
```
```

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

### JavaScript Example for Activating a Listing

Source: https://api-docs.everreal.co/endpoints/listing/listing-mutation

Demonstrates how to perform the 'updateListing' mutation using JavaScript's Fetch API. This code snippet sets up the request headers and sends the GraphQL mutation to the EverReal API endpoint.

```javascript
var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer .... ");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Cookie", "accept-language=de-DE");

var graphql = JSON.stringify({
  query: "\r\nmutation {\r\n updateListing(\r\n listing: {\r\n id: \"42b751a6-3eb6-4e48-a0d1-8e9959151670\"\r\n action: ACTIVATE_LISTING\r\n }\r\n ) {\r\n id\r\n }\r\n}",
  variables: {}
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: graphql,
  redirect: 'follow'
};

fetch("http://.everreal.co/api/reporting/graphql", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
```

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

### Street Number Extractor Example

Source: https://context7_llms

This example demonstrates how to extract the street number from a full address string. It takes an input like 'Musterstraße 8' and outputs only the street number, '8'.

```example
Input: Musterstraße 8
Output: 8
```

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

### Street Name Extractor Example

Source: https://context7_llms

This example shows how to extract the street name from a full address string. It takes an input like 'Musterstraße 8' and outputs only the street name, 'Musterstraße'.

```example
Input: Musterstraße 8
Output: Musterstraße
```

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

### Webhooks - LISTING_CONTRACT_FLOW_STARTED

Source: https://api-docs.everreal.co/webhooks/listing-contracting-events/listing_contract_flow_started

This webhook is triggered when a contract is created in EverReal. It provides details about the initiated contract flow.

```APIDOC
## LISTING_CONTRACT_FLOW_STARTED Webhook

### Description
Notifies when a contract is created in EverReal, submitting the below payload.

### Method
POST

### Endpoint
`/webhooks/listing_contract_flow_started`

### Request Body

- **uuid** (string) - Required - Unique identifier for the webhook event.
- **operation** (string) - Required - Type of operation, e.g., 'LISTING_CONTRACT_FLOW_STARTED'.
- **subdomain** (string) - Required - Subdomain of the EverReal account.
- **language** (string) - Required - Language of the notification.
- **createdAt** (Date) - Required - Timestamp when the event was created.
- **data** (IListingContractFlowStartedAction) - Required - Payload containing details of the started contract flow.

#### IListingContractFlowStartedAction
- **id** (string) - Required - Unique identifier for the contract flow.
- **contractTemplateId** (string) - Optional - Identifier for the contract template used.
- **metadata** (object) - Optional - Additional metadata about the contract.
  - **unitId** (string) - Optional - Identifier for the associated unit.
  - **listingId** (string) - Optional - Identifier for the associated listing.
  - **candidateId** (string) - Optional - Identifier for the associated candidate.
- **contractData** (any) - Optional - Data associated with the contract.
- **status** (CONTRACT_STATUS) - Optional - Current status of the contract.
- **contractFlowType** (CONTRACT_FLOW_TYPE) - Required - Type of contract flow.
- **contractFile** (object) - Optional - Details about the contract file.
  - **name** (string) - Optional - Name of the contract file.
  - **resourcePath** (string) - Optional - Path to the contract file resource.
  - **order** (number) - Optional - Order of the contract file.
  - **size** (number) - Optional - Size of the contract file.
  - **type** (string) - Optional - Type of the contract file.

### Response Example
```json
{
  "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "operation": "LISTING_CONTRACT_FLOW_STARTED",
  "subdomain": "example",
  "language": "en",
  "createdAt": "2023-10-27T10:00:00Z",
  "data": {
    "id": "contract-flow-123",
    "contractTemplateId": "template-abc",
    "metadata": {
      "unitId": "unit-456",
      "listingId": "listing-789",
      "candidateId": "candidate-012"
    },
    "contractData": {
      "key": "value"
    },
    "status": "STARTED",
    "contractFlowType": "LEASE",
    "contractFile": {
      "name": "lease_agreement.pdf",
      "resourcePath": "/path/to/lease_agreement.pdf",
      "order": 1,
      "size": 102400,
      "type": "application/pdf"
    }
  }
}
```
```

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

### JavaScript Example for Querying Users

Source: https://api-docs.everreal.co/endpoints/account-users-members

Provides a JavaScript code snippet using the `fetch` API to perform a GraphQL query for user data. This example illustrates how to set up the request headers, construct the GraphQL query, and handle the response, including error logging.

```javascript
var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer ...");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Cookie", "accept-language=de-DE");

var graphql = JSON.stringify({
  query: "query {\r\n users(input: { paging: { take: 10, skip: 0 }, filter: { email: \"email@domain.co\" } }) {\r\n id\r\n email\r\n }\r\n}",
  variables: {}
})

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: graphql,
  redirect: 'follow'
};

fetch("http://{subdomain}.everreal.co/api/reporting/graphql", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
```

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

### Sample Document Upload Response

Source: https://context7_llms

An example JSON response received after successfully uploading a document. It includes the document's ID, resource path, title, associated property details, media type, size, and timestamps.

```json
{
  "id": "f2d8b7a5-9e58-4347-8864-35243fd952b0",
  "resourcePath": "subdomain/116aeae1-615a-11e7-97db-257f422c1234/properties/117ff3a1-6f1b-4da8-a3da-208d2e6f5ac4/f2d8b7a5-9e58-4347-8864-35243fd952b0",
  "title": "Floor plans",
  "companyId": "116aeae1-615a-11e7-97db-257f422c1234",
  "type": "DOCUMENT",
  "propertyId": "117ff3a1-6f1b-4da8-a3da-208d2e6f5ac4",
  "propertyGroupId": null,
  "unitId": null,
  "tenantId": null,
  "candidateId": "3512f79f-5c99-49ce-a517-df838cce75b7",
  "email": null,
  "mediaType": "image/png",
  "size": 10473459,
  "createdAt": "2023-05-24T09:43:19.043Z",
  "updatedAt": "2023-05-24T09:43:19.043Z"
}
```