Common operations

Retrieving Records

Retrieve records by ID or list them using filters, sorting, pagination, fields and expansion.

Retrieve by ID

GET/api/v2/{entity}/{id1},{id2},…,{id10}Retrieve one or several records

Separate IDs with commas. A request can contain at most 10 IDs.

Retrieve a list

GET/api/v2/{entity}Retrieve a filtered, sorted and paginated list

List responses contain data, totalRecords and, when more data is available, nextPage.

Filtering

Pass a URL-encoded JSON object in the filter query parameter. Conditions in one object are combined with AND. Arrays match any listed value.

json

{
  "custom_review_date": "Next Month",
  "custom_reference": "^CX-",
  "custom_region": [
    "EMEA",
    "APAC"
  ]
}

Prefix text with ^ for "starts with". Use dot notation for associated records, such as project.deadline. Custom-field keys in these examples are illustrative.

Sorting

Pass a comma-separated list of property keys in sort. Sorting is ascending by default; append /desc for descending order.

For example, sort=project.name,plannedStart/desc sorts first by project name and then by planned start in descending order.

Pagination

List requests return at most 250 records. Pass page to retrieve a page and continue using the returned nextPage value.

Select properties

Default properties are always returned. Use fields with a JSON array to request additional properties. id and url are always included.

Use dot notation for association properties, such as user.name or project.name.

Expand associations

Use expand to include an association's default properties. Separate several associations with commas.

Use fields when you also need non-default properties from an expanded association.

Complete example

This request combines custom-field filtering, selected properties, sorting, pagination and an expanded project:

bash

curl -G \
  -H 'Authorization: bearer YourTokenHere' \
  --data-urlencode 'filter={
    "custom_review_date": "Next Month",
    "custom_reference": "^CX-",
    "custom_region": [
      "EMEA",
      "APAC"
    ]
  }' \
  --data-urlencode 'fields=[
    "name",
    "plannedStart",
    "project.name",
    "custom_review_date",
    "custom_reference",
    "custom_region"
  ]' \
  --data-urlencode 'sort=plannedStart/desc' \
  --data-urlencode 'expand=project' \
  --data-urlencode 'page=2' \
  'https://app.celoxis.com/psa/api/v2/tasks'

The custom-field keys are illustrative. Use the keys shown in your in-app API Property Reference.