PensionPro API

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

 

Warning: This article covers v2 of the API. Although v1 is still in effect and can continue to be utilized, some functionalities—such as API key management—are not supported in the legacy version. v1 will be deprecated on May 31, 2026; for guidelines on converting, refer to the article Upgrading to API v2.

 

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

 

Note: The instructions in this section only apply to v2 of the API. If using v1, refer to the Firm API Key section of the article Firms & Locations.

 

API keys are added and controlled within Firm & Location maintenance:

 

  1. Navigate to Maintenance > Firms/Locations. A new Firm tab opens.
  2. 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 Editedit.png and Deletedelete.png 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:

 

  1. Select Addadd.png at the top-right of the grid. The Add API Key window displays.
  2. 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.
  3. Create a Name for the key.
  4. (optional) Select any PII Endpoints that the API key should be allowed to access.
  5. (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.
  6. 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.
  7. 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

 

Note: All endpoints not included in the above list do not contain PII and can be accessed without restriction by any API key.

 


 

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.

 

Warning: An API key will cease to function as soon as it is regenerated or deleted. The key cannot be recovered.

 

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 Moremore_options.png > 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 Deletedelete.png 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.

 

Note: Ensure that you are referencing the correct version of the API by using the dropdown at the top-right of the page.

 

The API Docs are also interactive, providing an environment for calls to be built and tested within a user interface. To get started:

 

  1. Select the green Authorize button at the top-right of the tag list.
  2. Enter a valid combination of full API key and username, separated by a pipe ( | ) character (in the format xxxxxxxxxxxxxxxxxxxxxxxx|username), then select Authorize.
  3. Expand the desired endpoint. At the top-right of the endpoint's entry—in the Parameters header— select Try it out.
  4. 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.

 

Tip: The details of the request will be included along with the server response. If a test call is successful, it can be copied from the API Docs; this is a great way to ensure correct syntax during development.

 


 

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:

 

  1. Navigate to Maintenance > Firms/Locations. A new Firm tab opens.
  2. 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 Editedit.png and Deletedelete.png options on the right-hand side. Select Refreshrefresh.png to manually update the grid.

 


 

Adding a Webhook

 

Note: Only one webhook may be established at a time. A new webhook cannot be added until the prior one is removed.

 

To create a new webhook:

 

  1. Select Addadd.png at the top-right of the grid. The Add Webhooks window displays.
  2. Enter the URL that will receive the webhook requests.
  3. 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.
  4. 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 Moremore_options.png > 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 Moremore_options.png > 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.