List levels of hierarchy

GET api/hierarchy_fields

Lists the levels of hierarchy defined for your organization.

Request syntax

get api/hierarchy_fields

Request parameters

The request accepts the following data in the query string.

Parameter	Type	Description	Required	Default value
`only_management_levels`	Boolean	If `true`, lists only the levels at the store management level. If your organization doesn't manage stores by level of hierarchy, the response is an empty array.	No	N/A
`top_level_of_hierarchy`	String	The `full_name` of a level of hierarchy, for example `United States`. The response includes that level and every level below it. Encode spaces in the value as `%20`. If no level matches, the response is an empty array.	No	N/A

Response syntax

[
    {
        "id": integer,
        "full_name": "string",
        "name": "string",
        "primary_host": "string"
    }
]

Response parameters

If the action is successful, an HTTP 200 response is returned. The following data is returned in JSON format as an array, with one object for each level of hierarchy.

Field	Type	Description
`id`	Integer	The ID of the level of hierarchy.
`full_name`	String	The full path of the level of hierarchy, with each level separated by `>` , for example `United States > NE > NJ`. This is the value used in a store's `level_of_hierarchy` field.
`name`	String	The name of the level of hierarchy.
`primary_host`	String	The hostname of the primary host assigned to the level of hierarchy, for example `pfc0001red0`. `null` if no primary host is assigned.

Errors

This action doesn't return errors of its own. A top_level_of_hierarchy value that doesn't match any level returns an HTTP 200 response with an empty array. For a complete list of common errors, see Common errors.

Examples

Example: List all levels of hierarchy

This example lists all levels of hierarchy for the organization. The response has been shortened.

ruby api.rb <customer_code> get api/hierarchy_fields

Response

[
  {
    "id": 238,
    "full_name": "Argentina",
    "name": "Argentina",
    "primary_host": "pfc2020red0"
  },
  {
    "id": 239,
    "full_name": "Argentina > N",
    "name": "N",
    "primary_host": null
  },
  {
    "id": 240,
    "full_name": "Argentina > N > BA",
    "name": "BA",
    "primary_host": null
  },
  {
    "id": 14,
    "full_name": "Brazil",
    "name": "Brazil",
    "primary_host": "pfc0012red0"
  },
  {
    "id": 15,
    "full_name": "Brazil > NE",
    "name": "NE",
    "primary_host": "pfc0012red0"
  }
]

Example: List levels of hierarchy from a specific level down

This example lists the United States level and every level below it. The space in the value is encoded as %20. The response has been shortened.

ruby api.rb <customer_code> get 'api/hierarchy_fields?top_level_of_hierarchy=United%20States'

Response

[
  {
    "id": 1,
    "full_name": "United States",
    "name": "United States",
    "primary_host": "pfc0001red0"
  },
  {
    "id": 242,
    "full_name": "United States > MW",
    "name": "MW",
    "primary_host": "pfc6349red0"
  },
  {
    "id": 243,
    "full_name": "United States > MW > IL",
    "name": "IL",
    "primary_host": null
  },
  {
    "id": 10,
    "full_name": "United States > NE",
    "name": "NE",
    "primary_host": "pfc2344red0"
  },
  {
    "id": 28,
    "full_name": "United States > NE > NJ",
    "name": "NJ",
    "primary_host": null
  },
  {
    "id": 11,
    "full_name": "United States > NE > NY",
    "name": "NY",
    "primary_host": null
  }
]

Example: List levels of hierarchy from a level that doesn't exist

This example requests a level of hierarchy that doesn't exist. The response is an empty array.

ruby api.rb <customer_code> get 'api/hierarchy_fields?top_level_of_hierarchy=Docs%20Nonexistent'

Response

[]