Getting Started with the Holistiplan API

This guide will walk you through the steps you need to take to make your first API call to the Holistiplan API and go over how these calls can be made in Postman

💡 We're in the process of making our Public API widely available, but at this time we evaluate access on a case by case basis. Please reach out to our team at support@holistiplan.com and we'll help evaluate whether your firm would be a good candidate to use this feature.

 

Click here to access the Holistiplan API Documentation

I. Credentials

1. To get started with the Holistiplan API you'll need to generate a set of Client Credentials. These credentials can be generated by a Firm Admin by navigating from the Holistiplan home page to Settings > Security Settings where you can find the API Keys box seen below.

If you don't see this on the Security Settings page, please reach out to support@holistiplan.com and ask for OAuth Self Serve to be turned on for your firm

2. Next press + Create New and the modal seen below will display. Here you'll want to name your application, and select a user to assign the credentials to, the click Save

3. Once saved, you're credentials will populate back in the API Keys Box. You will want to copy both the Client ID and Client Secret as these will be used to generate the authentication token you'll need to start making API calls.

II. Manually Generating a Bearer Authorization Token 

The first call you'll need to make whenever you want to access the Holistiplan API is to the /o/token/ endpoint. This will generate a Bearer Token that will then be used to make all subsequent calls to the API

Below is an example of how to make this call in Postman. In the body of the request you will need to pass the following fields: grant_type | client_id | client_secret | scope

Note that this is a POST request and that the scope is set to read write.

A token will still be generated for you if the scope is set incorrectly, however you will encounter errors when making subsequent calls if the scope is just set to read or write only.

Once this call is made, you should receive a 200 OK response, with your access_token.  This token will be valid for 10 hours before it expires.

You can then copy this token, and add it in to your subsequent calls in the Authorization Header as seen below

If you receive an error at any point in the Token configuration process, please take a screenshot of the error as well as the call you are trying to make and send them to support@holistiplan.com

III. Setting Up Automatic Authorization in Postman

Another authentication option you have if you're working in Postman is to set up Automatic Authorization directly on your main API calls

For example, below is a GET request we're making to the /clients/ endpoint. If we navigate to the Authorization Tab we can select OAuth 2.0 as our Authentication Type as seen below

Once selected scroll down to Configure New Token. Here you can name the token, then select Client Credentials to make sure only the necessary fields are showed for the Holistiplan authorization.

Next enter the Access Token URL found here: https://app.holistiplan.com/o/token/

Following this enter your Client ID, Client Secret, and Scope

Note that Scope is set to read write.

A token will still be generated for you if the scope is set incorrectly, however you will encounter errors when making subsequent calls if the scope is just set to read or write only.

Once all the data has been entered, click on Generate New Access Token, and wait for the new token to be generated

If all of the above data was set properly, you will see a Modal pop up displaying the new Access Token

Next select Use Token. This will close the Modal and populate the Current Token section on the Authorization Page seen in the next image.

Once the token has been initially set, it will populate here. The benefit of doing this on the call itself, is you have the ability to refresh the token by selecting Refresh directly, or by turning on the Auto-refresh Token flag as seen below

Finally set the Header Prefix to Bearer

To validate that this was done properly you can navigate to the Headers tab and display the Auto-Generated Headers. Here you should see the Authorization header populated with the value Bearer <Token>

IV. Making API Calls

API Call Base URL: https://app.holistiplan.com/api/public/v1/

If you went through the process of setting up your Bearer Token under the Authorization tab as shown in Section III, you should be all set up to start making calls. 

If you made a call manually to the /o/token/ endpoint, the Bearer Token can be added into your API call Headers as seen below:

With authorization configured, find the endpoint you would like to make a call to from our API documentation here, and append the endpoint you would like to call to the end of the API Call Base URL found above.

For example if you would like to call the /households/ endpoint the full URL for this call would be: https://app.holistiplan.com/api/public/v1/households/

Note the request method for the call you are trying to make, as each of our endpoints can accept several different methods for separate actions you would like to take. As an example a POST request on the /households/ endpoint would create a new household, whereas a GET request on the same /households/ endpoint would list available households on your firm.

Many of our API requests can also take both request parameters and/or a request body. In Postman these can be configured by navigating to the Params and Body tab respectively and adding in the appropriate fields. 

While making API calls, if you ever run into an error, please take a screenshot of the error received along with the API request you are trying to make (Please incude the Body of the request and any Params added) and send those to support@holistiplan.com

V. Additional Resources

If you would like to download Postman, that can be done here

You can also find additional details on how to work with Postman's Authorization here

For an overview of how RESTful APIs like ours work, and what each of the request methods do, please read this article published by Amazon AWS