PRODA API Docs

API Overview


This guide is meant to show you how to access PRODA's API. The API is meant to enable you to pull standardized tenancy schedule data into your application.

Authentication

The first step to using an API is authentication. PRODA supports two modes of authentication: Web-based authentication and Machine to Machine (M2M) authentication.

  1. Web-based authentication is connected to an existing PRODA user-account. Your web application obtains an access (session-) token by redirecting to the normal PRODA login screen where the user enters their PRODA account credentials.
    When using the token, the PRODA API will assign permissions (which databases are visible) to match those of the user account that was used to obtain the token.
    See the guide on accessing the PRODA API using Web-based authentication
  2. Machine-to-Machine (M2M) authentication is intended to be used from your backend; it can be configured to get access to any data belonging to your PRODA company.
    Authentication happens using an ID/Secret pair that PRODA support will provide for your company. This token must not be shared with third-parties, so you should only store it in your backend. The advantage to this approach is that it can be fully automated, so you can e.g. synchronize data uploaded to your PRODA databases to your servers every hour without needing to manually log-in. This does not use PRODA user accounts so you'll have to handle permissions for your users on your end if required.
    See the guide on using machine-to-machine authentication

Endpoint reference

No matter how you choose to authenticate, you will be using the same endpoints. These are described in more detail in the endpoint reference docs.

Download the Postman collection to get started with the PRODA API quickly.

See recent changes to API functionality in the API Changelog.

Webhooks

Webhooks allow your application to react to changes on PRODA in near real-time.

See the guide and the webhook-related endpoints.

Writing an app that syncs all data from PRODA to your databases

This section will lay out a procedure which fetches all the data from PRODA while minimising data transfer. Note that realistically you should be using webhooks for this instead of polling. This is for illustration purposes only.

The app should roughly run the following:

  1. Query your database or storage layer for the last used access token. If it doesn't exist, retrieve one and store it.
  2. Hit the databases-list endpoint to get a list of available company databases.
    • If the server returns HTTP 401, it means the access token has expired. Remove your access token from your storage layer and go back to step 1.
  3. With the list of available company databases, it is time to fetch all existing properties through the properties endpoint.
    • You can now write all properties to your own database, delete missing and update existing ones. Remember to cascade deletes to all dependent data, including rent rolls and units.
    • It is possible a property was deleted in PRODA and recreated, making a property that is essentially the same you had before look like it has a new ID. This case is handled by doing what the item above suggests, which will delete the previous property from your database and add a new one.
  4. After synchronising properties, it is time to do the same to rent rolls through the rentrolls endpoint.
    • All the same observations about new, modified and existing properties apply to rent rolls.
    • One important attribute of rent rolls is lastApprovedAt. If any edits are made to a rent roll in PRODA, this attribute will be updated to when those changes were completed. So you probably want to store that attribute as well.
  5. With rent rolls in hand, it is time to fetch unit level data through the query endpoint.
    • Remember: you only need to fetch data from rent rolls which are new or had their lastApprovedAt field changed since your last check.
    • You can fetch data from multiple rent rolls in a single request by using this endpoint's filtering capabilities. We recommend making one request per `extractionId`/`extraction_id`. This will return data in the same chunk size as it has been uploaded.
    • One question is which columns to choose. Make sure to check the column-list endpoint and what your requirements are for that. If you are using webhooks, you will usually want to store the extraction_id and rentroll_id columns so you can easily update data when it changes on PRODA.
    • One simple thing you can do is to delete every unit from synced rent rolls and reinsert the ones received in this API call.
    • If you want to fetch monetary values in each rent roll's native currency use "fxCurrency": "source". If you want to show aggregated values, you will need to either request conversion to a single currency, e.g., "fxCurrency": "EUR", or divide units by primary_currency and aggregate them separately.
  6. Wait a few minutes or more and start over from step 1. How much time you wait depends on how quickly you need your data to be up to date with PRODA.

Try our API in this page

You can experiment with our API in this very page if you have a PRODA account. This relies on web-based authentication, but you'll be handling the same request/response formatting in either case.
To start, log in by clicking the button below. You'll be redirected back to this page and be able to click buttons that use the API with your data from https://app.proda.ai.