It’s official: This month marks the completion of the bringing out legacy Deal Export and Portfolio Export APIs into complete parity with Next Gen. All endpoints found within the Legacy APIs can be called from our Next Gen instances.
In addition, we’ve added a new field to our standard endpoints to help keep better track of spaces and deprecated a broker object that was adding more questions than clarity.
New API Features
In Asset added size to so the building’s total spaces can also be tracked at the building level. See screenshot below for where it can be found on in the Edit Building page:
The "size" field from the Edit Building page now returns in the Asset endpoint
Upcoming
We’re currently working on
the ability to exclude options from expired leases for customers using our MRI API integration
Investigating deal_terms performance and potential improvements that can be found
In our continuing effort to bring the legacy Deal and Portfolio APIs to parity with Next Gen endpoints, this month’s enhancements are focused on making financial information more readily available in Budgets, Deal Terms, and Lease Terms. Users who rely heavily on financial data will now be able to pull the below objects directly from the respective endpoint without having to link back to the financials endpoint with nested IDs. All new fields are returned in a standard format for consistency across the endpoint. As a result, we have deprecated certain fields within the Financials endpoint to maintain consistency with the new objects mentioned.
Additionally, we are introducing a new Next Gen endpoint for Appraisals, which will have the same attributes as Budgets (but not Blended Budgets and Asset) relationships.
New API Features
A new Appraisals endpoint for users who rely heavily on financial modeling and forecasts
In the Deal endpoint added agent phone extension to complete broker information
In the Deal Terms and Budget endpoints, added as objects that our seasoned users will recognize:
base_rents
free_rents
rent_escalations
percentage_rents
reimbursable_expenses
other_incomes
costs
Note: The attributes above will still be in the response even if there's no data. An empty list will be returned.
In the Deal Terms endpoint only, added remaining_lease_obligations
In the lease terms endpoint, added
base_rents
free_rents
reimbursable_expenses
commissions
other_incomes
In the Space endpoint added electrical
In the Assets endpoint, added und
Deprecations
In Budget endpoint,
tenant_improvements structure
building_improvements structure
other_fees structure
In Deal Terms, within the commissions object
created_at
updated_at
Upcoming
We anticipate a new Tours endpoint to be available by early April 2023. This will allow users to export tour metadata for enhanced reporting and analytics.
Overview / Summary
Enhancements were added to multiple endpoints based on customer feedback and performance analysis. Our current initiative is import nodes from the Legacy Deal Export API so users can have full access to the fields in the Deal Export but with the compartmentalization of the Next Gen APIs.
For this month’s update,, we’ve made additions to Assets, Budgets, Deal Terms, Deal Stages, and Options
We’ve also made backend enhancements that will improve performance and maintainability.
New API Additions
In the Deal Stages endpoint, added EndDate, and description to carryover functionality from our Legacy Deal Export API
In the Deal Term endpoint,
Comparative Lease Term object can be utilized to retrieve: Commencement Date Expiration Date Execution Date Rentable Size
This will allow legacy users to replicate the Deal Previous Term function in the Legacy Deal Export API
Added npv_per_area and description fields to eliminate the gap between Next Gen and Legacy Deal Export
In the Budgets endpoint, we have carried over legacy fields from the Legacy Deal Export API:
ProposalType is now exposed as analysis_type
NEROverride is now exposed as ner_override
NPVperSqFt is now exposed as npv_per_area
TotalNPV available as total_deal_value
LeaseType is available as structure
MiscDescription available as description
TotalIncome available as total_rent
The Assets endpoint now exposes
building_region based on a free-text field in the “Edit Buildings” form in the front-end. This will allow for greater use of free-text fields for reporting and analytics (See reference image below)
Market field that is associated with the sub-market of a building
In the Proposal endpoint, added proposal_label to naturally identify proposal names as they’re labeled in the front-end UI
Deal Terms endpoint now exposes total_commissions as object, eliminating a gap from the Legacy Deal Export API
In the Options endpoint added created_at and updated_at date fields
Bug Fixes
Internal Server Errors related to pagination have been resolved
Upcoming
Financial data such as Base rent, Percentage rent, Reimbursable expenses, Costs, Other Incomes will be available in the Budgets and Deal Terms endpoints. This will mimic the way the nodes were previously delivered in the Legacy Deal Export API
Nested Financials will be deprecated
Due to the lack of Changelog posts since March 2022, the following is a list of exposed endpoints, enhancements, and bug-fixes specifically related to the NextGen APIs from April 2022 to January 2023.
VTS will continue to publish changelog posts at least once per month to summarize any changes or confirm that no functional endpoints or fields have been added.
April 2022
Deal Comments Pagination error fixed
Deal Financials: Include relationship to “Tenant Improvements”
Options: Add Created at and Updated at fields
June 2022
Financials: Filter by term_type enabled
July 2022
Financials:End_date for “Free Rents” bug fix
Financials: Displaying free_rent duration in API Response
Tenants API endpoint: the name attribute will now always return the reported tenant name (the name of the tenant as inputted on the lease or deal). We also added a global_tenant_name attribute which returns the global tenant name. The global tenant name is the "cleaned" tenant name as identified by VTS' Tenant Network Services. This is the same as the "linked" or "anchored" tenant name. For more details, please see https://help.vts.com/hc/en-us/articles/4408622298395-Tenant-Network-Services-Overview-FAQs
Options API endpoint: added support for a non-nested Options endpoint. Note we are aware of an issue when filtering this endpoint on Lease Term and are working on a fix
Deal Tasks API endpoint: added support for a non-nested Deal Tasks endpoint
Budgets and Blended Budgets endpoints
A quick note on using the new Budgets and Blended Budgets endpoints -- we're working through some performance issues with these endpoints and recommend requesting fewer than 40 records for any call to these endpoints. We are working on making them more performant and aim to increase this limit to 100 records.
Note that budgets are associated with assets, spaces, and blended budgets but are not directly associated with deals. Rather, blended budgets are directly associated with deals and individual budgets are associated with deals through their blended budget relationship. For more information on budgets, please see our Help Center documentation
Blended budgets allow a user to compare a proposal against an aggregation of multiple budgets. For more information on blended budgets, please see our Help Center documentation
Calculated Metrics update
The calculate metrics are now considered generally available in the Deal Terms endpoint. Note that we do not support returning the NPV and IRR values as their long compute times may exceed our API time-out response limits. We are working on supporting these two values in the endpoints but do not have an estimated date of availability.
We do not have an ETA for when calculated metrics will be available in the Lease Terms endpoint.
Financials API endpoint (for both lease term and deal terms): added support for improvements, lease incentives, and other credits
Tenant Updates API endpoint: fixed a typo in the 'owner' label and renamed the relationships label 'property' to 'asset' to align with our standard nomenclature
Calculated metrics are represented on the VTS Lease front-end in the 'Proposal' tab under the 'Metrics' heading. These include fields such as NER, NPV, Net Rent, and GAAP Rent.
Calculated metrics are computed using a proposal's or deal term's various input parameters (duration, base rent, escalations, options, expenses and recoveries, and other costs and revenues). Some metrics are specific to a deal or lease term and some metrics are specific to a proposal. Other calculated metrics exist for both deal or lease terms and proposal objects. For example, consider a proposal that has 2 deal terms. Each deal term will have its own calculated NER value, and the corresponding proposal will have a NER value that is computed from the NER values of its two associated deal terms. Therefore, the deal and lease term endpoints will return an NER value and the proposal endpoint will return a possibly different NER value.
Note that returning the calculated metrics is in a pilot phase. Please reach out to your VTS rep to have these fields enabled for your API credentials.
Financials endpoint objects: Improvements, Incentives, and Other Credits
We added some new objects to the Financials endpoint (for both deal terms and lease terms) capturing expenses and recoveries associated with a deal or lease. This includes improvements of type building or tenant, lease incentives, and other credits. These are found on the VTS Lease front-end in the 'Expenses and Recoveries' section of a given deal or lease term. For more details on these objects, see the VTS Lease data dictionary at https://help.vts.com/hc/en-us/articles/4403703750939-VTS-Lease-Data-Dictionary.
The 'Global Tenants' endpoint enables API access to the new VTS tenant linking feature. This feature anchors tenant entities to a standard tenant entity across your portfolio, regardless of how those tenant names are inputted into a lease or deal in the VTS database. This also allows a user to understand the hierarchy of their tenant entities via an Ultimate Parent ID relationship
The 'Tenants' endpoint contains a relationships.global_tenant_id attribute, which links to the tenant's Global Tenant ID.
Additional notes on the fields in this new endpoint:
Attribute
Description
attributes.name
This is the cleansed, global name of the tenant
attributes.industry
This is the tenant’s Global Tenant industry, which may come from the client’s accounting system OR from CapIQ
Note that this could be different from this tenant’s industry in the 'Tenants' endpoint, which is the industry as reported by or pulled from your accounting system.
attributes.cap_iq_id
This is the CapIQ company ID. You may only find value from this field if you have a separate CapIQ datafeed that you need to relate to your data from VTS.
relationships.data.ultimate_parent.id
This is the Global Tenant's 'Ultimate Parent Global Tenant' ID
New Feature: Filter API calls by Updated Date
You can now filter the result set for your API requests to return only data that has been created or modified since a given date. You can filter by date or timestamp. Value should be provided in ISO8601 format.
All times are interpreted in the UTC time zone.
How to use:
For any endpoint with a 'Last Updated' field, append this clause to the API call:
?filter[updated_since]=YYYY-MM-DD HH:MM:SS
Additional Notes:
The YYYY-MM-DD is required, but HH:MM:SS is optional
The parameter value should be formatted in ISO8601 format (it may still parse in other date formats, but may produce unexpected results; however, it is guaranteed to work when given a valid ISO8601 date)
The time zone is always interpreted as UTC (unless a timezone offset is explicitly mentioned)
curl -X GET -u "<api_key>:<api_secret>" "https://api.vts.com/api/v1/assets?filter[updated_since]=2021-10-12"
