About the API

Write Requests

Write requests are used to create or update data.

Overview

With Propexo, you can move data to and from your customers’ Property Management Systems (PMS). To understand how Propexo handles write requests, it is important to understand how we think about source-of-truth relationships.

Source of Truth

Propexo does not act as the source of truth. Instead, we rely on each PMS to maintain accurate records. This means that when you write data to Propexo’s API, we will pass the request along to the PMS. The data in Propexo’s caching layer will remain in it’s original form (prior to your update) until we receive the updated record back from the PMS during your next sync window. We request an updated version of that record right away so that the cached data in Propexo is as fresh as possible. Since this is not enabled for all models across all PMSs, please ask us about this feature for your use case.

Generic Endpoints

As a unified API solution, Propexo offers generic endpoints for all write (POST & PUT) requests. This means that you can use the same endpoint, regardless of the Property Management System. However, different PMSs require or restrict different sets of data in the request payload which introduces an element of complexity in maintaining a single entry point. To address this, Propexo has developed some utilities (outlined below) to help with your development process.

How do generic endpoints work?

Generic endpoints are designed to be a single point of entry across all Property Management Systems. For example, if you want to update a value on the applicant model, you would request a PUT to /applicants/{id}. Under the hood, Propexo will perform a lookup in our database to determine which PMS is associated with the passed id, and we will automatically proxy the request to the appropriate PMS. We will then validate your request payload against that specific PMSs requirements for updating an applicant.

Generic Endpoint Utilities

  • Private Documentation — Propexo maintains a private documentation site (for customers only) that contains all of the information you need to know about the data models and endpoints for each PMS. This documentation is available to all of our customers and is updated regularly as we add new PMSs and features. These private docs address the following:

    • Granular PMS functionality — Not all functionality is permitted by every PMS. For example, some PMSs allow you to update a notes field on the residents model, but some do not. This could impact your development plans, so it is important to know what is and is not possible with each PMS. Our private docs detail which fields are and are not available for each PMS.
    • High Level PMS functionality — In addition to granular functionality, we also provide a high level overview of the functionality available for each PMS. For example, some PMSs allow you to create (POST) a new unit, while many do not. Propexo’s private docs will inform you when certain high level functionality is not permitted by a PMS API.

  • Validation Utility — There are cases where you may want to force a request payload that does not meet validation requirements for a certain PMS, but would be ok for another PMS. For example, our generic PUT /residents endpoint exposes a notes field that is not available on all PMSs. If you have customers using BUILDIUM (who supports notes on residents) and others using RENT MANAGER (who does not support notes on residents), you can still use the generic endpoint and append ?ignore_unknown_fields=true to each request against the generic PUT /residents endpoint. That way, you do not need to code against individual PMSs. Propexo will accept your request payload with notes and we will pass it through to BUILDIUM and strip it out for RENT MANAGER. If you do not append the ?ignore_unknown_fields=true query string param, you will receive a 400 error response when attempting to update the notes field for a RENT MANAGER customer.

Checking the status of write requests

Propexo makes sure to validate the input data for write requests as much as possible at our API so you can be informed of any possible errors as soon as possible.

However, there are some issues that involve data we don’t have access to that will fail during our asynchronous write request to the PMS directly. For example, if you’re updating a resident to be on a different lease, it’s possible that Propexo doesn’t currently have all the details on that individual and they may have already been reassigned within the PMS directly. In a case like this, Propexo will encounter and record the error.

To see this error, you can use our write operation status endpoint (GET /v1/admin/write-status/:root_job_id), where root_job_id is the job_id field returned from a successful write operation request to the Propexo API:

1{
2    "meta": {
3        "job_id": "cm4ublxhn5008550276138abyzlg821i"
4    },
5    "result": {}
6}

This endpoint will return whether or not the write operation was successful, any errors that were encountered, and the IDs of any records that were created due to the write operation.

Due to the asynchronous nature of Propexo syncs and write operations, it’s always possible for data have to been modified between the time you attempt to write it and the time the data was last read into our system or modified by the source. We recommend polling this endpoint after a write operation to ensure the data was written as expected.