View

View information about one or more categories.

To build the complete category tree, please do not use multiple API requests to recursively build the tree, but get all categories at once (or with mulitple requests if pagination is needed). Then build up the tree yourself in your own code. This is faster than doing multiple API requests.

This action requires a request with one or more active accounts.

Tokens

This action requires the following tokens:

  • category-read

Arguments

Required arguments are marked in bold, and optional arguments are marked in italics.

Argument Type Default Description
category Hash   Only show the category with the given hash
searchname String   Only show categories containing the given string somewhere in the name
parent Hash   Only show the childs of the given category
onlytoplevel Boolean false Only show the categories which are top level (i.e. do not have a parent)
showchildren Boolean false Whether to also show the children of each category
limit Integer 20 The maximum number of results to include in the output
offset Integer 0 The number of results to skip when outputting
orderfield String created

Defines the field to order the results by; can be any of the following:

  • name – Order lexicographically by name
  • created – Order by the date when the item was created
  • modified – Order by the date when the item was last modified
  • parent – Order by the parent
order String asc Sort the results by the field given in orderfield in ascending or descending order, by using ‘asc‘ or ‘desc‘ respectively

Output

This action produces the following extra headers on success, besides the default headers:

Name Type Description
count Integer The total number of results that would be returned when pagination would be disabled

This action produces the following output on success:

An array containing zero or more elements, each one being an object containing the following fields:

Name Type Description
id Hash Category ID
name String The name of this category
description String the description of this category
datecreated DateTime When this category was created
datemodified DateTime When this category was last modified
parent

The parent of this category, if any

The value of this field is an object containing the following fields:

Name Type Description
id Hash Category ID
name String The name of this category
account

The Account associated with this category

The value of this field is an object containing the following fields:

Name Type Description
id Hash Account ID
name String Account name
customer

The Customer associated with this category

The value of this field is an object containing the following fields:

Name Type Description
id Hash Customer ID
name String The name of this customer
datecreated DateTime When this customer was created
datemodified DateTime When this customer was last modified
children

The value of this field is an array containing zero or more elements, each one being an object containing the following fields:

Name Type Description
id Hash Child category ID
name Hash Child category name

Errors

This action can return one of the default status codes, or one of the following status codes on error:

STATUS_CATEGORY_NOT_FOUND (210)
If the category specified in “parent” can not be found
STATUS_ACCESS_DENIED (4)