Document management

Endpoints to upload documents to EverReal and link them to different objects

Introduction

Important notes

• Documents represents files that are uploaded and have metadata that link them to different objects in EverReal. Documents can be linked to tenants, units, properties, property groups. If you want to upload files and link them to listings later, please read the Simple file upload section.

• Documents need to have a resourcePath that is a "virtual folder" in EverReal. Recommended resource paths

  • Tenant documents: tenants/$tenantId

  • Property documents: properties/$propertyId

  • Unit documents: units/$unitId

  • property group documents: properties/$propertyId - documents attached to a property group should also be attached to a property as well

Endpoints

Upload a document with metadata

Uploading a document is a multipart/form-data operation that can pass via multipart parameters several required or optional parameters.

Please note that the field metadata needs to be passed as string JSON and can contain the following data:

// The type of document
type?: DOCUMENT_TYPES;
// Link a document to a tenant by id
tenantId?: string;
// Link the document to a unit by id
unitId?: string;
// Link the document to a property by id
propertyId?: string;
// Link the document to a property group by id
propertyGroupId?: string;

enum DOCUMENT_TYPES {
  // default document type
  DOCUMENT = "DOCUMENT",
  // rental application of a tenant, passed during rental process
  RENTAL_APPLICATION = "RENTAL_APPLICATION",
  // contract with a tenant or buyer
  CONTRACT = "CONTRACT",
  // move-in protocol
  MOVE_IN = "MOVE_IN",
  // move-out protocol
  MOVE_OUT = "MOVE_OUT",
  // pre-move-in protocol
  PRE-MOVE_IN = "PRE-MOVE_IN",
  // selling protocol
  SELLING = "SELLING",
}

Sample response

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

// afterwards the file will be accessible at 
// https://resources.everreal.co/subdomain/116aeae1-615a-11e7-97db-257f422c1234/properties/117ff3a1-6f1b-4da8-a3da-208d2e6f5ac4/f2d8b7a5-9e58-4347-8864-35243fd952b0

Upload a document with metadata

POST https://{custom_subdomain}.everreal.co/api/file-storage/company/documents

The parameters are passed via form data and are listed below.

Request Body

Name	Type	Description
file*	form Data File	File buffer
resourcePath*	String	Example: /protocols/:id
metadata*	String	String metadata as json string, example {\"propertyId\": \"{propertyId}\", \"unitId\": \"{unitId}\"}
name	String	Force another file name
format	ENUM	JPEG,PNG . Will force the conversion to JPEG or PNG of any image.

201: Created Create id is in "Location" header

401: Unauthorized

400: Bad Request

cURL

The example below will upload a file and attach it to a property and unit by passing metadata as string JSON.

curl --location "${BASE_URL}/api/file-storage/company/documents" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--form 'file=@"file blob multipart"' \
--form 'resourcePath="units/{unitId}"' \
--form 'name="Floor plans"' \
--form 'metadata="{\"propertyId\": \"{propertyId}\", \"unitId\": \"{unitId}\"}"'

Typescript

The example below will upload a file and attach it to a property and unit by passing metadata as string JSON.

const uploadFile = (input: { fileInput: Buffer; accessToken: string; propertyId: string; unitId: string }) => {
  const { fileInput, accessToken, propertyId, unitId } = input;
  const myHeaders = new Headers();
  myHeaders.append('Accept', 'application/json');
  myHeaders.append('Authorization', `Bearer ${accessToken}`);

  const formdata = new FormData();
  formdata.append('file', fileInput, { filename: 'Sample-png-image-10mb.png', contentType: 'image/png' });
  formdata.append('resourcePath', `units/${unitId}`);
  formdata.append('name', 'Move-in protocol John Doe, Unit 1');
  formdata.append('metadata', JSON.stringify({ propertyId, unitId, type: 'MOVE_IN' }));

  const requestOptions  = {
    method: 'POST',
    headers: myHeaders,
    body: formdata,
    redirect: 'follow',
  };

  fetch(`{baseUrl}/api/file-storage/company/documents`, requestOptions)
    .then((response) => response.text())
    .then((result) => console.log(result))
    .catch((error) => console.log('error', error));
};

Java

The example below will upload a file and attach it to a property and unit by passing metadata as string JSON.

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
  .addFormDataPart("file","Sample-png-image-10mb.png",
    RequestBody.create(MediaType.parse("application/octet-stream"),
    new File("/pathtofile/Sample-png-image-10mb.png")))
  .addFormDataPart("resourcePath","properties/117ff3a1-6f1b-4da8-a3da-208d2e6f5ac4")
  .addFormDataPart("name","Floor plans")
  .addFormDataPart("metadata","{\"propertyId\": \"117ff3a1-6f1b-4da8-a3da-208d2e6f5123\",\"unitId\": \"117ff3a1-6f1b-4da8-a3da-208d2e6f5567\"}")
  .build();
Request request = new Request.Builder()
  .url("{baseUrk}/api/file-storage/company/documents")
  .method("POST", body)
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer {accessToken}")
  .build();
Response response = client.newCall(request).execute();

C#

The example below will upload a file and attach it to a property and unit by passing metadata as string JSON.

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, baseUrl + "/api/file-storage/company/documents");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "Bearer " + accessToken);
var content = new MultipartFormDataContent();
content.Add(new StreamContent(File.OpenRead("/pathtofile/Sample-png-image-10mb.png")), "file", "/pathtofile/Sample-png-image-10mb.png");
content.Add(new StringContent("properties/117ff3a1-6f1b-4da8-a3da-208d2e6f5ac4"), "resourcePath");
content.Add(new StringContent("Floor plans"), "name");
content.Add(new StringContent("{\"propertyId\": \"117ff3a1-6f1b-4da8-a3da-208d2e6f123\", \"unitId\": \"117ff3a1-6f1b-4da8-a3da-208d2e6f5567\"}"), "metadata");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Delete a document by id

Deletes a document by id

DELETE https://{custom_subdomain}.everreal.co/api/file-storage/company/documents/{documentId}

Path Parameters

Name	Type	Description
documentId	String

401: Unauthorized

404: Not Found

204: No Content

Get all documents metadata and / or apply filters

Get all documents metadata from a company and filter

GET https://{custom_subdomain}.everreal.co/api/file-storage/company/documents/metadata

Can get all documents metadata from an account and filter by certain parameters passed via query string. The response can be used to display a list of documents or to query via resourcePath and download the files.

Query Parameters

Name	Type	Description
unitId	String
propertyId	String
propertyGroupId	String
candidateId	String
tenantId	String
types	Array String	See documentation above for available values
skip	Number	How many items should skip
take	Number	Ho many items should take.
propertyGroupId	String
title	String
tenantId	String

200: OK

[{
    "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"
}]

401: Unauthorized

Get document metadata by id

Get a single document metadata

GET https://{custom_subdomain}.everreal.co/api/file-storage/company/documents/{documentId}/metadata

200: OK

401: Unauthorized

404: Not Found