On August 19, 2024, PensionPro introduced version 2 of its API. v2 replaces v1 and provides additional features, increased security, and back-end optimizations. Firms that are still using v1 of the API will need to update their applications and scripts prior to May 31, 2026, at which time support for v1 will be removed. This article will highlight areas to focus on during your transition so that you are fully switched over before v1 is turned off.
Article Contents
Configure Keys
The firm API key that was used in v1 will not carry over to v2; you will need to navigate to the new API Access view within Firms/Locations Maintenance to set up an API key for the new version. However, some new functionality has been added in v2 to enhance API key management:
Multiple keys. PensionPro now allows you to create and manage multiple API keys. These keys can be distributed to different development teams or used to silo unique areas of integration. The API Access grid also records the date each key was last called to better monitor usage.
Personally Identifying Information (PII) security. API keys can now be configured to allow or reject access to endpoints that could contain PII. This adds another layer of protection against misuse, ensuring that a key can't be used to retrieve PII that isn't relevant to its function.
With these additions, you may want to review where your old API key was being used and what data it was accessing. Then you can consider which permissions make the most sense for the new key, or even establish multiple keys with more finely-tuned access rights.
Convert Code
Requests in v1 call the URL https://api.pensionpro.com/v1/[endpoint & parameters]. Within the URL, /v1/ will need to be replaced with /v2/ to reference the updated API.
Additionally, some limitations were applied to various areas of v2 to improve efficiency and security. This includes the following changes:
| Change | Example |
|
Linked models that can be accessed more efficiently from another endpoint can no longer be expanded. |
In the Get Plan by PlanId endpoint, the linked model Projects can no longer be expanded. Instead, use the Get All Projects By PlanId endpoint. |
|
Linked models no longer contain properties other than the candidate/key properties. |
In the Get Project by Id endpoint, the linked Plan model can be expanded but only contains basic information, such as Name and ID. Use Get Plan by PlanId for retrieving these details instead. |
|
Results filtering can now only be performed on certain properties. |
In the Get Plan by Client Id endpoint, filtering can be performed on the Name and InternalPlanId (among others), but can no longer be performed on properties such as FilingStatusId. |
Once you update the URLs to point to v2, review your existing calls and surrounding code and ensure everything functions as expected. If not, it may need to be reworked to facilitate the above restrictions.
Replace Polling
In v1 of the API, if you wanted to know when an update was made to PensionPro data, you had to periodically call to see if the data had changed. With v2, you now have the option to establish a webhook so that PensionPro alerts you when calls are made to certain endpoints. To do so, you'll first need to set up a listening URL that monitors and handles incoming requests, and then enter that URL into the Webhooks grid in PensionPro.
With a webhook in place, you can eliminate functions that regularly poll the PensionPro servers to check for updates, which can greatly reduce the number of calls that you make. Keep in mind that a webhook can only be configured to transmit changes made to the following endpoints:
- Client
- Contact
- Plan
- Project
- Task
Continue Testing
As mentioned earlier, v1 of the API will remain operational until May 31, 2026. Getting started with conversion sooner rather than later will give you more time for testing and troubleshooting. Remember to make use of the API Documentation to help build and test calls to ensure that the syntax of a request is correct. If some aspect of the API is no longer working as expected, the PensionPro Support team can help you resolve issues before the v1 cut-off.