🗃️Query Parameters

Control your request's results

Pagination

Plannr has pagination built into the API and it is incredibly easy to use. Unlike some APIs, there is no need to manually define a limit or offset.

For endpoints where pagination is possible (usually index endpoints) - all that is required is an integer query parameter called per_page. This parameter controls the number of results to return per page. For example, proving a per_page parameter of 30 to the 'Get All Accounts' endpoint will return 30 accounts objects per page:

https://api.plannrcrm.com/api/v1/account?per_page=30 Request pagination can also be combined with filters and sorts to further control the results in the returned resource collection: https://api.plannrcrm.com/api/v1/account?sort=first_name&per_page=30

It is important to note that any endpoint with the ability to paginate will have a default value for results per page, as well as a limit to the parameter. These values are displayed on the documentation page for each endpoint that can accept a per_page parameter. The usual default is 15 results per page, with the limit being 500.

An example of the per_page parameter on an endpoint in the API documentation

Links and Meta

Paginated responses from the Plannr API also include two other keys alongside Data: Links and Meta.

An example of the Links and Meta keys in a returned response on the Get All Plans endpoint

The Links block contains URL links to various pages in the response. The 4 keys present in this block can be seen above. The provided links in this section may be useful if it is necessary to have a specific link to a certain page in a response. For example, when building an integration, you may wish to build an interactable button that take an end-user to the next page of results.

The Meta block provides useful metadata about the response, it's results, and the URL links for each page. The key contains information such as how many results are displayed per page in the response, and how many returned objects there are in total. Metadata about the current page, which page was accessed last and the last page. Similiar to Links, this data may be required when building an integration, and can be found alongside the normal return objects in each paginated response.

Sort

Many endpoints in the API include the ability to send a sort query parameter, enabling items in the returned resource collection to be sorted based on the provided parameter. Only one sort query parameter can be provided for a request.

The available valid fields for a sort query parameter vary based on the endpoint. Check the API documentation to see what can be provided for each endpoint.

An example of the valid fields for the sort query parameter on the 'Get All Accounts' endpoint

Many endpoints will have a default sort and providing a different sort parameter will override this. A negative sign (-) can be prefixed to any sort parameter to retrieve results in descending order instead of ascending.

An example of an endpoint with a sort query parameter provided:

https://api.plannrcrm.com/api/v1/account?sort=first_name

This will return all accounts in ascending alphabetical order based on the first_name field of each account.

Filters

Filter query parameters are a powerful tool for customising the response from a request. The returned collection can be filtered to only include certain objects with data that corresponds to the filter. Multiple filters can be used together in a request. Plannr API has many filters available on certain endpoints (indexes) that can be used in conjunction with each other as well as a sort and pagination.

A filter parameter always begins with filter[], with the field to filter by contained in the square brackets e.g. filter[name].

The available fields and their corresponding valid values are documented per endpoint, in a similar manner to the sort query parameter. Unlike a sort, a filter will remove results from the resource entirely.

An example of available filters for the 'Get All Accounts' endpoint

Filter parameters are provided like other query parameters,and as mentioned previously, can be used in conjuction with all other types of parameters:

https://api.plannrcrm.com/api/v1/account?filter[type]=external&sort=first_name&per_page=8

Includes

Many endpoints in the API allow includes to be added to the query to load relationships. Using an include against an endpoint will load related models and their data alongside the base query. In the responses from the API, examples of all the relationships loaded against a particular response are shown. For example, a client with their assigned adviser:

An example of a loaded relationship under the assigned_adviser key in a response from the Get an Account endpoint

However, this does not mean the relationship is always loaded in the response. Most 'show' routes with load every relationship, but on 'index' routes you will have to define the includes. Any available includes are listed in the API documentation:

The allowed query includes on the Get All Accounts endpoint