Using the API (Desktop)

Looking for the Web version of this article?

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. Login to PensionPro as a user with Management rights
2. Open the Firms/Locations screen in PensionPro from the menu by clicking on Maintenance > Firms/Locations.
3. Once the Firms/Locations Information tab appears click on the “Regenerate API key” button in the middle of the screen. Your new Firm API Key will be created and displayed. You can copy and paste that key into your code or our endpoint page (powered by Swagger) to make authorized calls.

To explore the API, simply navigate to the URL above with a browser 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 because calls will have security based on that user. If you do not see this on the screen please contact support to enable access to the PensionPro API. 

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 doesn't have free API included in it, you can purchase a package to access the API as listed below

If you make a lot of API requests in a short amount 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 more 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.

Make sure you 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.

   For example, are some requests getting data items that aren't used in your application? Are retrieved data items being put back to your PensionPro product instance with no changes made to them?

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