Follow

PensionPro 2.0 - Using the API

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 Management rights.
  2. Open the Firms/Locations screen in PensionPro from the Navigation Panel by clicking Maintenance > Firms/Locations.
  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

The following grid outlines the amount of API requests available on each tier of our software.  If the tier you are currently using does not include use of the API, you can purchase a package to access the API as listed below:

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 both the add-on of the API to Premium, as well as the inclusion of the API feature in Business 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.

 

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.

 

FEATURE FEEDBACK

Was this article helpful?
0 out of 0 found this helpful

Comments