Postman for API Environment

PlanSource provides developers with an API environment to test against our endpoints by using Postman. This environment provides developers an easy-to-use programming alternative that's ready to go in minutes. Use the following guide to get started today.

Download Postman

To download Postman...

1. Visit the URL https://www.getpostman.com/apps.
2. Follow the on-screen instructions by Choosing your platform and clicking the Download button. The download should only t a few minutes.
3. Open the Postman-{platform}-{version}-Setup.exe file once downloaded. A loading screen saying Installing will appear and will take a few minutes to setup.
4. Once installed, Postman will load and you should see a workspace called My Workspace open.

Import PlanSource's API Collection

Now that you have Postman installed and have a working workspace, it's time to import PlanSource's API Collection.

1. Right click on the Run in Postman button to Open link in new tab.
2. Navigate to the new window and copy the URL for it.
3. Navigate to Postman, and click the Import button at the top left of the workspace.
4. Choose the option Import from Link and paste the URL copied from step 6.
5. Click the Import button, and wait for a collection to appear titled PlanSource's API Collection on the left hand side of the your workspace.

Import PlanSource's API Data Environment

To import PlanSource's API Data Package for Postman, please contact [email protected]. The data package is a .json file that needs to be imported like the collection was imported above. Instead of importing using a link, you will import using a file that will be sent to you from PlanSource. Make sure to include in your email's subject "Postman API Data Package Request".

1. Navigate to Postman, and click the gear icon in the top right corner.
2. Click the Import button.
3. Click the Choose Files button and select the PlanSource API Data Package (the API Testing.postman_environment.json file sent to you).
4. The environment should import into your Postman environment.

Set Your Variables

Before you can start making calls to PlanSource's endpoints, you will need to set up some critical variables. If you skip this step, all of your API calls will error out. The variables you will need to set are:

• lookup_code
• plansource_admin
• secret (user key)

These three variables are configured on PlanSource's side, so you will need to reach out to your PlanSource administrator point of contact to retrieve these. Once you have these variables, here is what you'll need to do.

1. Open the Postman application.
2. Select the API Testing environment from the drop-down menu in the upper right corner (this may already be selected since you just imported it).
3. Click the Environment Quick Look icon in the upper right corner (it looks like an eyeball).
4. Click the Edit button next to the API Testing label.
5. Enter the PlanSource provided values for lookup_code, plansource_admin, and secret.
6. Once entered, click the Update button to save these values.

📘

Signature Invalid?

Getting a signature invalid error? Make sure your values for lookup_code, plansource_admin, and secret are correctly entered. These values are case and space character sensitive. So be careful when inputting!

Make Calls to the Endpoints

Now that you have PlanSource's API Collection imported, it's time to make calls to PlanSource's endpoints. There are many endpoints under the six categories of API:

• Demographic
• Payroll
• Collections
• EOI
• Coverage
• Administrators

Get Subscriber Meta

This section will show how to call the Get Subscriber Meta endpoint. Let's begin!

1. Begin by clicking on the folder labeled OAuth Token from PlanSource's API Collection, and then click on the POST call to /oauth/v2/token. (There is only one item in this folder, and it is used to generate an access_token)
2. Click on the blue Send button at the top right of the workspace. This will initiate the POST call, and it will return an access_token in the body of the workspace.
3. From the collection, click on the Demographic folder, and then click on the Get Subscriber Meta endpoint.
4. Click the blue Send button at the top right of the workspace. This will initiate the GET call, and it will return the meta response. From the response, you can see the ID's for payroll schedules, the list validated field values, and more!

Post Subscriber

This section will show how to call the Post Subscriber endpoint.

1. Begin by clicking on the folder labeled OAuth Token, and then click on the POST call to /oauth/v2/token. (generates an access_token)
2. Click on the blue Send button at the top right of the workspace. This will initiate the POST call, and it will return an access_token in the body of the workspace.
3. Click on the folder labeled Demographic, and then click on the Post Subscriber endpoint.
4. Click on the tab labeled Body.
5. Enter all of the subscriber's information into the data fields (utilize the data from the GET Subscriber Meta call if you need to).
6. Once all of the information is entered, click on the blue Send button at the top right of the workspace. This will initiate the POST call, and it will return the created subscriber's information if there was no error.

You can check to see that this worked by logging into PlanSource's Benefits Admin site and checking for that subscriber under the tab labeled Employees.

Get Subscribers

This section will show how to call the Get Subscribers endpoint.

1. Begin by clicking on the folder labeled OAuth Token, and then click on the POST call to /oauth/v2/token. (generates an access_token)
2. Click on the blue Send button at the top right of the workspace. This will initiate the POST call, and it will return an access_token in the body of the workspace.
3. From the collection, click on the Demographic folder, and then click on the Get Subscribers endpoint.
4. Click the blue Send button at the top right of the workspace. This will initiate the GET call, and it will return a response of all subscribers and their stored demographic data.

📘

GET Single Subscriber

If Get Subscribers retrieves too many subscribers, there is another endpoint you can use to retrieve a single subscriber. Utilize the endpoint GET Subscriber ID by inputting the subscriber's ID into the {{id}} variable.
(ex: https://partner-dev-api.plansource.com/admin/v2/subscriber/{{id}})
This will retrieve all demographic data for a single subscriber.

Put Subscriber ID Terminate

This section will show how to call the Put Subscriber ID Terminate endpoint. Make sure to have the subscriber's unique ID before beginning. This can be obtained by making a GET Subscribers call (see section above) and copying the value from "id".

1. Begin by clicking on the folder labeled OAuth Token, and then click on the POST call to /oauth/v2/token. (generates an access_token)
2. Click on the blue Send button at the top right of the workspace. This will initiate the POST call, and it will return an access_token in the body of the workspace.
3. From the collection, click on the Demographic folder, and then click on the Put Subscriber ID Terminate endpoint.
4. In the editable URL text box, enter the subscriber's unique id into the {{id}} variable. Make sure to not enter the ID between the curly brackets, but actually replace the entire variable {{id}} with the unique ID.
5. Click on the tab labeled Body.
6. Enter values for termination_reason and termination_date (both of these fields are required to terminate a subscriber, and values for termination_reason_lookup_code can be found in the response to a Get Subscriber Meta call).
7. Click the blue Send button at the top right of the workspace. This will initiate the PUT call, and it will return a response saying success, and the subscriber should now be terminated.

Put Subscriber ID Rehire

This section will show how to call the Put Subscriber ID Rehire endpoint. Make sure to have the subscriber's unique ID before beginning. This can be obtained by making a GET Subscribers call (see section above) and copying the value from "id".

1. Begin by clicking on the folder labeled OAuth Token, and then click on the POST call to /oauth/v2/token. (generates an access_token)
2. Click on the blue Send button at the top right of the workspace. This will initiate the POST call, and it will return an access_token in the body of the workspace.
3. From the collection, click on the Demographic folder, and then click on the Put Subscriber ID Rehire endpoint.
4. In the editable URL text box, enter the subscriber's unique id into the {{id}} variable. Make sure to not enter the ID between the curly brackets, but actually replace the entire variable {{id}} with the unique ID.
5. Click on the tab labeled Body.
6. Enter values for rehire_date (this field is required to rehire a subscriber).
7. Click the blue Send button at the top right of the workspace. This will initiate the PUT call, and it will return a response saying success, and the subscriber should now be rehired.