<style>p { margin: 0; }span.fr-emoticon.fr-emoticon-img { background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle; } span.fr-emoticon { font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0; } blockquote { border-left: solid 2px #5e35b1; color: #5e35b1; margin-left:0; padding-left:5px;}blockquote blockquote{ border-color: #00bcd4; color: #00bcd4;}blockquote blockquote blockquote{ border-color: #43a047; color: #43a047;} table.grid{ border-collapse: collapse;} table.grid td, table.grid th { border: 1px solid #ddd;} .fr-fic.fr-dib{ display: block; margin: 5px auto;}.fr-fic.fr-dib.fr-fir{ text-align: right; margin: 5px 0 5px auto;}.fr-fic.fr-dib.fr-fil{ text-align: left; margin: 5px auto 5px 0;}.fr-fic.fr-dii{ float: none; margin: 5px auto;}.fr-fic.fr-dii.fr-fil{ float: left; margin: 5px auto;}.fr-fic.fr-dii.fr-fir{ float: right; margin: 5px auto;}img.fr-dib.fr-fir { margin-right: 0; text-align: right;}img.fr-dib.fr-fil { margin-left: 0; text-align: left;}img.fr-dib { margin: 5px auto; display: block; float: none;}img.fr-bordered { box-sizing: content-box; border: solid 5px #CCC;}img.fr-shadow { box-shadow: 10px 10px 5px 0px #cccccc;}img.fr-rounded { border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;}</style><p><strong>In this guide we will cover:</strong></p><p><strong>- Getting Authentication Credentials</strong></p><p><strong>- Creating a Collection in Postman</strong></p><p><strong>- Making API Requests</strong></p><p><strong>- Bulk Updating Data</strong></p><p><br></p><p><br></p><p><strong>Related Guides:</strong></p><ul><li style="font-weight: bold;"><a href="https://usehalo.com/haloitsm/guides/2187" target="_blank" rel="noopener noreferrer"><strong>A Step-by-Step Guide to Make a Bulk Change in the Halo Database Through the API Using JSON in Postman</strong></a> </li><li style="font-weight: bold;"><a href="https://usehalo.com/haloitsm/guides/2267/" target="_blank" rel="noopener noreferrer">Runbooks - Authorising API Access into Your Own Halo Instance</a></li><li style="font-weight: bold;"><a href="https://usehalo.com/haloitsm/guides/1670/" target="_blank" rel="noopener noreferrer">Setting Up An API Agent</a> </li></ul><p><br></p><p>Postman is a tool which can be used to make direct API calls and view the response returned from such calls. </p><p><br></p><p><strong>Download Postman: <a href="https://www.postman.com/downloads/" id="isPasted">https://www.postman.com/downloads/</a></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Getting Authentication Credentials </span></strong></p><p>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:</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImYzMDJmMzcwLTQyYzItNDgxYy05MjM5LTVmMzA5YzIxNzQxNiJ9.LloDO7E5PqIJ-b8YUHzh3-w6AMflJhRtaX5GoeDU0Ag" class="fr-fic fr-fil fr-dib" style="width: 931px; height: 432.53px;" width="931" height="432.53"></p><p><strong><span style="font-size: 10pt;">Fig 1. Creating an application.</span></strong></p><p><br></p><p>Give your application a sensible name "Postman", an Authentication Method of "Client ID & Secret" and set an "Agent to Log in as". This agent can be an API agent, which can be configured by following this guide on "<a href="https://usehalo.com/haloitsm/guides/1670/" target="_blank" rel="noopener noreferrer"><strong>Setting Up An API Agent</strong></a>".</p><p><br></p><p>On the "Permissions" tab, select the permissions you want to grant (effectively setting the 'Role' and associated permissions for this connection). </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjI3MjUyMTY5LWQ0NGQtNDNiMS05OTQ1LWE1YzIxMTMzMjZlYSJ9.XATP1ec3vce2C-Wcw1KrcSizn6FljkZ6ALFLNeonaTY" class="fr-fic fr-fil fr-dib" style="width: 937px;" width="937" height="211"></p><p><strong><span style="font-size: 10pt;">Fig 2. Setting permissions.</span></strong></p><p><br></p><p>Copy your Client Secret and save.</p><p><br></p><p><strong><span style="font-size: 14pt;">Creating a Collection in Postman</span></strong></p><p><span style="font-size: 11pt;">Head in to Postman, then to 'Workspaces'.</span></p><p><br></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjdiZTU5YTIxLTU3NmYtNDIyOC1hYzU4LTQ4OGE2OWMxYjM0ZiJ9.RpmXTfQphcgUNiWLhsea4baMtV4yYfzLcJJKuaPP-W8" class="fr-fic fr-fil fr-dib" style="width: 1199px;" width="1199" height="333"></span></p><p><span style="font-size: 10pt;"><strong>Fig 3. Postman workspace.</strong></span></p><p><br></p><p>Go to 'My Workspaces' then create a collection.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImJlNTExNTU5LTExODItNDliZi04YTNkLWFlYjBmOTg1NTYwNCJ9.D_kWF-Ixa1s0TCuV4kfqxdr7DmHe9IcUijSG9y7lQY8" class="fr-fic fr-fil fr-dib" style="width: 485px; height: 339.5px;" width="485" height="339.5"></p><p><strong><span style="font-size: 10pt;">Fig 4. Creating a collection.</span></strong></p><p><br></p><p>You can rename this collection by right-clicking on the record (once created) to give it a more meaningful name.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY2MTliNmRmLWI2MmItNDQ2MC05NDAyLTMwN2Q1ZjJmZmE5MyJ9.1FPSFZ-E9omVGRGoToL8cWXrjLC7Vtu0zwlb4CIw-4s" class="fr-fic fr-fil fr-dib" width="229" style="width: 229px; height: 467.985px;" height="467.985"></p><p><strong><span style="font-size: 10pt;">Fig 5. Renaming the collection.</span></strong></p><p><br></p><p>In the 'Authorization' tab, select OAuth 2.0.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijg2ODhlOGQwLTA5NTEtNDE5NS1iNjQyLTI5ODFjMDljOTlhZCJ9.uujgGBU7C87sao3D0S9u92JyYCB-pa7BLrGlqofzE20" class="fr-fic fr-fil fr-dib" style="width: 621px;" width="621" height="348"><strong><span style="font-size: 10pt;">Fig 6. Selecting authentication method.</span></strong></p><p><br></p><p>Fill the contents out as follows:</p><ul><li><strong>Add Auth Data To</strong><em> </em>- 'Request Headers'</li><li><strong>Header Prefix</strong><em> </em>- 'Bearer'</li><li><strong>Token Name</strong><em> </em>- Give this a sensible name.</li><li><strong>Grant Type</strong><em> </em>- 'Client Credentials'</li><li><strong>Access Token URL</strong><em> </em>- The URL of the instance you would like to connect) ../auth/token<ul style="list-style-type: disc;"><li>Ensure this is the same instance where you generated your client ID/Secret.</li><li>This is the same for both On-Prem and hosted.</li></ul></li><li><strong>Client ID</strong><em> </em>- The Client ID generated in Halo previously (<strong>Fig 1</strong>)</li><li><strong>Client Secret </strong>- The Client Secret generated in Halo previously (<strong>Fig 1</strong>)</li><li><strong>Scope </strong>- all</li><li><strong>Client Authentication</strong><em> </em>- 'Send as Basic Auth Header'</li></ul><p>Click 'Get New Access Token', at which point you should see the following screen (provided you have entered details correctly).</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImRkMWQ4OTYzLTYzMzMtNDhmYS1hZjIyLTE0ZjNhZTdkOWJlNCJ9.OSzB8tv2YQfkZQx44R9WU0L6xFdI7qUNzge5LIq61so" class="fr-fic fr-fil fr-dib" style="width: 481px;" width="481" height="308"></p><p><strong><span style="font-size: 10pt;">Fig 7. Authentication complete.</span></strong></p><p><br></p><p>Click 'Proceed', then give your Token a sensible name and click 'Use Token'.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImE3ZDk2OTRhLThhMzYtNGE5YS1hYzJhLTk5NDgxMmM0YjEzMCJ9.SKlPwYAHZfefEdafp8NMUaIKIKC8c2jv4VewAXRVYfo" class="fr-fic fr-fil fr-dib" width="514" style="width: 514px; height: 292.824px;" height="292.824"></p><p><strong><span style="font-size: 10pt;">Fig 8. Use Token button.</span></strong></p><p><br></p><p><span style="font-size: 14pt;"><strong>Making API Requests</strong></span></p><p>Now you've authenticated and got your Access Token, you can start making API requests.</p><p><br></p><p>Under your collection, you will see an option to 'Add a Request'.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxNjI3NTgxLThmNTItNDM3Yy1hOGM1LWQzMzQ5ZmM4Mzc5NyJ9.XcZnDvTXEuDjxr3Ei31QrycfHJirFqdHFj_QNu0Gh9A" class="fr-fic fr-fil fr-dib" width="413" style="width: 413px; height: 166.992px;" height="166.992"></p><p><strong><span style="font-size: 10pt;">Fig 9. Add a Request.</span></strong></p><p><br></p><p>You should then be presented with a screen similar to:</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjJjN2FhNDIzLTdkODAtNGRjYy05MmFlLWM4MmU2YTU4NDRlMiJ9.-DcvTOtDu4Xmf9D8lVEJCpgLzr74P9FXMJH1jdGzW5U" class="fr-fic fr-fil fr-dib" style="width: 840px;" width="840" height="571"></p><p><strong><span style="font-size: 10pt;">Fig 10. New request screen.</span></strong></p><p><br></p><p>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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjRiMWI4MTMzLWU4ZTUtNGMxOC1hNjExLTNhOTI4ZjFkYWJkYiJ9.tLPmmVi-ppu94cCn3mik-b0H6zjCOQMX0077g29BJWw" class="fr-fic fr-fil fr-dib" style="width: 431px;" width="431" height="309"></p><p><strong><span style="font-size: 10pt;">Fig 11. Selecting a token.</span></strong></p><p><br></p><p>Now you should be ready to make your API requests! Simply enter your request method and URL.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNlZjhkZjhjLTk0ZDQtNDIzYi1iNTg5LTE4ZDA3NmYyMjZlOCJ9.OjdYzHveASrPP45q-zWoiDjhQxN-yfm0JFNovS8HiIE" class="fr-fic fr-fil fr-dib" style="width: 1218px; height: 617.453px;" width="1216" height="617"></p><p><strong><span style="font-size: 10pt;">Fig 12. Selecting the method.</span></strong></p><p><br></p><p>You can find details on request URLs for API endpoints via our API Documentation - simply add /apidoc to your URL to access our API documentation.</p><p><br></p><p><strong><span style="font-size: 14pt;">Bulk Updating Data</span></strong></p><p>Postman can also be an effective way of bulk updating data. The procedure consists of the following steps:</p><p><br></p><ul><li>Determining what needs updating - this will be done via writing a report, including the ID of the entity you need to update.</li><li>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.</li><li>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).</li><li>Copying & Pasting into Postman</li></ul><p><strong>Example - Bulk updating the Product Tax rate for all Clients to '20% (Sales)'</strong></p><p><br></p><p>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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjU1YmE0NGQyLTE3NTktNDM5MS04ODZlLWEyNWZhNTc4YTRiNyJ9.3eBbTgsF94K0_UPSf7MgCvN8dDeCJ77e5ZsA4sHM0UI" class="fr-fic fr-fil fr-dib" style="width: 570px;" width="570" height="193"></p><p><strong><span style="font-size: 10pt;">Fig 13. Network tab of the developer console.</span></strong></p><p><br></p><p>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.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjAyZmY4ZDIyLWI0YjgtNDU3ZS1hMzAwLWUyMTgxYjlmZGNjZiJ9.kbe1onQ7RF-9BHKDElluza55vpHg6r9EfB6LCpmOrwk" class="fr-fic fr-fil fr-dib" width="491" style="width: 491px; height: 559.452px;" height="559.452"></p><p><strong><span style="font-size: 10pt;">Fig 14. Finding client in the list.</span></strong></p><p><br></p><p>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:</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijk1NzA2YTRjLTAzN2QtNGJkYi1iYzE0LWQ5NGJlMGNmNzUyZSJ9.X5PNv2ebeE9ib655C4JMKNcFaiUbkhRUdptdCV5iTH4" class="fr-fic fr-fil fr-dib" width="481" style="width: 481px; height: 325.213px;" height="325.213"></p><p><strong><span style="font-size: 10pt;">Fig 15. Looking at the payload.</span></strong></p><p><br></p><p>Generally, your request body will need to look something like:</p><p>"[</p><p> {"<strong><NAME OF API ATTRIBUTE 1></strong>": <INTEGER VALUE>,</p><p> "<strong><NAME OF API ATTRIBUTE 2>": "</strong><STRING VALUE><strong>",</strong></p><p><strong> etc..</strong></p><p> }</p><p> ]"</p><p><br></p><p>So, to produce a similar result to the above screenshot, I would need something similar to:</p><p><br></p><p>"[</p><p> {</p><p> "id": 12,</p><p> "item_tax_code": 1</p><p> }</p><p> ]</p><p>"</p><p><br></p><p><br></p>
