Branches

The branches endpoint provides access to the mappings between HGEM's identifier to those provided by our clients.

• /branches

  HGEM will provide access to the 'branches' endpoint where there is a business need to do so.
  Requires OAuth scope branches/standard.read

If you try to access the branches endpoint and your API Key or Access Token does not entitle you to, you will receive a 403 - Forbidden response.

---

Making requests to the /branches endpoint

To make a valid request, you will need to supply ALL of the following parameters on the querystring of the endpoint URL:

Parameter name	Data type	Permitted values
HgemClientId	Integer	Must be a value greater than zero

• The parameter names are NOT case-sensitive.
• Please review the Authentication page for information on how to authenticate your requests.

---

Query parameter limits

Please review the Rate Limiting page for information on request rate limits that HGEM impose.

---

Example requests

Example cUrl:

curl -X GET https://results-api.hgem.com/branches?hgemclientid=123456
  -H "hgem-api-key: YOUR-API-KEY-GOES-HERE" 
  -H "Authorization: Bearer Some_really_long_base64_encoded_text_that_makes_up_your_JWT_access_token" 

Example Raw HTTP/1.1:

Below is an example request made by Postman

GET /branches?hgemclientid=123456 HTTP/1.1
Host: results-api.hgem.com
hgem-api-key: YOUR-API-KEY-GOES-HERE
Authorization: Bearer Some_really_long_base64_encoded_text_that_makes_up_your_JWT_access_token
User-Agent: PostmanRuntime/7.13.0
Accept: */*
Cache-Control: no-cache
Postman-Token: e7fd3f29-dad4-4e82-8af8-dca71a93925e,2a369656-b09b-4212-9799-68f2fa4459af
accept-encoding: gzip, deflate
Connection: keep-alive
cache-control: no-cache

---

Possible API responses

HTTP Response Status	Description
200 - OK	Success - response body will contain your data
400 - Bad Request	You have made a malformed request that cannot be processed (with the same parameters), even if you were to retry
401 - Unauthorized	You have either failed to provide an API Key, an access token, or requested an endpoint you are not entitled to use
403 - Forbidden	You have requested results data you are not entitle to access. Change your query
429 - Too Many Requests	You have breached our API rate limits, try again later
500 - Internal Server Error	The API request has resulted in an error which we have not been able to provide further information for.
503 - Service Unavilable	The API is currently unavailable, try again later

See here for further information on HTTP response codes.

---

Successful Requests

When you make a successful request on the /branches endpoint, the response will be as per the example below:
Please review the Data Dictionary page for information on interpreting the data returned from your requests.

• Content-Type: application/json
• Body content:

  [
    	{
    		"id": "9871",
    		"name": "Example Branch Name #1",
    		"branchCode": "ABC001"
    	},
    	{
    		"id": "9872",
    		"name": "Example Branch Name #2",
    		"branchCode": "ABC002"
    	},
    	{
    		"id": "9873",
    		"name": "Example Branch Name #3",
    		"branchCode": "ABC003"
    	},
  ]
  

---

Bad Requests

When you make API calls that result in a response of 400 - Bad Request, you may also get a ProblemDetails response in the body.

An example response would be:

• Content-Type: application/problem+json
• Body content:

    {
    	"title": "Bad Request",
    	"status": 400,
    	"detail": Unable to process the requested query. See 'errors' for further information.,
    	"instance": "urn:hgem:api:results:error:aaf0b99b-d709-4efb-9138-1f1b231169e1",
    	"errors": [
    		"'hgemClientId' must not be empty."
    	]
    }