HaloPSA

HaloPSA Guides

Documentation to assist with the setup and configuration of the HaloPSA platform

Guides > Using Postman

Using Postman

In this guide we will cover:

- Getting Authentication Credentials

- Creating a Collection in Postman

- Making API Requests

- Bulk Updating Data



Related Guides:


Postman is a tool which can be used to make direct API calls and view the response returned from such calls. 


Download Postman: https://www.postman.com/downloads/


Getting Authentication Credentials 

The first thing you will need to do to allow for Postman to connect to your API is provide a client ID/Secret (effectively 'log in' to Halo via Postman). To do this, head in Halo to Configuration > Integrations > API > View Applications, then add to your records. You should see something similar to:


Fig 1. Creating an application.


Give your application a sensible name "Postman", an Authentication Method of "Client ID & Secret" and set an "Agent to Log in as". On the "Permissions" tab, select the permissions you want to grant (effectively setting the 'Role' and associated permissions for this connection). 


Fig 2. Setting permissions.


Copy your Client Secret and save.


Creating a Collection in Postman

Head in to Postman, then to 'Workspaces'.


Fig 3. Postman workspace.


Go to 'My Workspaces' then create a collection.


Fig 4. Creating a collection.


You can rename this collection by right-clicking on the record (once created) to give it a more meaningful name.


Fig 5. Renaming the collection.


In the 'Authorization' tab, select OAuth 2.0.


Fig 6. Selecting authentication method.


Fill the contents out as follows:

  • Add Auth Data To - 'Request Headers'
  • Header Prefix - 'Bearer'
  • Token Name - Give this a sensible name.
  • Grant Type - 'Client Credentials'
  • Access Token URL - The URL of the instance you would like to connect) ../auth/token
    • Ensure this is the same instance where you generated your client ID/Secret.
    • This is the same for both on-premise and hosted.
  • Client ID - The Client ID generated in Halo previously (Fig 1)
  • Client Secret - The Client Secret generated in Halo previously (Fig 1)
  • Scope - all
  • Client Authentication - 'Send as Basic Auth Header'

Click 'Get New Access Token', at which point you should see the following screen (provided you have entered details correctly).


Fig 7. Authentication complete.


Click 'Proceed', then give your Token a sensible name and click 'Use Token'.


Fig 8. Use Token button.


Making API Requests

Now you've authenticated and got your Access Token, you can start making API requests.


Under your collection, you will see an option to 'Add a Request'.


Fig 9. Add a Request.


You should then be presented with a screen similar to:


Fig 10. New request screen.


Firstly, head to the Authorisation tab. If you pick your Auth type as 'Oauth 2.0', you will then be able to use the Token you have generated in the previous step.


Fig 11. Selecting a token.


Now you should be ready to make your API requests! Simply enter your request method and URL.


Fig 12. Selecting the method.


You can find details on request URLs for API endpoints via our API Documentation - simply add /apidoc to your URL (i.e.: https://haloAcademy.halopsa.com/apidoc) to access our API documentation.


Bulk Updating Data

Postman can also be an effective way of bulk updating data. The procedure consists of the following steps:


  • Determining what needs updating - this will be done via writing a report, including the ID of the entity you need to update.
  • Determining the syntax for the payload - using the Dev Tools of the browser to get an idea of how the body of the request needs to be formatted.
  • Writing a basic formula in Excel - to get the structure for the desired payload, which can be used as a template and and applied to the report (upon exporting said report to CSV).
  • Copying & Pasting into Postman

Example - Bulk updating the Product Tax rate for all Clients to '20% (Sales)'


Step 1 should be pretty straightforward - write a report to get the ID of all clients. Export this report to CSV. To figure out the formatting for the request body/payload, head into a client record, open the Dev Tools (f12 in Chrome) and then to the 'Network' tab.


Fig 13. Network tab of the developer console.


In the UI, change the property you're looking to bulk update (for this example, I changed the product tax code for a client) and check the network tab for a record with a status of 201.


Fig 14. Finding client in the list.


Click into this row, then head to the 'Payload' tab. This will give you an indication as to the names of the API fields/attributes that need changing:


Fig 15. Looking at the payload.


Generally, your request body will need to look something like:

"[

     {"<NAME OF API ATTRIBUTE 1>": <INTEGER VALUE>,

      "<NAME OF API ATTRIBUTE 2>": "<STRING VALUE>",

       etc..

     }

 ]"


So, to produce a similar result to the above screenshot, I would need something similar to:


"[

    {

        "id": 12,

        "item_tax_code": 1

    }

 ]

"



Popular Guides