PensionPro API

Follow

The PensionPro API is a RESTful API that communicates using JSON over HTTPS. The endpoints for API are as follows:

 

https://api.pensionpro.com - Production version

 

Please note that the production endpoint uses the production database which contains your firm's live data.

 

Development Sandbox accounts can be provisioned on request so that your live data is not at risk while development occurs. Please click here to reach out to support to request a sandbox account.

 

 

Generating a Key

 

If you would like to get started using our API, you will need to be on a tier that supports access to the API, or have purchased the API Add-On. In order to make requests to the API, you will need to generate an access key. Please follow the steps below to get started:

 

  1. Log into PensionPro as a user with Maintenance Security Rights.
  2. Open the Firms/Locations screen in PensionPro from the Navigation Panel by clicking Maintenance > Firms/Locations > General.
  3. Click the More icon in the upper right corner of the Firm Information grid. Click Regenerate API key. Your new Firm API Key will be created and displayed. You can copy and paste the key into your code or our endpoint page (powered by Swagger) to make authorized calls.

 

To explore the API, simply click here and use your Firm API Key. To see the key in unobscured text, click the Show API Key button. Please note that you will also need to provide a username to an active login with each call you make as calls will have security based on that user. 

 

 

Call Limits

 

If you make several API requests in a short period of time, you may bump into the API rate limit for requests. When you reach the limit, the PensionPro API will return a status of 429 and stop processing any additional requests until a certain amount of time has passed. The body of the response will contain a message specifying the issue. Limits include:

 

  • Limit per minute
  • Limit per billing cycle
  • Concurrent file upload limit 
  • Concurrent file download limit 

 

The rate limits for the API feature on the Business tier are 100 requests per minute and 2,000,000 requests per month. 

 

You can use the following response headers to confirm the account's current rate limit and monitor the number of requests remaining in the current minute:

 

Rate-Limit: 700
Rate-Limit-Remaining: 699

 

You can monitor your requests for rate limiting problems by inspecting the HTTP response returned after each request. If you get a response code of 429, "Too Many Requests", you've hit the rate limit.

 

If a higher rate limit is necessary, a High Volume add-on can be purchased for $295/month. This add-on increases the limits to 300 calls per minute and 5,000,000 calls per month. To upgrade, please open a new Support request.

 

 

Catching Errors Caused by Rate Limiting

 

It's best practice to include code in your script that catches request errors caused by rate limiting. The HTTP response code the PensionPro API sends for request errors caused by rate limiting is 429, "Too Many Requests".

 

For example, a curl request that bumps into the rate limit might return the following response:

 

< HTTP/1.1 429
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Type: application/json; charset=utf-8
< Expires: -1
< Server: Microsoft-IIS/8.5
< RateLimit-Limit: 200
< RateLimit-Remaining: 0
< X-AspNet-Version: 4.0.30319
< X-Powered-By: ASP.NET
< Date: Mon, 13 Feb 2017 17:38:15 GMT
< Content-Length: 59
"The maximum allowed number of requests has been exceeded."

 

The response contains the following key information:

  • Status: 429
  • RateLimit-Limit: 200
  • RateLimit-Remaining: 0

 

The 429 status code means too many requests. Your code should stop making additional API requests until enough time has passed to retry.

 

 

Reducing the Number of API Requests

 

Be sure to make only the requests that you need. Here are areas to explore for reducing the number of requests:

 

  1. Optimize your code to eliminate any unnecessary API calls.

  2. Use expands on parent items instead of querying single items by the parent ID where applicable.

  3. Cache frequently used data.

 

 

You can cache data on the server or on the client using DOM storage. You can also save relatively static information in a database or serialize it in a file.

 

 

Regulating the Request Rate

 

If you regularly approach or bump into the rate limit, consider including a process in your code that regulates the rate of your requests so that they're distributed more evenly over time. This is known as a throttling process or a throttling controller. Regulating the request rate can be done statically or dynamically. For example, you can monitor your request rate and regulate requests when the rate approaches the rate limit.

 

To determine if you need to implement a throttling process, monitor your request errors. How often do you get 429 errors? Does the frequency warrant implementing a throttling process?

 

 

Frequently Asked Questions

 

  • Is there an endpoint that returns all endpoints for a resource, including the different rate limits and times to retry?
    No, we don't provide a rate-limit endpoint.

  • What happens when the rate limit is reached?
    The request isn't processed and a response is sent containing a 429 response code. 

  • Will batching calls reduce the number of API calls? How about making parallel calls?
    No, batching won't reduce the number of API calls.

  • Why am I receiving a "Missing apikey and username" error when I try to test a call on the API Docs site?
    Before a test call can be made,     select the Authorize button at the top-right of the tag list and enter the firm API key and username, separated by a pipe ( | ) character.