Order

Endpoints that support sorting accept an optional orders array in the JSON request body. Each endpoint declares its own set of order keys — the available keys are listed on the endpoint’s API Reference page. Like every tipee API call, the examples below are POST requests with a JSON body (see First steps).

Basic syntax

Every order is an object with a key and a direction. Order keys follow the same <entity>.<field> naming convention as filters:

{
  "orders": [
    {
      "key": "<entity>.<field>",
      "direction": "asc"
    }
  ]
}

Field	Description
`key`	One of the order keys declared by the endpoint
`direction`	`asc` or `desc`

Always include an explicit direction in every order object.

For example, on /api/activity/projects.list:

{
  "orders": [
    {
      "key": "project.name",
      "direction": "asc"
    }
  ]
}

Multiple orders

Orders are applied in the order of the array: the first entry is the primary sort, the second breaks ties, and so on.

{
  "orders": [
    {
      "key": "activity.date",
      "direction": "desc"
    },
    {
      "key": "activity.duration",
      "direction": "asc"
    }
  ]
}

A few endpoints only accept a single order: /api/activity/activities.list-details responds with 422 Multiple orders are not allowed. when several are sent. That restriction is enforced by the endpoint but not visible in its reference schema, which is why it is listed here.

Orders with additional properties

Some order keys require extra properties. For example, resource.attribute on /api/directory/resources.list sorts by any attribute of the directory kind and requires an attribute property:

{
  "orders": [
    {
      "key": "resource.attribute",
      "attribute": "last_name",
      "direction": "asc"
    }
  ]
}

The available attribute names come from /api/directory/kinds.show, which also indicates whether each attribute can be ordered.

Default ordering

When orders is omitted, each endpoint applies its own default ordering. For example, /api/directory/resources.list falls back to the sorting attributes configured on the directory kind.

When paginating, always send explicit orders: the pagination cursor is derived from the sorted values, so a deterministic order guarantees stable pages. See Pagination.

Common errors

Status	Cause
`422`	Unknown order `key`, or several orders sent to an endpoint that accepts a single one

The response body contains a message describing the problem — see Error Handling for the general error format.

Getting Started

Core concepts

Endpoint general guides

Resources

Issues & Bugs

Basic syntax

Multiple orders

Orders with additional properties

Default ordering

Common errors

​Basic syntax

​Multiple orders

​Orders with additional properties

​Default ordering

​Common errors

Basic syntax

Multiple orders

Orders with additional properties

Default ordering

Common errors