<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;}</style><p><strong>In this guide we will cover:</strong></p><p><strong>- How to find the API Name of a field</strong></p><p><strong>- Worked Example - Including the Reference in Client Imports</strong></p><p><br></p><p><br></p><p>Halo provides a series of example import sheets that can be used to import your data from a spreadsheet. However, you may find the need to import/bulk update extra fields that are not included in the example spreadsheets.</p><p><br></p><p>If this is the case, you will first want to find the name of relevant fields in our API as the API field names are required for the header for the spreadsheet. </p><p><br></p><p><strong><span style="font-size: 14pt;">Finding API Field Names</span></strong></p><p><strong><span style="font-size: 12pt;">View Example response in API documentation</span></strong><span style="font-size: 12pt;"><br></span></p><p><span style="font-size: 11pt;">There are several ways you can go about obtaining the field names for API resources. If you head to Configuration>Integrations>Halo API>API Documentation, you will find a list of resources with respective field names. Make sure to look at the Example Response for single objects, as these return a more complete set of fields:</span></p><p><br></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNjZTllMDU5LTg4YTgtNGU3MC1iZThjLTliNmExNTk4YjM0ZiJ9.4n4Xc-jARCwFtXNeg6_bMFrgr4GpqSzNSwuP0-066UI" class="fr-fic fr-fil fr-dib" style="width: 451px;" width="451" height="307"></span></p><p><span style="font-size: 10pt;"><strong>Fig 1. API documentation for item records in Halo</strong></span><strong><span style="font-size: 10pt;"><br></span></strong></p><p><br></p><p>Field names are not always immediately obvious as to what they are referring to, so you may want to use Swagger to look at the data in your instance, as opposed to example responses.</p><p><br></p><p><strong><span style="font-size: 12pt;">Using Swagger</span></strong></p><p>Head to your Halo URL + '/api/swagger'. The first thing you'll want to do once you're in here is authorize Swagger to get your data.</p><p><br></p><p>Authorizing Swagger will require you to provide an access token:</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImJhMTViMmI5LThjZTUtNGZlYS1iNDBiLTk5M2Q5NmE4NDEyMyJ9.WL4yauXKfIgYAdIll2-R89eROPHacP0C3vXCKXTdBvY" class="fr-fic fr-fil fr-dib" width="373" style="width: 373px; height: 164.642px;" height="164.642"></p><p><strong><span style="font-size: 10pt;">Fig 2. Access token for swagger</span></strong></p><p><br></p><p>I'll cover one such means of obtaining an access token in this article, but feel free to use whichever method you prefer (Postman, PowerShell etc..).</p><p><br></p><p><strong>Obtain access token for Swagger</strong></p><p>When in Halo, open your browsers developer tools (f12 in Chrome, for example). Head to the Network tab & clear your Network Activity:</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVkOWI0Mzg1LWNiY2UtNGQ3NS05ODg2LWNlNzA5NjMxMzk0ZiJ9.2VWL7meHwrbJz-085fxcaFgCoCOuBntppZ1K1CQLFiw" class="fr-fic fr-fil fr-dib" width="152" height="42"></p><p><strong><span style="font-size: 10pt;">Fig 3. Clear network activity</span></strong></p><p><br></p><p>Then refresh the page. You should find when expanding the first record in your network activity you see something similar to:</p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImJmYzVmZTI5LWYyN2ItNGQ1OS04Mzc3LWYwNjdjNTVjMzJiYSJ9.jj90rDr84SZZwluDJv9doccR7Ai__df6d_F8L1lPCWA" class="fr-fic fr-fil fr-dib" width="544" height="700"></p><p><strong><span style="font-size: 10pt;">Fig 4. Network activity</span></strong></p><p><br></p><p>Scroll down to the 'Request Headers' section. You'll see part of the text in here gives you the Access Token:</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjljNzhjYTcwLTlkNjMtNDFjMS04ZmM2LTZlMTlmNTgzNDMyNCJ9.QQ7mMNkq2kANRZDBpSSUsiCq_cdeqivFQP8N65Dq3q4" class="fr-fic fr-fil fr-dib" width="409" style="width: 409px; height: 74.2287px;" height="74.2287"></p><p><strong><span style="font-size: 10pt;">Fig 5. Access token in request header</span></strong></p><p><br></p><p>Copy the value ('CfDJ8...' in the above screenshot) and paste this into Swagger. Upon clicking 'Authorize' you should see that you are Authorized:</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjU5NGUwMDQ2LTRlZDQtNDNiOC1hM2JhLTgxMDQ2Y2YxMmE2YiJ9.kmnkKVEkQ6A8_SDvj71gZsH_M-AdqGlimfjdXfcJQW0" class="fr-fic fr-fil fr-dib" style="width: 339px;" width="339" height="151"></p><p><strong><span style="font-size: 10pt;">Fig 6. Enter access token</span></strong></p><p><br></p><p>Now you should be able to query your desired resource - again, ensure you query a single entity instead of the whole list:</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjA3ZTgwY2ZhLWU5MWItNGNlNS05MjIwLTY3YTA4OWM2NDY5NSJ9.5KvBTKfvc2mx-IanDP8y9X4yH1HzteuqqAlEjfQjH6U" class="fr-fic fr-fil fr-dib" style="width: 771px; height: 427.19px;" width="771" height="427.19"></p><p><strong><span style="font-size: 10pt;">Fig 7. query specified resource </span></strong></p><p><br></p><p>The ID of the entity you are querying will be returned in the URL in Halo:</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjI3NTExY2FlLTlmMWEtNDJmNC1iMjZiLWMwNjNhZDYyOTA5MCJ9.G9ZHhyn8Wp5O5eZ-SWj7qKunEAf6CpV3I8yLTXF1Ass" class="fr-fic fr-fil fr-dib" style="width: 391px; height: 188.729px;" width="391" height="188.729"></p><p><br></p><p>This response shows the data being returned for that item:</p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjI1YzAzYzA5LTg4YjAtNDg3NS04NGRkLTAyMWFlNzNiMzliZCJ9.FY28Av89J5MlfuyV1aY1TyXiaYavAaEb50jnjWsKW1M" class="fr-fic fr-fil fr-dib" style="width: 388px; height: 462.147px;" width="388" height="462.147"></p><p><strong><span style="font-size: 10pt;">Fig 8. Response data for specified item</span></strong></p><p><br></p><p>This way, you can manipulate the details of your desired resource to see what fields change in the API & what they change from/to.</p><p><br></p><p><em><strong>Note: Several fields in Halo's API resources provide an 'ID' field and a corresponding 'Name' field (Notice both the AssetGroup_ID & AssetGroup_name fields in the above screenshot). As a general rule, you should always use the ID field (if the field is not already included in the example spreadsheets).</strong></em></p><p><br></p><p>Obtaining the ID for your field can be achieved via heading to the respective entity in Halo & reading the ID in the URL:</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImQyZWFkM2FhLTg3MjYtNGU5Zi1iMTQ0LWJiMTg1OGM3YWFhMyJ9.DizP_ITUzJXrq1abc4_wkQkVFYpzBgJOcxYylBfi_yE" class="fr-fic fr-fil fr-dib" style="width: 273px;" width="273" height="194"></p><p><strong><span style="font-size: 10pt;">Fig 9. ID of resource is found in URL</span></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Worked Example - Including the Reference in Client Imports</span></strong></p><p><span style="font-size: 11pt;">Let's say I'm importing my client list into Halo and would like to populate the 'Reference' field when performing this import. I have obtained my access code & plugged this into Swagger (as per the above) & now I will look at the 'Area' resource.</span></p><p><br></p><p><span style="font-size: 11pt;">I have added some example text into my 'Reference' field in Halo to allow me to easily find this in Swagger:</span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjMxMGI5MmNkLTU1NmEtNDkyYS05YmI5LTI0ZDc2MTZhZGQ1NiJ9.I52JM3xvDG3t91zE6VI1HQX9zh3Joyg_ftT5EHB_9HE" class="fr-fic fr-fil fr-dib" width="1178" style="width: 1178px; height: 441.097px;" height="441.097"></span></p><p><span style="font-size: 10pt;"><strong>Fig 10. Entering text in field to make it easily identifiable in swagger</strong></span><strong><span style="font-size: 10pt;"><br></span></strong></p><p><br></p><p>So from this, I know that I need to add a column to my Clients & Sites import sheet with column header "Ref".</p>
