The PensionPro API is a powerful tool for working with PensionPro data outside of the application itself. With a little bit of creativity and development know-how, firms can automate their processes, build their own tools, or integrate with third-party software. This article will discuss managing aspects of the API and assist firms in getting started with this functionality.
Tier Availability: Team, Business
Article Contents
What To Know
The PensionPro API is a RESTful↗ API that communicates using JSON over HTTPS.
A list of available endpoints and data models can be found at api.pensionpro.com. This page also serves as an interface for testing and building calls.
Security is maintained via the use of API keys, which are controlled by the firm and must be passed with each API call to verify its legitimacy. These keys may be optionally be restricted from accessing records containing personally identifying information (PII). API keys can be revoked at any time. A valid PensionPro username must also be passed with the call; changes made to records via the API will be recorded to the Audit Log of the Employee who executed the request.
API calls are directed toward the firm's production database, which contains live data. Upon request, a sandbox account can be provisioned so that live data is not at risk while development occurs. To get started, please submit a Support request ticket to the PensionPro Help Desk.
API Key Management
Security Rights Required: Add/Edit API Access, Maintenance
API keys are added and controlled within Firm & Location maintenance:
- Navigate to Maintenance > Firms/Locations. A new Firm tab opens.
- Select the API Access view from the list on the left.
The API Access grid contains any API keys that have already been generated, along with their descriptions and the dates the keys were last used to make a call. Hovering over an entry in the grid displays the Edit and Delete
options on the right-hand side.
Above the grid, PensionPro displays the total number of API calls that have been made in the current cycle, providing a simple means of measuring usage against the monthly limit. For more information, refer to the section Call Limits.
Adding a New Key
To create a new API key:
- Select Add
at the top-right of the grid. The Add API Key window displays.
- Note that the API Key field has generated a randomized 24-character key.
- This character string cannot be edited.
- The full key will be lost once the window is closed. Either utilize the key immediately upon creation, or copy the key to a safe location.
- Create a Name for the key.
- (optional) Select any PII Endpoints that the API key should be allowed to access.
- Refer to the section Personally Identifying Information, below.
- (optional) Add a Description.
- For firms who generate many keys for fine control over their usage, the Description can be a crucial asset to keep API access organized.
- To the right of the API Key field at the top of the window, select Copy to Clipboard.
- To ensure that the generated key is not immediately lost, the new entry cannot be saved until this action is performed.
- Select Save.
Personally Identifying Information
It is rarely good practice to give individuals full API access to areas of PensionPro containing PII when this information is not needed. This is especially true for firms that outsource API development to third parties. For this reason, API keys can be configured to only allow access to the data that is relevant for the task being performed. A 401 "Unauthorized" error will be returned if an API key is used in an attempt to retrieve or alter information it has not been permitted to access.
Data from the following categories will be restricted unless the API key has been configured to allow access; permissions for each category are added individually to allow for fine-tuning:
- Distribution Information Details
- Employees
- Family Members
- Files
- Interactions
- Notes
- Participants
- To-Dos
Regenerating & Deleting Keys
In the event that an API key has been lost, potentially compromised, or is no longer needed, it can be deleted entirely or simply swapped out for a new key with all the same settings.
To replace a current key with a new one while keeping the settings of the original, click to select the key within the grid, then select More > Regenerate API Key. A dialog asks to confirm this action; select Yes to continue. An updated API key will then be displayed in a new window; select Copy to Clipboard, then Save. As with adding a new API key, the full updated key will be lost when the window is closed.
Alternately, to remove a key, hover over it in the grid, then select Delete on the right-hand side.
Using the API Docs
The page at api.pensionpro.com provides a full list of endpoints and schemas for the PensionPro API, separated by category. Select an endpoint to view it in more detail; doing so will display the parameters that may be used in the call as well as the applicable data model.
The API Docs are also interactive, providing an environment for calls to be built and tested within a user interface. To get started:
- Select the green Authorize button at the top-right of the tag list.
- Enter a valid combination of full API key and username, separated by a pipe ( | ) character (in the format xxxxxxxxxxxxxxxxxxxxxxxx|username), then select Authorize.
- Expand the desired endpoint. At the top-right of the endpoint's entry—in the Parameters header— select Try it out.
- Enter any parameters as appropriate, then select Execute. The API Docs will generate and submit the request with the given parameters; the reply from the server will be displayed below in the Responses section.
Call Limits
To safeguard servers against negative performance issues associated with third-party API use, PensionPro imposes the following limits:
- 100 requests per minute
- 2,000,000 requests per month
- 2 concurrent file uploads
- 2 concurrent file downloads
The PensionPro servers will return status code 429 "Too Many Requests" in the event one of these limits is exceeded; further requests will be likewise rejected until the appropriate amount of time has elapsed.
The monthly request limit can be tracked via the counter above the API Access grid within Firm & Location maintenance. The requests-per-minute limit is reported in the x-ratelimit-limit and x-ratelimit-remaining headers of every server response.
The next section provides suggestions for lowering the number of API requests to avoid reaching the call limits listed above. However, if optimized code is insufficient to resolve errors caused by these restrictions, PensionPro can provide a High Volume add-on for $295 /month. This add-on increases the call limits to 300 requests per minute and 5,000,000 requests per month. To upgrade, please submit a Support request ticket to the PensionPro Help Desk.
Reducing "Too Many Request" Errors
The simplest method of avoiding call limit restrictions is to reduce the number of requests that are made to PensionPro's servers. Consider investigating the following options:
- Optimize code to eliminate calls that aren't being used, and identify areas where multiple requests to the same endpoint could be condensed into a single call.
- Use Expand parameters on parent items to retrieve data from linked children, as opposed to querying the children individually by parent ID.
- Implement caching solutions such as web/DOM storage↗, or save temporary information to a local file or database.
- Utilize Webhooks as opposed to polling PensionPro for updates.
If the number of requests being made are regularly exceeding the minute-by-minute limit and resulting in failed calls, it may be worth including a process in the code that regulates the rate of requests so that they are more evenly distributed over time. This type of throttling could be accomplished statically (execute the call every X seconds) or dynamically (if nearing the rate limit, delay the request).
Webhooks
Security Rights Required: Maintenance
In some situations, no action needs to be taken until a change is made within PensionPro. While it is possible to make regular calls to the PensionPro servers and check for updated data, it can be more efficient to establish a webhook instead. Implementing a webhook means that PensionPro will transmit details of the change after it happens, making it unnecessary to repeatedly poll for new information.
A webhook can notify of additions, updates, and deletions affecting the following endpoints:
- Client
- Contact
- Plan
- Project
- Task
Webhooks are added and managed within Firm & Location maintenance:
- Navigate to Maintenance > Firms/Locations. A new Firm tab opens.
- Select the Webooks view from the list on the left.
If a webhook has already been established, it will be displayed within the Webhooks grid. Hovering over the entry in the grid displays the Edit and Delete
options on the right-hand side. Select Refresh
to manually update the grid.
Adding a Webhook
To create a new webhook:
- Select Add
at the top-right of the grid. The Add Webhooks window displays.
- Enter the URL that will receive the webhook requests.
- Select at least one Endpoint to receive updates for.
- There is no limit to the number of Endpoints that may be selected, but it is good practice to only add the Endpoints that are required for the code to function.
- Select Save.
A request will immediately be sent to the provided URL to verify that it is a valid target. If the request fails, PensionPro will display an error, and a new URL will need to be provided before the webhook can be added.
Managing Webhooks
Any changes made in PensionPro that affect the data within any of the established endpoints will be queued as a POST request; queued requests will be transmitted to the receiving URL in 5-minute intervals. A log of sent requests can be obtained by clicking to select the webhook in the grid, then selecting More > Export Request Log. This log includes the request date/time, the entity type that triggered the request, and the response from the receiving URL.
After the webhook is created, a Shared Key will be provided in the grid. This key is transmitted in the header of webhook requests, making it possible to confirm that the request was sent from PensionPro.
The State of the webhook will also be included in the grid. In the event the webhook receives an error response from the receiving URL, State will display Error and no further requests will be sent. Errors can be reviewed by exporting the Request Log as detailed above. Once the issue is resolved, click to select the webhook in the grid, then select More > Reactivate to return the webhook to an Active State so that it may resume sending requests.
Frequently Asked Questions
-
Will batching calls reduce the number of API calls? How about making parallel calls?
No, these methods will not reduce the number of calls made to the server.