Introduction

The GRESB API is used to submit data for the GRESB Real Estate assessment. Applications can receive historical data when authorised by a given entity. Data needs to be submitted for the asset and portfolio. Asset data is aggregated to the portfolio level (Real Estate assessment) where subsequently evidence is added to support the submitted data. Asset data consists of utility data reflecting the performance of the portfolio. Provided per building, across energy, GHG, water, and waste, for the last two years of data. Portfolio data consists of Management, Performance, and Development indicators which consist of checkboxes, radiobuttons, text fields, and evidence. See the Real Estate Reference Guide for more information.

For testing the API, we suggest using one of the following tools:

We created a Postman collection which you can use to test the different endpoints. It is not yet fully covering all the different indicator variables of the Real Estate assessment and will be updated at a later stage.

For the data mapping exercise on the portfolio level, you can make use of Real Estate Assessment variables. This file presents most of the variables of a response along with their description, data type, and accepted values.

Basic Operations

For all API actions below the same basic principles apply:

All API actions are over HTTPS. The API is designed in the spirit of REST. JSON is the primary encoding used for content. Access tokens are used to authenticate your application to the API and authorize access to our user's entities.

Endpoints

The API is versioned. With the introduction of portfolio-level endpoints, the current application uses both v0 and v1. This means the base URLs are:

Testing Sandbox: https://demo-api.gresb.com/api/v0 for portfolio-level, and https://demo-api.gresb.com/api/v1 for asset-level API endpoints. Please be aware that any UI functionalities (i.e. login) are hosted on https://demo-portal.gresb.com.
Production: https://api.gresb.com/api/v0 for portfolio-level, and https://api.gresb.com/api/v1 for asset-level API endpoints. Please be aware that any UI functionalities (i.e. login) are hosted on https://portal.gresb.com.

The following paths/endpoints are available:

Path	HTTP verbs/methods	Version
/certifications	GET	v1
/entities	GET	v1
/entities/{entity_id}	GET	v1
/entities/{entity_id}/assets	GET, POST	v1
/entities/{entity_id}/assets/{gresb_asset_id}	GET, PATCH, DELETE	v1
/entities/{entity_id}/assets/batches	POST	v1
/lists	GET	v0
/lists/:slug	GET	v0
/entities/{entity_id}/responses	GET	v0
/entities/{entity_id}/responses/{response_id}	GET	v0
/entities/{entity_id}/responses/{response_id}/values/{variable}	GET, POST	v0
/entities/{entity_id}/responses/{response_id}/documents	POST	v0

Common HTTP Verbs

There are four HTTP verbs we use in the API:

GET - Get a resource or a list of resources. If successfull a 200 OK status code will be returned along with the results. A GET request is safe and never modifies data on the server and can always be retried if a network error occurs.
PATCH - Update an existing resource with new values. The request can contain a partial representation of the resource, meaning only the provided fields/attributes will be updated.
POST - Create a new resource or trigger a process with side-effects such as importing asset level data. If a new resource is created a 201 Created status code will be returned along with the new resource. If a more complex action is successfully trigged a 200 OK status will be returned along with action specific details. If an error occurs doing a POST request the action may or may not have been completed and so retrying it may trigger additional side effects or attempt to create additional resources.
DELETE - Delete an existing resource. If successful 200 OK status code will be returned along with the last snapshot of the resource. DELETE requests are idempotent and can safely be retried for the same effect.

In all cases an error on the part of the client or server could also occur. The very common status of 422 Unprocessable Entity indicates some sort of validation error and 404 Not Found typically indicates an invalid resource URI (e.g. the resource may have been deleted). Other likely codes are below but any HTTP 1.1 code could occur.

Common HTTP Status Codes

Standard HTTP status codes indicate success or failure of an API request.

Codes in the 200s indicate success
Codes in the 400s indicate error in your request
Codes in the 500s indicate an error with GRESB's servers

Code	Text	Description
200	OK	Command was a success. The response body may include the result.
201	Created	Command was a success and a new resource has been created. The response body may include the result.
204	No Content	Command was a success. There is no futher content available.
301	Moved Permanently	The request included an older API version that is no longer supported.
400	Bad Request	The request was invalid. Often there is a missing parameter. An accompanying error message with further information may be provided.
401	Unauthorized	Authentication credentials were missing or invalid. See authorization for more assistance.
403	Forbidden	The request was refused because your account did not receive permission to complete this action.
404	Not Found	The requested item does not exist.
422	Unprocessable Entity	The request to create or update a resource resulted in validation errors. Error details are returned in the response body.
429	Too Many Requests	The request was refused due excessive use. The batch endpoint is rate-limited to prevent abuse. Usage is tracked per access token.
5xx	Serverside Error	An error has occurred on our servers. Please wait a few minutes and try again or notify us if the errors persists.

Request and Response Encoding

Request parameters should be provided using the application/json Content-Type. The only exception is the IDs of entities or assets which are part of the URLs.

Unless otherwise documented all responses are JSON-encoded. Content-Type: application/json.

Date formats

All date values send to the API must be ISO 8601 formatted (YYYY-MM-DD). Requests with incorrect format on any date fields will be rejected and an error is shown. This rule won't apply if empty values ("" or null) for date fields are given.

API Authorization

The GRESB API requires an access token to make requests to the several endpoints. These access tokens are created through your data partner account in the GRESB Portal and are unique to your application. The process for creating access token is outlined below.

Manage data partner account

Before you will be able to create access tokens, a GRESB data partner account has to be assigned to your GRESB Portal user account. In order to verify if this is the case you will have to login to https://portal.gresb.com/ and confirm that you have the 'Data Partners' tab on the navigation menu.

access data partner account

Your data partner account is where you manage your tokens and users. Any user associated with this account can access the page.

data partner page

When you generate a new token you can give it a name and expiration date. An access token can at most be valid for 1 year.

generate new token

Once generated be sure to copy your access token.

copy token

After generating a number of tokens you'll see an overview in your data partner account. You can delete tokens at any moment in time. After the expiration date they automatically get deactivated.

see tokens

Provide access to data partner

Once you have your data partner account set up your clients need to provide you with access. This is done through their user accounts. When they login they will see an overview of their GRESB reporting entities. For each entity they will need to provide your data partner account with access. This is done one at a time.

participant entities

Once they clicked on one of their reporting entities the will need to go to the 'Data Partner Access Rights' tab.

participant responses

In this page they can grant access to a data partner by selecting the data partner from the list. They can also revoke access at any given time.

grant access

select data partner

granted access

OAuth flow

An OAuth application can be created through your data partner account. Subsequently OAuth can be used to ask a user to grant access. This will then provide access through OAuth for the entities the user has access to. This will only work if the entities are also connected to your data partner account (see previous section). This is meant to secure user permission and saves you the exercise of mapping entities to your own internal platform. Since you can simply show to the user what is returned through OAuth.

An OAuth application can be created through your data partner account.

oauth data partner

If you want to alter the id or change the name you can always return back to your data partner account and edit the OAuth application.

The token generated after the user authorizes your application expires after 2 hours. This then needs to be refreshed, which requires the user to authorize your application again. If the user is still logged in to the GRESB Portal this will not prompt the user to login again.

Obtain OAuth 2.0 Credentials

Before receiving an access token, you must register your application and obtain OAuth credentials. This will include a unique client_id and client_secret. First, ensure that you are logged into your GRESB account, then add your application to your data partner account. You will need to include a name and one or more redirect URIs.

oauth new application

Sample Application

oauth id secret

You may register as many applications as you like.

Requesting API Access

To use OAuth, you must receive authorization from your users to access their entities. There are many ways to do this. This step is typically handled using a client library (see Client Libraries at http://oauth.net/2/ for examples in many languages). We support the following standard flows:

Authorization Code Grant Flow - Often used for Web Applications (server-side)

OAuth Scopes

OAuth allows you to request different levels of access to a user's account. By default all applications are granted access to the public scope. For the GRESB API that doesn't allow access to any user data. To use the API in a meaningful way, you need to request one or more of the following scopes:

Scope	Access	Endpoints
entities	Read access to entities	`GET /entities` and `GET /entities/{entity_id}`
read:assets	Read access to assets	`GET /entities/{entity_id}/assets` and `GET /entities/{entity_id}/assets/{asset_id}`
write:assets	Write access to assets	`POST /entities/{id}/assets`, `PATCH/DELETE /entities/{id}/assets/{id}`, `POST /entities/{entity_id}/assets/batches`
read & write:responses	Read and write access to responses	`GET entities/{entity_id}/responses/`, `GET entities/{entity_id}/responses/{entity_id}` and `POST entities/{entity_id}/responses/{response_id}`

If your user is not already signed in to their GRESB account they will be prompted to sign in or create a new account. Once signed in, the user will then be shown an authorization request with the option to 'Authorize' or 'Deny' your application access.

Example: Web Applications

As an example we will describe in detail the Authorization Code Grant Flow for a web application. This is the most secure method to authorize your application. It is also the most complex and is made simpler by using an OAuth client library.

Step 1 - Request Authorization

An account and reporting entities for the participant user needs to be created on https://portal.gresb.com. The first time you grant a user access to the GRESB API via your application, link the user to https://portal.gresb.com/oauth/authorize, passing the following parameters:

your application's client_id
one of your application's registered redirect_uris
response_type=code
the access scope you need

The full URL should look like this:

https://portal.gresb.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=https://www.example.com/oauth2/callback&response_type=code&scope=write:assets

If you are testing this on the testing environment, you can use the "Authorize" button, to simulate this step:

authorize test app

Authorization Code Screen:

The user will be requested to authorize or deny access to your application:

authorization screen

If the user denies your request you will receive a request at the redirect_uri with error and error_description parameters:

https://www.example.com/oauth2/callback?error=access_denied&error_description=User+denied

If the user authorizes your request you will receive a request at the redirect_uri with the authorization code in the code parameter. You will use this to request an access_token. The authorization code will expire in 10 minutes. Once expired a fresh code must be requested. For example if your redirect_uri was http://example.com/oauth2/callback you should expect a callback to:

https://www.example.com/oauth2/callback?code=AUTHORIZATION_CODE

Note: It is also possible to use the urn:ietf:wg:oauth:2.0:oob as a redirect_uri. Doing this will display the code to the user in a webpage and ask them to copy and paste it into your application's configuration. This might be useful during testing or if your application does not have a web server component.

authorization code screen

It is important to remember that users may revoke your application's access at any time. The easiest course of action if this happens is to request access again starting at Step 1.

Step 2 - Exchange Authorization Code for Access Token

curl \
  -F "client_id=$CLIENT_ID" \
  -F "client_secret=$CLIENT_SECRET" \
  -F "code=$AUTHORIZATION_CODE" \
  -F "grant_type=authorization_code" \
  -F "redirect_uri=urn:ietf:wg:oauth:2.0:oob" \
  -X POST https://api.gresb.com/oauth/token

{
  "access_token":"0123456789abcdef...",
  "token_type":"bearer",
  "expires_in":7200,
  "scope":"write:assets"
}

curl \
  -F "access_token=$ACCESS_TOKEN" \
  -X POST https://api.gresb.com/oauth/token/info?

{
  "resource_owner_id":1234,
  "scope":["public","write:assets"],
  "expires_in":7200,
  "application": {
    "uid":"d26b1521a034a2e4cfc6372b0db51e6790421e1fd00fd97d5a0d923fe67b685b"
  },
  "created_at":1548944742
}

You can now request an access token by issuing a POST request to /oauth/token. You must include grant_type=authorization_code, your client_id, client_secret, and the authorization code as parameters to your request. In return you will receive an access_token for you application.

POST /oauth/token?client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&code=$AUTHORIZATION_CODE&redirect_uri=urn:ietf:wg:oauth:2.0:oob

Step 3. Use Access Token

The access token can now be used to make requests to the GRESB API. The token must be included either as a Authorization: Bearer HTTP header, or as a request parameter named access_token.

As an HTTP Header:

curl https://api.gresb.com/api/responses -H 'Authorization: Bearer $ACCESS_TOKEN'

As a request parameter:

curl https://api.gresb.com/api/responses?access_token=$ACCESS_TOKEN

OAuth Errors

Common

invalid_request: 'The request is missing a required parameter, includes an unsupported parameter - value, or is otherwise malformed.'
invalid_redirect_uri: 'The redirect uri included is not valid.'
unauthorized_client: 'The client is not authorized to perform this request using this method.'
access_denied: 'The resource owner or authorization server denied the request.'
invalid_scope: 'The requested scope is invalid, unknown, or malformed.'
server_error: 'The authorization server encountered an unexpected condition which prevented it from fulfilling the request.'
temporarily_unavailable: 'The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server.'

Access Grant Errors

unsupported_response_type: 'The authorization server does not support this response type.'

Access Token Errors

invalid_client: 'Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method.'
invalid_grant: 'The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.'
unsupported_grant_type: 'The authorization grant type is not supported by the authorization server.'

Password Access Token Errors

invalid_resource_owner: 'The provided resource owner credentials are not valid, or resource owner cannot be found'

Invalid Tokens

unknown: "The access token is invalid"

View-only UI

After you have been given access to a reporting entity you will have view-only access to the data forms in the UI. This allows you to see the data uploaded through the API endpoints, as the client would see it. This is especially helpful for the Real Estate assessment, since our current portfolio endpoint does not respond with validation. As such when you access your user account you will see an overview of reporting entities.

data partner entities

When you click on one of the reporting entities you will be able to access the 'Asset Portal' and 'Response'. The asset portal is for viewing the asset data, whereas the response of the GRESB Assessment is for viewing the portfolio data.

view-only data forms

Reporting Entities

For testing purposes, you can create a reporting entity, using the GRESB sandbox portal.

GET /entities

Returns all the entities to which the data partner has access.

curl https://api.gresb.com/api/v1/entities \
  -H "Authorization: Bearer $ACCESS_TOKEN"

[
   {
      "id": {entity_id},
      "name": "API Test Entity",
      "manager": "GRESB",
      "hq_country_code": "NL",
      "hq_country_name": "Netherlands",
      "address": "Barbara Strozzilaan 374",
      "reporting_preferences":    
         {
            "currency": "EUR",
            "area_units_name": "Square Meters",
            "reporting_period": "fiscal",
            "reporting_period_month": 4,
            "reporting_period_month_name": "April"
         },
      "created_at": {date},
      "updated_at": {date}
   },
   {
      "id": {entity_id_2},
      "name": "API Test Entity 2",
      "manager": "GRESB",
      "hq_country_code": "NL",
      "hq_country_name": "Netherlands",
      "address": "Barbara Strozzilaan 374",
      "reporting_preferences":    
         {
            "currency": "EUR",
            "area_units_name": "Square Meters",
            "reporting_period": "fiscal",
            "reporting_period_month": 4,
            "reporting_period_month_name": "April"
         },
      "created_at": {date},
      "updated_at": {date}
   }
]

GET /entities/{entity_id}

Similar to the above, but returns the details on a specific entity, identified by the ID in the URL.

curl https://api.gresb.com/api/v1/entities/{entity_id} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
   "id": {entity_id},
   "name": "API Test Entity",
   "manager": "API Tester",
   "hq_country_code": "NL",
   "hq_country_name": "Netherlands",
   "address": "Barbara Strozzilaan 374",
   "reporting_preferences":    
      {
         "currency": "EUR",
         "area_units_name": "Square Meters",
         "reporting_period": "fiscal",
         "reporting_period_month": 4,
         "reporting_period_month_name": "April"
      },
   "created_at": {date},
   "updated_at": {date}
}

Asset Data

Asset data can be posted via the assets endpoint. The data consists of building characteristics and annual data. Building characteristics are constant over time, whereas annual data changes annually. Some data is only valid for the most current of the two reporting years, other data is valid for both years.

Building characteristics:

gresb asset identifier
location specifics (e.g. city, address, latitude)
construction year
building certifications
energy ratings
asset ownership
asset size

Annual data:

yearly asset characteristics (i.e. property type, asset name)
efficiency measures
reporting characteristics
energy consumption
ghg emissions
water consumption
waste disposal

You may submit data for any number of buildings for your user, in one or more of the aforementioned sections. The respondent may also provide data on other assets or for the same assets but in different sections. The data you access through the API is not specific to your application and include data on the respondent's other assets or sections. In other words, you can access assets from a common pool - as long as the assets are part of the same entity. It is the responsibility of the respondent to make sure that data submitted from multiple API partners does not conflict with each other. This API is designed to meet the needs of applications that upload data to GRESB in real-time or as a batch.

GET /entities/{entity_id}/assets

curl https://api.gresb.com/api/v1/entities/{entity_id}/assets \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Returns the assets of the entity specified in the URL, along with any annual data (if available).

[
    {
        "gresb_asset_id": {asset_id},
        "country": "NL",
        "state_province": "North Holland",
        "city": "Amsterdam",
        "address": "Barbara Strozzilaan 374",
        "lat": 52.335915637320596,
        "lng": 4.889755053768094,
        "partners_id": 123456,
        "construction_year": 1800,
        "asset_ownership": 55,
        "certifications":    [
            {
            "id": {unique_id},
            "certification_id": 598,
            "name": "BCA Green Mark/Existing Buildings",
            "level": "Platinum",
            "size": 230,
            "year": 2017,
            "_validations": {"errors": {}}
            }
        ],
        "asset_size": 5000.0,
        "annual_data":    [
            {
                "year": {reporting_year - 1},
                "asset_size": 5000,
                "asset_name": "API Created Asset",
                "en_tot_wd": 4000,
                "en_tot_we": 900,
                "en_tot_wf": 100,
                "ghg_tot_s3_w": 5000,
                "ncmr_status": "Standing Investment",
                "owned_entire_period": true,
                "property_type_code": "HTL",
                "tenant_ctrl": true,
                "was_pcov": 0,
                "wat_tot_w": 5000,
                "whole_building": true,
                "asset_vacancy":0,
                "_validations": {
                    "errors": {}}
            }
        ],
        "_outliers": [],
        "created_at": {date},
        "updated_at": {date},
    },
    {
        "gresb_asset_id": {asset_id_2},
        "country": "US",
        "state_province": "DC",
        "city": "Washington, DC",
        "address": "1900 Pennsylvania Avenue NW",
        "lat": null,
        "lng": null,
        "partners_id": 123456,
        "construction_year": 1792,
        "asset_ownership": null,
        "certifications": [
            {
                "id": {unique_id_2},
                "certification_id": 1140,
                "name": "2000-Watt/Site - Operational",
                "level": null,
                "size": 123,
                "year": 2017,
                "_validations": {
                    "errors": {}
                }
            }
        ],
        "asset_size": 5000.0,
        "annual_data": [
            {
                "year": {reporting_year - 1},
                "asset_size": 5000,
                "asset_name": "The White House",
                "asset_vacancy": 0,
                "en_tot_wd": 4000,
                "en_tot_we": 900,
                "en_tot_wf": 100,
                "ghg_tot_s3_w": 5000,
                "ncmr_status": "Standing Investment",
                "owned_entire_period": true,
                "property_type_code": "HTL",
                "tenant_ctrl": true,
                "was_pcov": 0,
                "wat_tot_w": 5000,
                "whole_building": true
            },
            {
                "year": {reporting_year - 2},
                "asset_size": 5000,
                "asset_name": "The White House",
                "asset_vacancy": 0,
                "en_tot_lc_te": 112.4,
                "en_tot_wd": 4000,
                "en_tot_we": 900,
                "en_tot_wf": 100,
                "ghg_tot_s3_w": 5000,
                "ncmr_status": "Standing Investment",
                "owned_entire_period": true,
                "property_type_code": "OCHI",
                "tenant_ctrl": true,
                "was_pcov": 0,
                "wat_tot_w": 5000,
                "whole_building": true
            }
        ],
        "_outliers": [],
        "created_at": {date},
        "updated_at": {date}
    }
]

GET /entities/{entity_id}/assets/{asset_id}

curl https://api.gresb.com/api/v1/entities/{entity_id}/assets/{asset_id} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Returns the asset specified in the URL, along with its annual data (if available).

{
    "gresb_asset_id": {asset_id},
    "country": "NL",
    "state_province": "North Holland",
    "city": "Amsterdam",
    "address": "Barbara Strozzilaan 374",
    "lat": 52.335915637320596,
    "lng": 4.889755053768094,
    "partners_id": 123456,
    "construction_year": 1800,
    "asset_ownership": 55,
    "certifications": [
        {
            "id": {unique_id},
            "certification_id": 598,
            "name": "BCA Green Mark/Existing Buildings",
            "level": "Platinum",
            "size": 230,
            "year": 2017
        }
        ],
    "annual_data": [
        {
            "year": {reporting_year - 1},
            "asset_size": 5000,
            "asset_name": "API Created Asset",
            "en_tot_wd": 4000,
            "en_tot_we": 900,
            "en_tot_wf": 100,
            "ghg_tot_s3_w": 5000,
            "ncmr_status": "Standing Investment",
            "owned_entire_period": true,
            "property_type_code": "HTL",
            "tenant_ctrl": true,
            "was_pcov": 0,
            "wat_tot_w": 5000,
            "whole_building": true,
            "asset_vacancy":0
        },
        {
            "year": {reporting_year - 2},
            "asset_name": "API Created Asset",
            "asset_size": 5000,
            "en_tot_wd": 4000,
            "en_tot_we": 900,
            "en_tot_wf": 100,
            "ghg_tot_s3_w": 5000,
            "ncmr_status": "Standing Investment",
            "owned_entire_period": true,
            "tenant_ctrl": true,
            "was_pcov": 0,
            "wat_tot_w": 5000,
            "whole_building": true,
            "asset_vacancy":0,
            "property_type_code": "OCHI",
            "en_tot_lc_te": 112.4
        }
    ]
}

POST /entities/{entity_id}/assets

Creates a new asset for the specified entity in the URL. Returns the created asset, along with any validation errors and warnings.

Some validation errors will prevent the asset from being created. Check the gresb_asset_id to verify that an asset is created and has unique ID assigned.

country, state_province, city, and asset_ownership are fields required to create an asset and all are posted year agnostically. Other mandatory fields are asset_size, property_type_code and asset_name, however they are reported per year, under annual_data.

If no record for that year is available, a new one will be created. Old records will be updated but won't have any effect on past surveys and rankings. You can update data for up to 5 years prior to the Assessment year.

For certifications we require the certification_id and the size (the size of your asset that received the certification). If a certification is divided in multiple levels, we also require the level.

Notice the gresb_asset_id in the response. This is a unique ID generated from the API, if the asset is complete (no validation errors). It's highly recommended to keep this ID in your database, as it's the only way to identify the new asset. You don't have to provide it in the response, in fact it is ignored, if you do.

For a complete list of fields, and their meaning, see the Data Dictionary.

To bulk-create more than a few assets, please submit a Batch Operation.

curl -X POST https://api.gresb.com/api/v1/entities/{entity_id}/assets \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<JSON

{
    "country": "NL",
    "state_province": "North Holland",
    "city": "Amsterdam",
    "address": "Barbara Strozzilaan 374",
    "lat": 52.335915637320596,
    "lng": 4.889755053768094,
    "partners_id": 123456,
    "construction_year": 1800,
    "asset_ownership": 55,
    "certifications": [
        {
            "id": {unique_id},
            "certification_id": 598,
            "name": "BCA Green Mark/Existing Buildings",
            "level": "Platinum",
            "size": 230,
            "year": 2017
        }
        ],
    "annual_data": [
        {
            "year": {reporting_year - 1},
            "asset_size": 5000,
            "asset_name": "API Created Asset",
            "en_tot_wd": 4000,
            "en_tot_we": 900,
            "en_tot_wf": 100,
            "ghg_tot_s3_w": 5000,
            "ncmr_status": "Standing Investment",
            "owned_entire_period": true,
            "property_type_code": "HTL",
            "tenant_ctrl": true,
            "was_pcov": 0,
            "wat_tot_w": 5000,
            "whole_building": true,
            "asset_vacancy":0
        },
        {
            "year": {reporting_year - 2},
            "asset_name": "API Created Asset",
            "asset_size": 5000,
            "en_tot_wd": 4000,
            "en_tot_we": 900,
            "en_tot_wf": 100,
            "ghg_tot_s3_w": 5000,
            "ncmr_status": "Standing Investment",
            "owned_entire_period": true,
            "tenant_ctrl": true,
            "was_pcov": 0,
            "wat_tot_w": 5000,
            "whole_building": true,
            "asset_vacancy":0,
            "property_type_code": "OCHI",
            "en_tot_lc_te": 112.4
        }
    ]
}

{
    "gresb_asset_id": {asset_id},
    "country": "NL",
    "state_province": "North Holland",
    "city": "Amsterdam",
    "address": "Barbara Strozzilaan 374",
    "lat": 52.335915637320596,
    "lng": 4.889755053768094,
    "partners_id": 123456,
    "construction_year": 1800,
    "asset_ownership": 55,
    "certifications": [
        {
            "id": {unique_id},
            "certification_id": 598,
            "name": "BCA Green Mark/Existing Buildings",
            "level": "Platinum",
            "size": 230,
            "year": 2017,
            "_validations": {
                "errors": {}
            }
        }
        ],
    "annual_data": [
        {
            "year": {reporting_year - 1},
            "asset_size": 5000,
            "asset_name": "API Created Asset",
            "en_tot_wd": 4000,
            "en_tot_we": 900,
            "en_tot_wf": 100,
            "ghg_tot_s3_w": 5000,
            "ncmr_status": "Standing Investment",
            "owned_entire_period": true,
            "property_type_code": "HTL",
            "tenant_ctrl": true,
            "was_pcov": 0,
            "wat_tot_w": 5000,
            "whole_building": true,
            "asset_vacancy":0,
            "_validations": {
                "errors": {}
            }
        },
        {
            "year": {reporting_year - 2},
            "asset_name": "API Created Asset",
            "asset_size": 5000,
            "en_tot_wd": 4000,
            "en_tot_we": 900,
            "en_tot_wf": 100,
            "ghg_tot_s3_w": 5000,
            "ncmr_status": "Standing Investment",
            "owned_entire_period": true,
            "tenant_ctrl": true,
            "was_pcov": 0,
            "wat_tot_w": 5000,
            "whole_building": true,
            "asset_vacancy":0,
            "property_type_code": "OCHI",
            "en_tot_lc_te": 112.4,
            "_validations": {
                "errors": {}
            }
        }
        ],
    "_outliers": [],
    "created_at": {date},
    "updated_at": {date},
    "_validations": {
        "errors": {}
    }
}

PATCH /entities/{entity_id}/assets/{asset_id}

Updates the asset specified in the URL. This endpoint allows partial updates, meaning you only need to provide the changes you want to apply and they are merged with the existing asset fields. To clear an existing value, you need to explicitly set it to null. The changed asset is validated and is only saved if there are no validation errors. In all cases, you get a response with all the asset fields and any validation errors/warnings.

In the example shown on the right, we attempt to increase asset_size from 5000 to 6000; however, the requested update does not get recorded due to the new value having introduced validation errors. Make note of the HTTP status informing the user of the unprocessed content when there is such a case.

For a complete list of fields, and their meaning, see the Data Dictionary.

To bulk-update more than a few assets, please submit a Batch Operation.

curl -X PATCH https://api.gresb.com/api/v1/entities/{entity_id}/assets/{asset_id} \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<JSON

{
    "annual_data": [
        {
            "year": {reporting_year - 1},
            "asset_size": 6000
        }
    ]
}

{
    "gresb_asset_id": {asset_id},
    "country": "NL",
    "state_province": "North Holland",
    "city": "Amsterdam",
    "address": "Barbara Strozzilaan 374",
    "lat": 52.335915637320596,
    "lng": 4.889755053768094,
    "partners_id": 123456,
    "construction_year": 1800,
    "asset_ownership": 60,
    "certifications": [
        {
            "id": {unique_id},
            "certification_id": 598,
            "name": "BCA Green Mark/Existing Buildings",
            "level": "Platinum",
            "size": 230,
            "year": 2017,
            "_validations": {
                "errors": {}
            }
        }
        ],
    "annual_data": [
        {
            "year": {reporting_year - 1},
            "asset_size": 6000,
            "asset_name": "API Created Asset",
            "en_tot_wd": 4000,
            "en_tot_we": 900,
            "en_tot_wf": 100,
            "ghg_tot_s3_w": 5000,
            "ncmr_status": "Standing Investment",
            "owned_entire_period": true,
            "property_type_code": "HTL",
            "tenant_ctrl": true,
            "was_pcov": 0,
            "wat_tot_w": 5000,
            "whole_building": true,
            "asset_vacancy":50,
            "_validations": {
                "errors": {
                    "ghg_tot_s3_w": [
                        "Must be less than or equal to asset_size",
                        "Must be equal to asset_size if the whole building is tenant controlled"
                    ],
                    "en_tot_wf": [
                        "Must be less than or equal to asset_size"
                    ],
                    "wat_tot_w": [
                        "must be equal to asset_size"
                    ]
                }
            }
        },
        {
            "year": {reporting_year - 2},
            "asset_size": 6000,
            "asset_name": "API Created Asset",
            "en_tot_wd": 4000,
            "en_tot_we": 900,
            "en_tot_wf": 100,
            "ghg_tot_s3_w": 5000,
            "ncmr_status": "Standing Investment",
            "owned_entire_period": true,
            "property_type_code": "HTL",
            "tenant_ctrl": true,
            "was_pcov": 0,
            "wat_tot_w": 5000,
            "whole_building": true,
            "asset_vacancy":50,
            "_validations": {
                "errors": {
                    "ghg_tot_s3_w": [
                        "Must be less than or equal to asset_size",
                        "Must be equal to asset_size if the whole building is tenant controlled"
                    ],
                    "en_tot_wf": [
                        "Must be less than or equal to asset_size"
                    ],
                    "wat_tot_w": [
                        "must be equal to asset_size"
                    ]
                }
            }
        }
        ],
    "_outliers": [],
    "created_at": {date},
    "updated_at": {date},
    "_validations": {
        "errors": {}
    }
}

DELETE /entities/{entity_id}/assets/{asset_id}

Deletes the asset specified in the URL. Returns the deleted asset if the operation is successful.

curl -X DELETE https://api.gresb.com/api/v1/entities/{entity_id}/assets/{asset_id} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
    "gresb_asset_id": {asset_id},
    "country": "NL",
    "state_province": "North Holland",
    "city": "Amsterdam",
    "address": "Barbara Strozzilaan 374",
    "lat": 52.335915637320596,
    "lng": 4.889755053768094,
    "partners_id": 123456,
    "construction_year": 1800,
    "asset_ownership": 60,
    "certifications": [],
    "asset_size": 5000.0,
    "annual_data": [],
    "_outliers": [],
    "created_at": {date},
    "updated_at": {date}
}

POST /entities/{entity_id}/asset_spreadsheet_export

Exports all the entity's assets to a XSLX spreadsheet and sends a POST request to the provided callback URL containing the file URL. It will be accessible for 15 minutes.

curl -X POST https://api.gresb.com/api/v1/entities/{entity_id}/asset_spreadsheet_export \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d "callback_url=https://your.callback.url"

{
    "url": "https://gresb-prd-private.s3.amazonaws.com/production/asset-excels/..."
}

Asset Batch Operations

The API offers an endpoint specifically for scenarios when you need to create or update multiple assets with one request. The request format is similar, with one major difference: all asset representations are enclosed in an array, and assigned to fields which are named create, always_create, update, always_update and delete depending on what you want to do with the array of assets. All five fields are optional. In any case, you probably want to provide at least one, otherwise no operation will be performed.

{
    "create": [
      // any number of asset representations
    ],
    "always_create": [
      // Same as above, but always creates all items even if they fail
      // some validation rules. A few attributes (see below) are still
      // required, and the batch will fail if they are not found/valid.
    ],
    "update": [
      // any number of partial asset representations
      // each one must include "gresb_asset_id"
    ],
    "always_update": [
      // Same as above, but always updates all (found) items even if they
      // fail some validation rules.
      // Each one must include "gresb_asset_id".
    ],
    "delete": [
      // objects with "gresb_asset_id" only
    ]
}

This endpoint returns a response in a similar format to the request. Instead of create, always_create, update, always_update, delete, you get created, always_created, updated, always_updated, deleted. Each one will contain an array of asset representations which were successfully created, created regardless of validations, successfully updated, updated regardless of validations, or deleted, respectively.

In addition to the fields above, you will also get invalid, not_found and counts. invalid will contain assets you attempted to create, or update, but failed validation. These records will not be saved and you will get a _validations field for each, with more details. You can use always_create and always_update to bypass the validation procedure.

The field always_create requires 5 data variables. Namely, country, city, state_province, asset_name, and property_type_code. If one of these variables is missing, the entire batch request will fail! The field always_update has no minimal requirements. Please be aware that although the API accepts invalid data, the data must be valid in order for the user to update the portfolio data in the Real Estate Assessment form the GRESB Asset Portal.

Please be aware that access to this endpoint is limited in order to prevent abuse or overuse caused by a buggy or malicious client. It happens in two ways:

Not more than 10 requests are allowed per minute.
Each of the fields in the request is limited to 5000 assets at once.

These values are experimental and therefore are subject to change. However, you are unlikely to reach them during normal operation.

The information about the throttling is also provided in the following headers:

X-RateLimit-Remaining which contains remaining amount of allowed requests, -1 if throttled.
X-RateLimit-Limit contains the maximum number of allowed requests during a time period.
X-RateLimit-Reset expected counter reset time in UTC epoch seconds.

{
    "created": [
      // successfully created assets, with their "gresb_asset_id" added
    ],
    "always_created": [
      // created assets (even invalid), with their "gresb_asset_id" added
    ],
    "updated": [
      // successfully updated assets, only those whose "gresb_asset_id" exist
    ],
    "always_updated": [
      // updated assets (even invalid), only those whose "gresb_asset_id" exist
    ],
    "deleted": [
      // successfully deleted assets, only those whose "gresb_asset_id" exist
    ],
    "invalid": [
      // failed creates and updates due to validation errors
    ],
    "not_found": [
      // failed deletes or updates due to incorrect/missing "gresb_asset_id"
    ],
    "counts": { // counts of the items in the arrays above
        "created": 0,
        "always_created": 0,
        "updated": 0,
        "always_updated": 0,
        "deleted": 0,
        "invalid": 0,
        "not_found": 0
    }
}

POST /entities/{entity_id}/assets/batches

curl -X POST https://api.gresb.com/api/v1/entities/{entity_id}/assets/batches \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @-

In this example, we are going to create two new assets where one is always created, update two existing assets where one is always updated, and delete two assets.

Many required fields are missing for brevity. The example response shows what you would expect to get back.

{
    "create": [
        {
            "country": "US",
            "state_province": "DC",
            "city": "Washington, DC",
            "address": "1600 Pennsylvania Avenue NW",
            "construction_year": 1800,
            "partners_id": 123456,
            "certifications": [{
                    "certification_id": 598,
                    "name": "BCA Green Mark/Existing Buildings",
                    "level": "Platinum",
                    "size": 230,
                    "year": 2017
                }
            ],
            "annual_data": [{
                    "year": {reporting_year - 1},
                    "asset_size": 5000,
                    "asset_name": "The White House",
                    "en_tot_wd": 4000,
                    "en_tot_we": 900,
                    "en_tot_wf": 100,
                    "ghg_tot_s3_w": 5000,
                    "ncmr_status": "Standing Investment",
                    "owned_entire_period": true,
                    "property_type_code": "HTL",
                    "tenant_ctrl": true,
                    "was_pcov": 0,
                    "wat_tot_w": 5000,
                    "whole_building": true,
                    "asset_vacancy": 0
            }]
        }
    ],
    "always_create": [
        {
            "country": "US",
            "state_province": "DC",
            "city": "Washington, DC",
            "annual_data": [
                {
                    "year": {reporting_year - 1},
                    "asset_name": "The White House 2",
                    "property_type_code": "HTL"
                }
            ]
        }
    ],
    "update": [
        {
            "gresb_asset_id": {asset_id_update},
            "address": "1600 Pennsylvania Avenue NW",
            "annual_data": [
                {
                    "year": {reporting_year - 1},
                    "asset_name": "The Grand White House",
                    "property_type_code": "HTL"
                }
            ]
        }
    ],
    "always_update": [
        {
            "gresb_asset_id": {asset_id_always_update},
            "address": "1600 Pennsylvania Avenue NW",
            "annual_data": [
                {
                    "year": {reporting_year - 2},
                    "asset_name": "The Pink House",
                    "tenant_ctrl": false
                }
            ]
        }

    ],
    "delete": [
        {
            "gresb_asset_id": {asset_id_delete}
        },
        {
            "gresb_asset_id": {asset_id_delete_2}
        }
    ]
}

{
   "created": [
        {
            "gresb_asset_id": {asset_id_create},
            "country": "US",
            "state_province": "DC",
            "city": "Washington, DC",
            "address": "1600 Pennsylvania Avenue NW",
            //...trimmed for brevity ...
            "_outliers": [],
            "created_at": {date},
            "updated_at": {date},
            "_validations": {
                "errors": {}
            }
        }
    ],
    "always_created": [
        {
            "gresb_asset_id": {asset_id_always_create},
            "country": "US",
            "state_province": "DC",
            "city": "Washington, DC",
            //...trimmed for brevity ...
            "annual_data": [      {
                "year": {reporting_year - 1},
                "asset_size": null,
                "asset_name": "The White House 2",
                "owned_entire_period": false,
                "property_type_code": "HTL",
                "_validations": {
                    "errors":   
                    {
                        "tenant_ctrl": ["must be true or false"],
                        "ownership_from": ["Either ownership_from or ownership_to must be present if asset is not owned for entire reporting period"],
                        "ownership_to": ["Either ownership_from or ownership_to must be present if asset is not owned for entire reporting period"]
                    }
                }
            }],
            "_outliers": [],
            "created_at": {date},
            "updated_at": {date},
            "_validations": {
                "errors": 
                {
                    "asset_size": ["is not a number"]
                }
            }
        }
    ],
   "updated": [
        {
            "gresb_asset_id": {asset_id_update},
            "country": "US",
            "state_province": "DC",
            "city": "Washington, DC",
            //...trimmed for brevity ...
            "_outliers": [],
            "created_at": {date},
            "updated_at": {date}
        }
    ],
    "always_updated": [
        {
            "gresb_asset_id": {asset_id_always_update},
            "country": "US",
            "state_province": "DC",
            "city": "Washington, DC",
            "address": "1600 Pennsylvania Avenue NW",
            //...trimmed for brevity ...
            "_outliers": [],
            "created_at": {date},
            "updated_at": {date},
            "_validations": {
                "errors": {}
            }
        }
    ],
    "deleted":  [
        {
            "gresb_asset_id": {asset_id_delete},
            "country": "US",
            "state_province": "DC",
            "city": "Washington, DC",
            //...trimmed for brevity ...
            "_outliers": [],
            "created_at": {date},
            "updated_at": {date},
            "_validations": {"errors": {}}
        },
        {
            "gresb_asset_id": {asset_id_delete_2},
            "country": "US",
            "state_province": "DC",
            "city": "Washington, DC",
            //...trimmed for brevity ...
            "_outliers": [],
            "created_at": {date},
            "updated_at": {date},
            "_validations": {
            "errors": {}
            }
        }
   ],
   "invalid": [],
   "not_found": [],
   "counts":    {
      "created": 1,
      "always_created": 1,
      "updated": 1,
      "always_updated": 1,
      "deleted": 2,
      "invalid": 0,
      "not_found": 0
   }
}

Asset Outliers

curl https://api.gresb.com/api/v1/entities/{entity_id}/assets \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GRESB provides a realtime outlier check to ensure high data quality and automatically flags values that seem to be out of the norm. Outlier checks are performed after creating or updating a portfolio asset.

If validation outliers have been detected, the outliers:[] field in the response will list them accordingly.

[
    {
        "gresb_asset_id": {asset_id},
        "country": "US",
        "state_province": "DC",
        "city": "Washington, DC",
        // ... trimmed for brevity ...
        "certifications": [   {
            "id": {unique_id},
            "certification_id": 598,
            // ... trimmed for brevity ...
   }],
   "asset_size": "6000.0",
        "annual_data": [
          {
              "year": {reporting_year - 1},
              // ... trimmed for brevity ...
          },
          {
              "year": {reporting_year - 2},
              // ... trimmed for brevity ...
          },
        ],
        "_outliers": [
          {
            "kpi": "en",
            "type": "intensity",
            "accepted": true,
            "value": "2.5627716"
          },
          {
            "kpi": "en",
            "type": "lfl",
            "accepted": true,
            "value": "-28.20623403"
          },
          {
            "kpi": "ghg",
            "type": "lfl",
            "accepted": false,
            "value": "-95.59816432"
          }
        ],
      "created_at": {date},
      "updated_at": {date},
      "_validations": {"errors": {}}
    }
]

Outlier types:

LFL: Like for like detection, compares values against last year
Intensity: Detects abnormal values for the current year

KPI:

en: Energy in kWh/m²
ghg: Green house gases measured in tonnes/m²
was: Waste in tonnes/m²
wat: Water in m³/m²

Accepted:

The accepted field gives you information whether or not this value will be included or excluded in scoring.
true: The data points associated to this outlier will be included in your score, but not in the benchmark groups.
false: The data points associated to this outlier will not be included in your score.

Asset Validation Endpoint

The API offers an endpoint specifically to only validate (multiple) assets. The request format is similar, all asset representations have to be enclosed in an array and are assigned to the fields create or update.

The update array requires assets with an gresb_asset_id.

{
    "create": [
      // any number of asset representations
    ],
    "update": [
      // any number of partial asset representations
      // each one must include "gresb_asset_id"
    ]
}

{
    "valid": [
      // all records that passed validation
    ],
    "invalid": [
      // all invalid records
    ],
    "not_found": [
      // failed to find via "gresb_asset_id"
    ],
    "counts": { // counts of the items in the arrays above
        "valid": 0,
        "invalid": 0,
        "not_found": 0
    }
}

POST /entities/{entity_id}/assets/validation

curl -X POST https://api.gresb.com/api/v1/entities/{entity_id}/assets/validation \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @-

In this example, we are going to validate a new asset and an already existing one. Many required fields are missing for brevity, but assume that one of the assets we want to create is valid and the existing one is missing some required data (tenant_ctrl). The example response shows what you would expect to get back. In this case one asset is valid and the other one is invalid.

{
    "create": [{
        "country": "US",
        "state_province": "DC",
        "city": "Washington, DC",
        //...trimmed for brevity...
        "annual_data": [{
            "year": {reporting_year - 1},
            //...trimmed for brevity...
            },
            {
            "year": {reporting_year - 2},
            //...trimmed for brevity...
            }
        ]
    }],
    "update": [{
        "gresb_asset_id": {asset_id},
        "address": "1600 Pennsylvania Avenue NW",
        "annual_data": [{
            "year": {reporting_year - 1},
            "tenant_ctrl": null
        }]
    }]
}

{
   "valid": [   
        {
            "gresb_asset_id": null,
            "country": "US",
            "state_province": "DC",
            "city": "Washington, DC",
            //...trimmed for brevity...
            "certifications": [
                {
                    //...trimmed for brevity...
                    "_validations": {
                        "errors": {}
                    }
                }
            ],
            "asset_size": 5000.0,
            "annual_data": [
                {
                    "year": {reporting_year - 1},
                    //...trimmed for brevity...
                    "_validations": {
                        "errors": {}
                    }
                },
                {
                    "year": {reporting_year - 2},
                    //...trimmed for brevity...
                    "_validations": {
                        "errors": {}
                    }
                }
            ],
            "_outliers": [],
            "created_at": null,
            "updated_at": null,
            "_validations": {
                "errors": {}
            }
        }
    ],
    "invalid": [
        {
            "gresb_asset_id": {asset_id_2},
            "country": "US",
            "state_province": "DC",
            "city": "Washington, DC",
            "address": "1600 Pennsylvania Avenue NW",
            //...trimmed for brevity...
            "certifications":   [
                {
                    "id": {unique_id},
                    //...trimmed for brevity...
                    "_validations": {
                        "errors": {}
                    }
                },
                {
                    "id": {unique_id_2},
                    //...trimmed for brevity...
                    "_validations": {
                        "errors": {}
                    }
                }
            ],
            "asset_size": 5000.0,
            "annual_data":  [
                {
                    "year": {reporting_year - 1},
                    "asset_size": 5000,
                    //...trimmed for brevity...
                    "_validations": {
                        "errors": {
                            "tenant_ctrl": ["must be true or false"]
                        }
                    }
                }
            ],
            "_outliers": [],
            "created_at": {date},
            "updated_at": {date},
            "_validations": {
                "errors": {}
            }
        }
    ],
    "not_found": [],
    "counts":    {
    "valid": 1,
    "invalid": 1,
    "not_found": 0
    }
}

Asset Data Dictionary

Data may be posted to describe each asset/building and provide an annual snapshot for up to 5 years prior to the current assessment year. The data types and object keys for each field/metric are listed below. Please refer to the Real Estate Reference Guide for more detailed definitions and reporting guidance.

For the data mapping exercise you may consider using the GRESB Asset Spreadsheet. The hidden first row in each data tab holds the variable names which are used in the API endpoint.

Asset characteristics are posted per asset, not per reporting year.

variable	type	description
gresb_asset_id	integer	Unique GRESB Asset ID. Generated automatically when creating a new asset. Non-existing IDs or IDs belonging to another portfolio will be rejected.
partners_id	integer	Self-provided Asset ID to ensure correct mapping within your application.
country	character varying (255)	ISO3166 country code. See Country List for further information.

state_province	character varying (255)	State, province, or region.
city	character varying (255)	City, town, or village.
address	character varying (255)	Physical street or postal address.
lat	numeric	Latitude.
lng	numeric	Longitude.
construction_year	integer	Year in which the asset was completed and ready for use.
asset_ownership	numeric	Percentage of the asset owned by the reporting entity.

Certifications and energy ratings are posted per asset, not per reporting year.

variable	type	description	unit
id	integer	Unique identifier associated to a certification record. Created automatically when creating a new certification record.
certification_id	integer	The ID of the certification.
size	numeric	Floor area covered by the certification or energy rating.	m²/sq. ft
level	character varying (255)	The certification level achieved. Only available for some certifications, and mandatory when available.
year	integer	Year for which the certification is issued.
energy_rating_id	integer	The ID of the energy rating. See Energy Ratings for further information.

The following list of fields are posted annually, per reporting year.

variable	type	description	unit
year	integer	Year that data is being reported for.
asset_name	character varying (255)	Name of the asset as displayed to the users with access to this portfolio in the Asset Portal.
property_type_code	character varying (255)	GRESB property type classification for the asset. See Property Type List for further information.

asset_gav	numeric	Gross asset value of the asset at the end of the reporting year.	currency (millions)
asset_size	numeric	The total floor area size of the asset - without outdoor/exterior areas. Use the same area metric as reported in RC3.	m²/sq. ft
en_emr_tba	boolean	Has a technical building assessment to identify energy efficiency improvements been performed in the last 3 years?
en_emr_amr	boolean	Energy efficiency measure: Have automatic meter readings for energy been implemented in the last 3 years?
en_emr_asur	boolean	Energy efficiency measure: Have automation system upgrades/replacements been implemented in the last 3 years?
en_emr_msur	boolean	Energy efficiency measure: Have management system upgrades/replacements been implememted in the last 3 years?
en_emr_ihee	boolean	Energy efficiency measure: Have high-efficiency equipment and/or appliances been installed in the last 3 years?
en_emr_iren	boolean	Energy efficiency measure: Has on-site renewable energy been installed in the last 3 years?
en_emr_oce	boolean	Energy efficiency measure: Have occupier engagement/informational technology improvements been implemented in the last 3 years?
en_emr_sbt	boolean	Energy efficiency measure: Have smart grid or smart building technologies been implemented in the last 3 years?
en_emr_src	boolean	Energy efficiency measure: Has systems commissioning or retro-commissioning been implememted in the last 3 years?
en_emr_wri	boolean	Energy efficiency measure: Has the wall and/or roof insulation been replaced or modified to improve energy efficiency in the last 3 years?
en_emr_wdr	boolean	Energy efficiency measure: Have windows been replaced to improve energy efficiency in the last 3 years?
wat_emr_tba	boolean	Has a technical building assessment to identify water efficiency improvements been performed in the last 3 years?
wat_emr_amr	boolean	Water efficiency measure: Have automatic meter readings for water been implemented in the last 3 years?
wat_emr_clt	boolean	Water efficiency measure: Have cooling towers been introduced in the last 3 years?
wat_emr_dsi	boolean	Water efficiency measure: Have smart or drip irrigation methods been implemented in the last 3 years?
wat_emr_dtnl	boolean	Water efficiency measure: Has drought-tolerant and/or native landscaping been introduced in the last 3 years?
wat_emr_hedf	boolean	Water efficiency measure: Have high-efficiency and/or dry fixtures been introduced in the last 3 years?
wat_emr_lds	boolean	Water efficiency measure: Has a leak detection system been implemented in the last 3 years?
wat_emr_mws	boolean	Water efficiency measure: Has the installation of water sub-meters been implemented in the last 3 years?
wat_emr_owwt	boolean	Water efficiency measure: Has a system or process of on-site water treatment been implemented in the last 3 years?
wat_emr_rsgw	boolean	Water efficiency measure: Has a system or process to reuse storm and/or grey water been implemented in the last 3 years?
was_emr_tba	boolean	Has a technical building assessment to identify waste efficiency improvements been performed in the last 3 years?
was_emr_clfw	boolean	Waste efficiency measure: Has composting landscape and/or food waste been implemented in the last 3 years?
was_emr_opm	boolean	Waste efficiency measure: Has a system or process of ongoing monitoring of waste performance been implemented in the last 3 years?
was_emr_rec	boolean	Waste efficiency measure: Has a program for local waste recycling been implemented in the last 3 years?
was_emr_wsm	boolean	Waste efficiency measure: Has a program of waste management been implemented in the last 3 years?
was_emr_wsa	boolean	Waste efficiency measure: Has a waste stream audit been performed in the last 3 years?
tenant_ctrl	boolean	Is the whole building tenant-controlled (TRUE) or does the landlord have at least some operational control (FALSE)?
asset_vacancy	numeric	The average percent vacancy rate.	%
owned_entire_period	boolean	Has the asset been owned for the entire reporting year (TRUE) or was the asset purchased or sold during the reporting year (FALSE)?
ownership_from	date	If asset was not owned for entire reporting period, date when the asset was purchased or acquired within the reporting year.
ownership_to	date	If asset was not owned for entire reporting period, date when the asset was sold within the reporting year.
ncmr_status	character varying (255)	The operational status of the asset: `Standing Investment`, `Major Renovation Project`, or `New Construction Project`, within the reporting year.
ncmr_from	date	If the asset was under major renovation or new construction, the start date of the project within the reporting year.
ncmr_to	date	If the asset was under major renovation or new construction, the end date of the project within the reporting year.
whole_building	boolean	Is the energy consumption data of the asset collected for the whole building (TRUE) or separately for base building and tenant space (FALSE)?
asset_size_common	numeric	Floor area of the common areas.	m²/sq. ft
asset_size_shared	numeric	Floor area of the shared spaces.	m²/sq. ft
asset_size_tenant	numeric	Floor area of all tenant spaces (all lettable area).	m²/sq. ft
asset_size_tenant_landlord	numeric	Floor area of tenant spaces where the landlord purchases energy.	m²/sq. ft
asset_size_tenant_tenant	numeric	Floor area of tenant spaces where the tenant purchases energy.	m²/sq. ft
en_data_from	date	Date within reporting year from which energy data is available.
en_data_to	date	Date within reporting year to which energy data is available.
en_abs_wf	numeric	Absolute and non-normalized fuel consumption for assets reporting on whole building.	kWh
en_cov_wf	numeric	Covered floor area where fuel consumption data is collected for assets reporting on whole building.	m²/sq. ft
en_tot_wf	numeric	Total floor area where fuel supply exists for assets reporting on whole building.	m²/sq. ft
en_abs_wd	numeric	Absolute and non-normalized district heating and cooling consumption for assets reporting on whole building.	kWh
en_cov_wd	numeric	Covered floor area where district heating and cooling consumption data is collected for assets reporting on whole building.	m²/sq. ft
en_tot_wd	numeric	Total floor area where district heating and cooling supply exists for assets reporting on whole building.	m²/sq. ft
en_abs_we	numeric	Absolute and non-normalized electricity consumption for assets reporting on whole building.	kWh
en_cov_we	numeric	Covered floor area where electricity consumption data is collected for assets reporting on whole building.	m²/sq. ft
en_tot_we	numeric	Total floor area where electricity supply exists for assets reporting on whole building.	m²/sq. ft
en_abs_lc_bsf	numeric	Absolute and non-normalized fuel consumption for shared services.	kWh
en_cov_lc_bsf	numeric	Covered floor area where fuel consumption data is collected for shared services.	m²/sq. ft
en_tot_lc_bsf	numeric	Total floor area where fuel supply exists for shared services.	m²/sq. ft
en_abs_lc_bsd	numeric	Absolute and non-normalized district heating and cooling consumption for shared services.	kWh
en_cov_lc_bsd	numeric	Covered floor area where district heating and cooling consumption data is collected for shared services.	m²/sq. ft
en_tot_lc_bsd	numeric	Total floor area where district heating and cooling supply exists for shared services.	m²/sq. ft
en_abs_lc_bse	numeric	Absolute and non-normalized electricity consumption for shared services.	kWh
en_cov_lc_bse	numeric	Covered floor area where electricity consumption data is collected for shared services.	m²/sq. ft
en_tot_lc_bse	numeric	Total floor area where electricity supply exists for shared services.	m²/sq. ft
en_abs_lc_bcf	numeric	Absolute and non-normalized fuel consumption for common areas.	kWh
en_cov_lc_bcf	numeric	Covered floor area where fuel consumption data is collected for common areas.	m²/sq. ft
en_tot_lc_bcf	numeric	Total floor area where fuel supply exists for common areas.	m²/sq. ft
en_abs_lc_bcd	numeric	Absolute and non-normalized district heating and cooling consumption for common areas.	kWh
en_cov_lc_bcd	numeric	Covered floor area where district heating and cooling consumption data is collected for common areas.	m²/sq. ft
en_tot_lc_bcd	numeric	Total floor area where district heating and cooling supply exists for common areas.	m²/sq. ft
en_abs_lc_bce	numeric	Absolute and non-normalized electricity consumption for common areas.	kWh
en_cov_lc_bce	numeric	Covered floor area where electricity consumption data is collected for common areas.	m²/sq. ft
en_tot_lc_bce	numeric	Total floor area where electricity supply exists for common areas.	m²/sq. ft
en_abs_lc_tf	numeric	Absolute and non-normalized fuel consumption for landlord-controlled tenant spaces.	kWh
en_cov_lc_tf	numeric	Covered floor area where fuel consumption data is collected for landlord-controlled tenant spaces.	m²/sq. ft
en_tot_lc_tf	numeric	Total floor area where fuel supply exists for landlord-controlled tenant spaces.	m²/sq. ft
en_abs_lc_td	numeric	Absolute and non-normalized district heating and cooling consumption for landlord-controlled tenant spaces.	kWh
en_cov_lc_td	numeric	Covered floor area where district heating and cooling consumption data is collected for landlord-controlled tenant spaces.	m²/sq. ft
en_tot_lc_td	numeric	Total floor area where district heating and cooling supply exists for landlord-controlled tenant spaces.	m²/sq. ft
en_abs_lc_te	numeric	Absolute and non-normalized electricity consumption for landlord-controlled tenant spaces.	kWh
en_cov_lc_te	numeric	Covered floor area where electricity consumption data is collected for landlord-controlled tenant spaces.	m²/sq. ft
en_tot_lc_te	numeric	Total floor area where electricity supply exists for landlord-controlled tenant spaces.	m²/sq. ft
en_abs_tc_tf	numeric	Absolute and non-normalized fuel consumption for tenant-controlled tenant spaces.	kWh
en_cov_tc_tf	numeric	Covered floor area where fuel consumption data is collected for tenant-controlled tenant spaces.	m²/sq. ft
en_tot_tc_tf	numeric	Total floor area where fuel supply exists for tenant-controlled tenant spaces.	m²/sq. ft
en_abs_tc_td	numeric	Absolute and non-normalized district heating and cooling consumption for tenant-controlled tenant spaces.	kWh
en_cov_tc_td	numeric	Covered floor area where district heating and cooling consumption data is collected for tenant-controlled tenant spaces.	m²/sq. ft
en_tot_tc_td	numeric	Total floor area where district heating and cooling supply exists for tenant-controlled tenant spaces.	m²/sq. ft
en_abs_tc_te	numeric	Absolute and non-normalized electricity consumption for tenant-controlled tenant spaces.	kWh
en_cov_tc_te	numeric	Covered floor area where electricity consumption data is collected for tenant-controlled tenant spaces.	m²/sq. ft
en_tot_tc_te	numeric	Total floor area where electricity supply exists for tenant-controlled tenant spaces.	m²/sq. ft
en_abs_lc_of	numeric	Absolute and non-normalized fuel consumption for landlord-controlled outdoor spaces.	kWh
en_abs_lc_oe	numeric	Absolute and non-normalized electricity consumption for landlord-controlled outdoor spaces.	kWh
en_abs_tc_of	numeric	Absolute and non-normalized fuel consumption for tenant-controlled outdoor spaces.	kWh
en_abs_tc_oe	numeric	Absolute and non-normalized electricity consumption for tenant-controlled outdoor spaces.	kWh
en_abs_nopr_ev	numeric	Non-operational energy consumption by EV charging stations.	kWh
en_ren_ons_con	numeric	Renewable energy generated and consumed on-site by the landlord.	kWh
en_ren_ons_exp	numeric	Renewable energy generated on-site and exported by the landlord.	kWh
en_ren_ons_tpt	numeric	Renewable energy generated and consumed on-site by the tenant or a third party.	kWh
en_ren_ofs_pbl	numeric	Renewable energy generated off-site and purchased by the landlord.	kWh
en_ren_ofs_pbt	numeric	Renewable energy generated off-site and purchased by the tenant.	kWh
ghg_abs_s1_w	numeric	GHG scope 1 emissions generated by the asset.	metric ton
ghg_cov_s1_w	numeric	Covered floor area where GHG scope 1 emissions data is collected.	m²/sq. ft
ghg_tot_s1_w	numeric	Total floor area where GHG scope 1 emissions can exist.	m²/sq. ft
ghg_abs_s1_o	numeric	GHG scope 1 emissions generated by the outdoor spaces associated with the asset.	metric ton
ghg_abs_s2_lb_w	numeric	GHG scope 2 emissions generated by the asset, calculated using the location-based method.	metric ton
ghg_cov_s2_lb_w	numeric	Covered floor area where GHG scope 2 emissions data is collected, calculated using the location-based method.	m²/sq. ft
ghg_tot_s2_lb_w	numeric	Total floor area where GHG scope 2 emissions can exist, calculated using the location-based method.	m²/sq. ft
ghg_abs_s2_lb_o	numeric	GHG scope 2 emissions generated by the outdoor spaces associated with the asset, calculated using the location-based method.	metric ton
ghg_abs_s2_mb_w	numeric	GHG scope 2 emissions generated by the asset, calculated using the market-based method.	metric ton
ghg_abs_s2_mb_o	numeric	GHG scope 2 emissions generated by the outdoor spaces associated with the asset, calculated using the market-based method.	metric ton
ghg_abs_s3_w	numeric	GHG scope 3 emissions generated by the asset.	metric ton
ghg_cov_s3_w	numeric	Covered floor area where GHG scope 3 emissions data is collected.	m²/sq. ft
ghg_tot_s3_w	numeric	Total floor area where GHG scope 3 emissions can exist.	m²/sq. ft
ghg_abs_s3_o	numeric	GHG scope 3 emissions generated by the outdoor spaces associated with the asset.	metric ton
ghg_abs_offset	numeric	GHG offsets purchased.	metric ton
wat_data_from	date	Date within reporting year from which water data is available.
wat_data_to	date	Date within reporting year to which water data is available.
wat_abs_w	numeric	Absolute and non-normalized water consumption for assets reporting on whole building.	m³
wat_cov_w	numeric	Covered floor area where water consumption data is collected for assets reporting on whole building.	m²/sq. ft
wat_tot_w	numeric	Total floor area where water supply exists for assets reporting on whole building.	m²/sq. ft
wat_abs_lc_bs	numeric	Absolute and non-normalized water consumption for shared services.	m³
wat_cov_lc_bs	numeric	Covered floor area where water consumption data is collected for shared services.	m²/sq. ft
wat_tot_lc_bs	numeric	Total floor area where water supply exists for shared services.	m²/sq. ft
wat_abs_lc_bc	numeric	Absolute and non-normalized water consumption for common areas.	m³
wat_cov_lc_bc	numeric	Covered floor area where water consumption data is collected for common areas.	m²/sq. ft
wat_tot_lc_bc	numeric	Total floor area where water supply exists for common areas.	m²/sq. ft
wat_abs_lc_t	numeric	Absolute and non-normalized water consumption for landlord-controlled tenant spaces.	m³
wat_cov_lc_t	numeric	Covered floor area where water consumption data is collected for landlord-controlled tenant spaces.	m²/sq. ft
wat_tot_lc_t	numeric	Total floor area where water supply exists for landlord-controlled tenant spaces.	m²/sq. ft
wat_abs_tc_t	numeric	Absolute and non-normalized water consumption for tenant-controlled tenant spaces.	m³
wat_cov_tc_t	numeric	Covered floor area where water consumption data is collected for tenant-controlled tenant spaces.	m²/sq. ft
wat_tot_tc_t	numeric	Total floor area where water supply exists for tenant-controlled tenant spaces.	m²/sq. ft
wat_abs_lc_o	numeric	Absolute and non-normalized water consumption for landlord-controlled outdoor spaces.	m³
wat_abs_tc_o	numeric	Absolute and non-normalized water consumption for tenant-controlled outdoor spaces.	m³
wat_rec_ons_reu	numeric	Volume of greywater and/or blackwater reused in on-site activities.	m³
wat_rec_ons_cap	numeric	Volume of rainwater, fog, or condensate that is treated and purified for reuse and/or recycling.	m³
wat_rec_ons_ext	numeric	Volume of extracted groundwater that is treated and purified for reuse and/or recycling.	m³
wat_rec_ofs_pur	numeric	Volume of recycled water purchased from a third party.	m³
was_data_from	date	Date within reporting year from which waste data is available.
was_data_to	date	Date within reporting year to which waste data is available.
was_abs_haz	numeric	Absolute and non-normalized hazardous waste produced by asset.	metric ton
was_abs_nhaz	numeric	Absolute and non-normalized non-hazardous waste produced by asset.	metric ton
was_pcov	numeric	Percent coverage out of total asset size where waste data is collected.	%
was_pabs_lf	numeric	Percentage of total waste sent to landfill.	%
was_pabs_in	numeric	Percentage of total waste incinerated.	%
was_pabs_ru	numeric	Percentage of total waste reused.	%
was_pabs_wte	numeric	Percentage of total waste converted to energy.	%
was_pabs_rec	numeric	Percentage of total waste recycled.	%
was_pabs_oth	numeric	Percentage of total waste where disposal route is other or unknown.	%

Asset Certifications

We provide a list of available building certifications that can be assigned to an asset. Some certifications have various levels available. In those cases, the level field is mandatory for an asset.

GET /certifications

curl https://api.gresb.com/api/v1/certifications

[
  {
      "id": 585,
      "name": "ABINC Certification/Urban Development and Shopping Centre",
      "country": "JP",
      "status": "both"
   },
      {
      "id": 895,
      "name": "Austin Energy/Austin Energy Green Building",
      "status": "both"
   },
      {
      "id": 598,
      "name": "BCA Green Mark/Existing Buildings",
      "levels":       [
         "Platinum",
         "GoldPlus",
         "Gold",
         "Certified"
      ],
      "country": "SG",
      "status": "operational"
   }
   // ... trimmed for brevity ...
]

Create certifications

Certification records can be created by sending the certification_id, level (when relevant), size and year within the certifications array. The certification_id in constraint with the level is unique for each asset.

The response includes a unique id, which is the identifier for the particular association record created. If id is not returned, then the record is not created.

Data is not overwritten by sending another certification. If the certification data does not include an id, we always try to create a new association.

curl https://api.gresb.com/api/v1/entities/{{entity_id}}/assets/{{asset_id}}

{
    "certifications": [
        {
            "certification_id": 999,
            "level": "GoldPlus",
            "size": 123,
            "year": 2017
        }
    ]  
}

[
    {
        "gresb_asset_id": {asset_id},
        "country": "NL",
        "state_province": "North Holland",
        "city": "Amsterdam",
        "address": "Barbara Strozzilaan 374",
        "lat": 52.335915637320596,
        "lng": 4.889755053768094,
        "partners_id": 123456,
        "construction_year": 1800,
        "asset_ownership": 55,
        "certifications":    [
            {
                "id": null,
                "certification_id": null,
                "name": null,
                "level": null,
                "size": 123,
                "_validations": {
                    "errors": {
                        "certification": [
                            "must exist"
                        ]
                    }
                }
            }
        ],
        "asset_size": 5000.0,
        "annual_data":    [
            {
                "year": {reporting_year - 1},
                "asset_size": 5000,
                //...trimmed for brevity ...

Update certifications

Provide the unique ID of the certification record, id, to update an existing certification. For example, to update the size of a certification, send the following data: { "certifications": [{ "id": 123456, "size": 234, "year": 2017 }] }

If you don't want to update or add more certifications, you can simply exclude the certifications array from your request.

Remove certifications

To remove certifications you need to provide the id and the key _destroy. certifications: [{ "id": 123456, "_destroy": "1" }]

Asset Energy Ratings

We provide a list of available energy ratings that can be assigned to an asset.

GET /energy_ratings

curl https://api.gresb.com/api/v1/energy_ratings

[
  {
      "id": 66,
      "name": "Arc Energy Performance Certificate"
   },
      {
      "id": 67,
      "name": "Arc Energy Performance Score"
   },
      {
      "id": 68,
      "name": "BBC Effinergie"
   }
   // ... trimmed for brevity ...
]

Create, Update and Remove Energy Ratings

Just like building certifications, it is possible to report multiple energy ratings per asset. Encapsulate all the energy ratings in the energy_ratings array and submit to /entities/{entity_id}/assets/{asset_id}. Each energy rating has to have an energy_rating_id and a size specified in order to be valid.

A unique ID will be returned when the energy rating is created for the first time. Returned ID can then be referenced to update and delete the record: energy_ratings: [{ "id": 123456, "_destroy": "1" }]

curl https://api.gresb.com/api/v1/entities/{{entity_id}}/assets/{{asset_id}}

{
    "energy_ratings": [
        {
        "energy_rating_id": 57,
        "size": 123
        },
        {
        "energy_rating_id": 66,
        "size": 456
        }
    ]
}

[
    {
        "gresb_asset_id": {asset_id},
        "country": "NL",
        "state_province": "North Holland",
        "city": "Amsterdam",
        "address": "Barbara Strozzilaan 374",
        "lat": 52.335915637320596,
        "lng": 4.889755053768094,
        "partners_id": 123456,
        "construction_year": 1800,
        "asset_ownership": 55,
        "certifications":    [
            {
            "id": {unique_id},
            "certification_id": 598,
            "name": "BCA Green Mark/Existing Buildings",
            "level": "Platinum",
            "size": 230,
            "_validations": {"errors": {}}
            }
        ],
        "energy_ratings": [
            {
            "id": {unique_id},
            "energy_rating_id": 57,
            "size": 123,
            "_validations": {"errors": {}}
            },
            {
            "id": {unique_id},
            "energy_rating_id": 66,
            "size": 456,
            "_validations": {"errors": {}}
            }
        ],
        "asset_size": 5000.0,
        "annual_data":    [
            {
                "year": {reporting_year - 1},
                "asset_size": 5000,
                "asset_name": "API Created Asset",
                "en_tot_wd": 4000,
                "en_tot_we": 900,
                "en_tot_wf": 100,
                "ghg_tot_s3_w": 5000,
                "ncmr_status": "Standing Investment",
                "owned_entire_period": true,
                "property_type_code": "HTL",
                "tenant_ctrl": true,
                "was_pcov": 0,
                "wat_tot_w": 5000,
                "whole_building": true,
                "asset_vacancy":0,
                "_validations": {
                    "errors": {}}
            }
        ],
        "_outliers": [],
        "created_at": {date},
        "updated_at": {date},
    }

Portfolio Data

With the introduction of portfolio-level endpoints, users associated with a data partnership can now submit portfolio-level data on behalf of the reporting entities and fill in the Real Estate Assessment in full. Mind that portfolio-level APIs do not serve all the functionalities in the Portal, such as aggregation, validation, and submission; meaning that API users should still make use of the Portal UI for the end-to-end submission flow.

Portfolio data needs to be submitted per indicator, and requires many requests to submit one full assessment. Each portfolio-level variable corresponds to their own endpoint, and all portfolio-level endpoints are situated in v0:

/api/v0/entities/{entity_id}/responses/{response_id}/values/{variable}

A full list of variables, along with their description, data type, and accepted values can be found in the Excel version of the Real Estate Assessment. See introduction for the Postman collection.

After performing a GET request to learn the variable's current value and lock version, a POST request can be sent in a payload, for example:

{
    "lock_version": "1",
    "value": "1"
}

Variable Patterns

Base patterns are mostly used in the tables where data fields and variables are identified with a combination of its components. These components are mostly property type, country, utility, and other variable codes which in many cases, correspond to their respective row and/or columns. R1, T1.1, T1.2, BC1.1, BC1.2, BC2, DR1, DBC1.2 are examples of tables which make use of variable patterns.

For example to submit percentage of GAV (gross asset value) for any of the benchmark categories under R1 table which represents the property type and country composition of the portfolio, base pattern of R_1_TBL_PGAV_ should be followed by the code of the country and property type of the benchmark.

Assuming that we would like to report % of GAV for assets based in the Netherlands with property type Hotel: full variable would be R_1_TBL_PGAV_NL.HTL, in which country preceeds property type code.

You can find the variables for property types and countries in the following ways:

By requesting it from the /lists endpoint
From https://portal.gresb.com/about/lists
From the Variable Whitelist below

Refer to our Variable Whitelist document for a clear overview of all the variables which the users are allowed to interact with.

GET /lists

Requests info on all the picklist (dropdown options).

curl https://api.gresb.com/api/v0/lists \

[
    {
        "slug": "equity_asset_type",
        "name": "All current real estate property types",
        "updated_at": {date}
    },
    {
        "slug": "location",
        "name": "All current locations from locations table",
        "updated_at": {date}
    }
    // ... trimmed for brevity ...
]

GET /lists/:slug

Requests info on a specific picklist and lists all the available picklist items. In this example we request the picklist items for country.

curl https://api.gresb.com/api/v0/lists/country \

{
    "slug": "country",
    "name": "Country (ISO3166)",
    "updated_at": "2019-04-11T15:30:36.132Z",
    "items": [
        {
            "label": "Afghanistan",
            "value": "AF"
        },
        {
            "label": "Albania",
            "value": "AL"
        },
        {
            "label": "Algeria",
            "value": "DZ"
        },
        // ... trimmed for brevity ...
    ]
}

GET /entities/{entity_id}/responses

Requests the assessment responses associated with the entity.

curl https://api.gresb.com/api/v0/entities/{entity_id}/responses \
  -H "Authorization: Bearer $ACCESS_TOKEN"

[
    {
        "id": {response_id},
        "entity_id": {entity_id},
        "business_line": "real_estate",
        "survey_year": {survey_year},
        "name": "API Test Entity",
        "manager": "GRESB",
        "status": "in_progress",
        "survey_open": true,
        "assessment_type": "real_estate",
        "percent_completed": 65,
        "created_at": {date},
        "updated_at": {date}
    },
    {
        "id": {response_id},
        "entity_id": {entity_id},
        "business_line": "real_estate",
        "survey_year": {survey_year},
        "name": "API Test Entity",
        "manager": "GRESB",
        "status": "new",
        "survey_open": true,
        "assessment_type": "sfdr_re",
        "percent_completed": 0,
        "created_at": {date},
        "updated_at": {date}
    }
]

GET /entities/{entity_id}/responses/{response_id}

Requests info on the specific assessment response.

curl https://api.gresb.com/api/v0/entities/{entity_id}/responses/{response_id} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

[
    {
        "id": {response_id},
        "entity_id": {entity_id},
        "business_line": "real_estate",
        "survey_year": {survey_year},
        "name": "API Test Entity",
        "manager": "GRESB",
        "status": "in_progress",
        "survey_open": true,
        "assessment_type": "real_estate",
        "percent_completed": 65,
        "created_at": {date},
        "updated_at": {date}
    }
]

GET /entities/{entity_id}/responses/{response_id}/values/{variable}

Requests the data for the variable in the endpoint.

curl https://api.gresb.com/api/v0/entities/{entity_id}/responses/{response_id}/values/{variable} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
    "variable": {variable},
    "value": "1",
    "lock_version": "1",
    "created_at": {date},
    "updated_at": {date}
}

POST /entities/{entity_id}/responses/{response_id}/values/{variable}

Updates the variable in the endpoint. null can be sent to clear the value of a variable.

curl https://api.gresb.com/api/v0/entities/{entity_id}/responses/{response_id}/values/{variable} \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<JSON

{
    "lock_version": "1",
    "value": "1"
}

{
    "id": 12345678,
    "analysis_id": 12345,
    "variable": {variable},
    "value": "1",
    "created_at": {date},
    "updated_at": {date},
    "validator_id": null,
    "validation_status": null,
    "secondary_validation_status": null,
    "secondary_validator_id": null,
    "reachable_on_submit": null,
    "raw_value": null,
    "decimal_separator": null,
    "validatable": false,
    "session_ident": null,
    "lock_version": 1,
    "validation_color": null,
    "validation_escalate": false,
    "validator_validation_date": null,
    "secondary_validation_date": null,
    "automatic_validation": false,
    "similar_value_id": null,
    "similar_value_count": null
}

Portfolio Evidence

Evidence uploads are either hyperlinks or files, depending on available options per indicator. It is possible to submit more than one evidence per indicator.

Multiple steps need to be taken to submit an evidence item and it is not possible to combine these steps within one request. Similar to the UI, each evidence submission has to indicate file type, a valid URL pointing to the evidence, and notes. An additional step can be taken to change the setting for sharing the evidence document to investors. This setting is not applicable when submitting evidence as a hyperlink (shared with investors by defualt).

Upload Hyperlink as Evidence

In order to upload a hyperlink as evidence, a total of 3 requests should be send. First indicate file type, secondly post the hyperlink URL, and thirdly share any evidence notes to indicate where in the hyperlink the supporting information can be found.

In this example, let us share a public URL as evidence for the indicator PO1 in Management > Policies.

POST values/{variable} - Indicate Evidence Type for Hyperlink

Indicate evidence type as hyperlink by sending H as the value.

curl https://api.gresb.com/api/v0/entities/{entity_id}/responses/{response_id}/values/PO_1_A1_EVD_TYPE_1 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<JSON

{
    "lock_version": "1",
    "value": "H"
}

{
    "id": 12345678,
    "analysis_id": 12345,
    "variable": "PO_1_A1_EVD_TYPE_1",
    "value": "H",
    "created_at": {date},
    "updated_at": {date},
    "validator_id": null,
    "validation_status": null,
    "secondary_validation_status": null,
    "secondary_validator_id": null,
    "reachable_on_submit": true,
    "raw_value": null,
    "decimal_separator": null,
    "validatable": false,
    "session_ident": null,
    "lock_version": 1,
    "validation_color": null,
    "validation_escalate": false,
    "validator_validation_date": null,
    "secondary_validation_date": null,
    "automatic_validation": false,
    "similar_value_id": null,
    "similar_value_count": null
}

POST values/{variable} - Indicate the Hyperlink URL

Post the hyperlink for the evidence document as a string.

curl https://api.gresb.com/api/v0/entities/{entity_id}/responses/{response_id}/values/PO_1_A1_EVD_LINK_1 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<JSON

{
    "lock_version": 1,
    "value": "https://documents.gresb.com/"
}

{
    "id": 12345678,
    "analysis_id": 12345,
    "variable": "PO_1_A1_EVD_LINK_1",
    "value": "https://documents.gresb.com/",
    "created_at": {date},
    "updated_at": {date},
    "validator_id": null,
    "validation_status": null,
    "secondary_validation_status": null,
    "secondary_validator_id": null,
    "reachable_on_submit": true,
    "raw_value": null,
    "decimal_separator": null,
    "validatable": false,
    "session_ident": null,
    "lock_version": 1,
    "validation_color": null,
    "validation_escalate": false,
    "validator_validation_date": null,
    "secondary_validation_date": null,
    "automatic_validation": false,
    "similar_value_id": null,
    "similar_value_count": null
}

POST values/{variable} - Add Evidence Notes for Hyperlink

Add a note to indicate where the evidence can be found.

curl https://api.gresb.com/api/v0/entities/{entity_id}/responses/{response_id}/values/PO_1_A1_EVD_NOTES_1 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<JSON

{
    "lock_version": 1,
    "value": "Our policies on environmental issues can be found within the second report on our public documents page."
}

{
    "id": 12345678,
    "analysis_id": 12345,
    "variable": "PO_1_A1_EVD_NOTES_1",
    "value": "Our policies on environmental issues can be found within the second report on our public documents page.",
    "created_at": {date},
    "updated_at": {date},
    "validator_id": null,
    "validation_status": null,
    "secondary_validation_status": null,
    "secondary_validator_id": null,
    "reachable_on_submit": true,
    "raw_value": null,
    "decimal_separator": null,
    "validatable": false,
    "session_ident": null,
    "lock_version": 1,
    "validation_color": null,
    "validation_escalate": false,
    "validator_validation_date": null,
    "secondary_validation_date": null,
    "automatic_validation": false,
    "similar_value_id": null,
    "similar_value_count": null
}

Upload File as Evidence

In order to upload a file as evidence, total of 3 requests should be send. First one is to indicate answer name, file type and the URL of the file, second one is to share notes, and final (optional) one to make the file accessible to investors within the Benchmark Report.

In this example, let us upload a PDF document as our second evidence for the indicator PO1 in Management > Policies.

To change a file with another one that was already uploaded to the Portal, make a POST request to the PO_1_A1_EVD_DOCID_2 endpoint with the document ID. Document ID is identified from the {DOCID} value.

POST /documents - Indicate Evidence Type and URL for File

Evidence documents which are not public hyperlinks can be uploaded to entities/{entity_id}/responses/{response_id}/documents endpoint. Answer name, evidence type, and URL are all mandatory fields and should be send within the same request body. Indicate file type as F.

curl https://api.gresb.com/api/v0/entities/{entity_id}/responses/{response_id}/documents \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<JSON

{
    "answer_name": "PO_1_A1_EVD",
    "lock_version": "0",
    "evidence_type": "F",
    "url": "https://gresb-prd-public.s3.amazonaws.com/2022/RE-Documents/Asset_Portal_Validation_Rules.png"
}

{
    "answer_name": "PO_1_A1_EVD",
    "item_number": 1,
    "evidence_type": "F",
    "report_url": "https://portal.gresb.com/reports/{report_id}/PO_3_A1_EVD/documents/1",
    "variables": {
        "TYPE": {
            "variable": "PO_1_A1_EVD_TYPE_2",
            "value": "F"
        },
        "DOCID": {
            "variable": "PO_1_A1_EVD_DOCID_2",
            "value": "123456"
        },
        "NOTES": {
            "variable": "PO_1_A1_EVD_NOTES_2",
            "value": null
        },
        "SHARE": {
            "variable": "PO_1_A1_EVD_SHARE_2",
            "value": null
        }
    }
}

POST values/{variable} - Add Evidence Notes for File

Add a note to indicate where the evidence can be found.

curl https://api.gresb.com/api/v0/entities/{entity_id}/responses/{response_id}/values/PO_1_A1_EVD_NOTES_2 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<JSON

{
    "lock_version": 1,
    "value": "Our policies on environmental issues can be found on page 12 of our ESG Policy Report."
}

{
    "id": 12345678,
    "analysis_id": 12345,
    "variable": "PO_1_A1_EVD_NOTES_2",
    "value": "Our policies on environmental issues can be found on page 12 of our ESG Policy Report.",
    "created_at": {date},
    "updated_at": {date},
    "validator_id": null,
    "validation_status": null,
    "secondary_validation_status": null,
    "secondary_validator_id": null,
    "reachable_on_submit": true,
    "raw_value": null,
    "decimal_separator": null,
    "validatable": false,
    "session_ident": null,
    "lock_version": 1,
    "validation_color": null,
    "validation_escalate": false,
    "validator_validation_date": null,
    "secondary_validation_date": null,
    "automatic_validation": false,
    "similar_value_id": null,
    "similar_value_count": null
}

As opposed to a public hyperlink, a file uploaded to the system is not visible to investors by default. To make the evidence file accessible to investors, set the sharing setting to true by sending 1 as value to the corresponding endpoint.

curl https://api.gresb.com/api/v0/entities/{entity_id}/responses/{response_id}/values/PO_1_A1_EVD_SHARE_2 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<JSON

{
    "lock_version": 1,
    "value": 1
}

{
    "id": 12345678,
    "analysis_id": 12345,
    "variable": "PO_1_A1_EVD_SHARE_2",
    "value": 1,
    "created_at": {date},
    "updated_at": {date},
    "validator_id": null,
    "validation_status": null,
    "secondary_validation_status": null,
    "secondary_validator_id": null,
    "reachable_on_submit": true,
    "raw_value": null,
    "decimal_separator": null,
    "validatable": false,
    "session_ident": null,
    "lock_version": 1,
    "validation_color": null,
    "validation_escalate": false,
    "validator_validation_date": null,
    "secondary_validation_date": null,
    "automatic_validation": false,
    "similar_value_id": null,
    "similar_value_count": null
}

Evidence Delete

Evidence documents can be removed by settng the evidence type, URL, notes, and sharing settings to null in the corresponding endpoints.

API Version History

All updates to our API will be documented in this section. If a backwards-incompatible update is released, all API users will be notified in advance and be given ample time to upgrade.

Version 2.04 – Feb 13, 2024

Introduction of country as a benchmarking factor (R1.1 and R1.2 merged into R1; DR1.1 and DR1.2 merged into DR1).
Introduction of multiple energy ratings.
Introduction of year as a mandatory field for building certifications.
Introduction of non-operational energy consumption by EV charging stations.

Version 2.03 – May 01, 2023

Removed user role and access scope from entities endpoint response example.

Version 2.02 – Mar 15, 2023

Reintroduced the user OAuth flow
Oauth token expires after 2 hours
Oauth token only allows access to entities which belong both to the user and data partner

Version 2.01 – Mar 03, 2023

Removed the section on /users since it became obsolete with the introduction of data partners.
Moved the notices on certifications and energy ratings to their own sections.
Clarified on the asset ownership % becoming a mandatory field.

Version 2.00 – Feb 08, 2023

Breaking change: Different authorization flow. Old tokens will be invalidated on April 1, 2023.
Added view-only UI for data partners.
New sandbox environment.

Version 1.99 – Dec 21, 2022

Major update: Release of the portfolio-level endpoints.
Added new Postman collection.
Documented the v0 portfolio-level endpoints.
Added list of portfolio response variables.

Version 1.02 – Apr 26, 2022

Specify the use of api.gresb.com as base URL.
Updated all json requests examples.
Removal of energy_ratings.id = 59 (became a certification).
New certifications accessible through GET /certifications on production.

Version 1.01 – Mar 01, 2021

Added optional asset_ownership field to the building characteristics section.

Version 1.0 – Feb 01, 2020

Breaking change: Introduced API version 1.0. Completely abandoned support for URLs with version 0.
Added more data fields for the 2020 assessment.
Added ability to view all available historical data.
Added ability to update historical data.
Added endpoints for certifications and energy ratings.
Updated documentation and example requests.

Version 0.94 – Jul 11, 2019

Change the rules when X-RateLimit-Remaining header appears.

Version 0.93 – Jul 04, 2019

Added set of headers X-RateLimit-Limit, X-RateLimit-Reset and X-RateLimit-Remaining to the batch operations endpoint. They contain information about available usage limits and possible throttling.

Version 0.92 – May 28, 2019

Added always_create and always_update keys in the batch batch operations endpoint. These operations are always successful, even if validation fails.

Version 0.91 – Mar 29, 2019

Added set of "greater than zero" validation rules based on directlymanaged and wholebuilding.
Added set of "maximum coverages" validation rules. No longer possible to report an asset without perfomance data.
Added set of "lfl-eligible" validation rules. If the data coverage did not change you'll have to report consumption for both years.

Version 0.90 – Feb 07, 2019

Breaking change: URLs have changed and now include the API version
Breaking change: The endpoint for batch operations has changed significantly
Major change: There is a single pool of asset data for each entity. All API partners get access to the same assets as the reporting entity. In the past, each API partner had access only to their own set of assets.
Major change: To ensure high data quality and integrity, we have added many more validations. As a result, you may find that some of your previously submitted assets are now considered invalid.

Version 0.20 – Dec 08, 2018

Decoupled the asset data from the response, allowing partners to submit asset-level data outside the regular survey period
Added new /api/entities endpoints
Deprecated the old /api/responses endpoints, which now redirect to the new /api/entities endpoints

Version 0.18 – Oct 08, 2018

Added parameter provider_id=0 to get asset data from the participant

Version 0.17 – May 08, 2018

Added a paragraph and formulas to the Threshold Values section

Version 0.16 – Apr 06, 2018

Added outlier thresholds
Updated links and added examples where to put data within the JSON requests, see data dictionary

Version 0.15 – Mar 16, 2018

Authorization domain is api.gresb.com, gresb.com was deprecated

Version 0.14 – Feb 12, 2018

Updated document for the 2018 assessment

Version 0.13 – Apr 24, 2017

Asset-level data dictionary formatting

Version 0.12 – Apr 24, 2017

Documented missing asset_size and dc_change

Version 0.11 – Apr 21, 2017

asset_size_tenant is now split into two fields asset_size_tenant_tenant and asset_size_tenant_landlord"

Version 0.10 – Mar 06, 2017

Update mentions of survey_date to use 2017 as an example
Rename two field names from asset dictionary published on Jan 26: asset_year should have been asset_const_year, asset_IDM should have been asset_ind

Version 0.9 – Jan 26, 2017

Updated data dictionary for 2017 assessment

Version 0.8 – May 04, 2016

Documented new /api/user resource

Version 0.7 – Apr 26, 2016

Documented asset_country field
Documented waste_diverted_lte_100 errors
Removed waste_alloc, not_negative errors
Corrected documentation for waste_lte_100, present errors

Version 0.6 – Mar 02, 2016

Corrected curl example in Step 2 - Exchange Authorization Code For Access Token

Version 0.5 – Feb 24, 2016

Corrected "scopes" parameter name in examples which should have been "scope"
Removed references to OAUTH flows that aren't fully supported

Version 0.4 – Feb 17, 2016

Documented ghg_offset and ghg_net fields
Documented was_wd_perc, was_dwe_perc, was_dr_perc, was_do_perc and was_oth_perc fields
Removed documentation for field was_r_pec which has been replaced by was_wd_perc and was_dr_perc
Adjust code examples for new waste diverted fields
Documented cov_lt_tot, cov_value_required, field_invalid, and waste_alloc errors
Updated design of API Authorization screens

Version 0.3 – May 15, 2015

"Basic Operations" now explains more about our uses of HTTP/REST/JSON
Cleaned up some styling
Removed commitment to auto-version the API by application
Added production URL and remove under-development warning
Documented optional major_renovation asset field

Version 0.2 – Apr 17, 2015

Added documentation sections on "Get Response" and "Update Response"
Added sample output to "Survey Response" examples
Added documentation of survey property of response objects
Removed incorrect sentence saying responses can be updated by name or manager
Change: The response fields: legal_status, property_type, country, survey_date are now read-only instead of optional

Version 0.1 – Feb 13, 2015

Initial version

Introduction

Basic Operations

Endpoints

Common HTTP Verbs

Common HTTP Status Codes

Request and Response Encoding

Date formats

API Authorization

Manage data partner account

Provide access to data partner

OAuth flow

Obtain OAuth 2.0 Credentials

Sample Application

Requesting API Access

OAuth Scopes

Example: Web Applications

Step 1 - Request Authorization

Step 2 - Exchange Authorization Code for Access Token

Step 3. Use Access Token

OAuth Errors

View-only UI

Reporting Entities

GET /entities

GET /entities/{entity_id}

Asset Data

GET /entities/{entity_id}/assets

GET /entities/{entity_id}/assets/{asset_id}

POST /entities/{entity_id}/assets

PATCH /entities/{entity_id}/assets/{asset_id}

DELETE /entities/{entity_id}/assets/{asset_id}

POST /entities/{entity_id}/asset_spreadsheet_export

Asset Batch Operations

POST /entities/{entity_id}/assets/batches

Asset Outliers

Asset Validation Endpoint

POST /entities/{entity_id}/assets/validation

Asset Data Dictionary

Asset Certifications

GET /certifications

Create certifications

Update certifications

Remove certifications

Asset Energy Ratings

GET /energy_ratings

Create, Update and Remove Energy Ratings

Portfolio Data

Variable Patterns

GET /lists

GET /lists/:slug

GET /entities/{entity_id}/responses

GET /entities/{entity_id}/responses/{response_id}

GET /entities/{entity_id}/responses/{response_id}/values/{variable}

POST /entities/{entity_id}/responses/{response_id}/values/{variable}

Portfolio Evidence

Upload Hyperlink as Evidence

POST values/{variable} - Indicate Evidence Type for Hyperlink

POST values/{variable} - Indicate the Hyperlink URL

POST values/{variable} - Add Evidence Notes for Hyperlink

Upload File as Evidence

POST /documents - Indicate Evidence Type and URL for File

POST values/{variable} - Add Evidence Notes for File

POST values/{variable} - Share File with Investors

Evidence Delete

API Version History