Query Parameters

Query parameters for filtering, ordering and/or pagination are supported for several resources in the Solvimon API, The API reference shows for which resources these query actions are supported.

In the articles below each parameter type is explained in detail:

Filtering

Filtering allows an API user to receive a limited subset of the query results based on a filter provided as a query parameter. The filter that is desired is submitted as a query parameter and the matching filter value is submitted as a query value. The filter value can either be a string, a list of strings, or a date range. Please refer to the API reference to see which filters are available for the to-be-filtered resource.

For instance, if you want to search for pricing plan subscriptions, where:

1. the starting date of the pricing plan subscription schedule dates is between 01/01/2023 and 01/04/2023 , and
2. the status of the pricing plan subscription is DRAFT

the following request will achieve this

https://test.api.solvimon.com/v1/pricing-plan-subscriptions?start_at=[2023-01-01T00:00:00Z,2023-04-01T00:00:00Z]&status=DRAFT

Ordering

Some endpoint results can be ordered by adding the order_by query parameter to the request, and adding a query value of the field on which you want the request to be ordered. It is also possible to alter the order direction by adding the query parameter order_direction, setting it to either desc for descending, or asc for ascending. If the order_direction is excluded from the request, it is set to desc. An example of an ordered request is:

https://test.api.solvimon.com/v1/pricing-plan-subscriptions?order_by=start_at&order_direction=desc

where the results are ordered in a descending order based on the start_at date of the pricing plan subscription.

The following resources are available for ordering:

Pagination

For some resources, the Solvimon API supports pagination. When performing a get request for the endpoints /ingest/meter-data , /customers , /invoices, /contacts, /pricing-plans and /pricing-plan-subscriptions, the resulting response will be returned in a paginated manner.

Customer page and limit query parameters can be given with the request. When the page and limit parameters are omitted, they are set to the values 1 and 50 respectively. The limit parameter indicates how many elements ought to be returned in the response. The page parameter indicates which page of results is shown. For instance, when a resource has 80 entries on the Solvimon platform, and a limit is set at 20 and the page number is 1, it will show the first 20 elements of the these list entries. With a identical limit, and page number set to 2, the response will include entries 21 to 40.

The response for paginated resources is always return 5 parameters. First we have the data which shows the returned resource entries. Next, parameter page shows the page number included in the request. The limit parameter shows the limit given in the request. Next, total_number_of_pages shows the overall number of pages that are available.

Finally, there is a links parameter, which includes links for requests to other pages of the requested resource. The possible links included in the response are first, previous, current and next. Links first and previous are only included when the page number is greater than one. The next link is only included when there are more entries of the list to be returned. For instance, when there are 2 total_number_of_pages and the page set in the request is 2, the next link is omitted.

An example of a response for the request https://test.api.solvimon.com/v1/customers?page=2&limit=2 is shown in the code block below:

{
    "data": [
        {
            "object_type": "CUSTOMER",
            "id": "cust_qwDvxI0tDFJ1GTBaeX1z",
            "created_at": "2023-05-08T13:29:33Z",
            "reference": "customer_organization_feestbazaar",
            "status": "ACTIVE",
            "timezone": "UTC",
            "type": "ORGANIZATION",
            "email": "[email protected]",
            "organization": {
                "legal_name": "Feestbazaar",
                "tax_id": "NL0987654",
                "tax_exempt": false,
                "registered_address": {
                    "line1": "Daalsesingel 51",
                    "line2": "Blok A",
                    "city": "Utrecht",
                    "postal_code": "3511 SW",
                    "state": "",
                    "country": "NL"
                }
            }
        },
        {
            "object_type": "CUSTOMER",
            "id": "cust_UwDvxh0tDo8xb4BWeC1c",
            "created_at": "2023-05-05T13:17:58Z",
            "reference": "customer_organization_only-bv",
            "status": "ACTIVE",
            "timezone": "UTC",
            "type": "ORGANIZATION",
            "email": "[email protected]",
            "organization": {
                "legal_name": "Only BV",
                "tax_id": "NL0987654",
                "tax_exempt": false,
                "registered_address": {
                    "line1": "Streetaddress 111",
                    "line2": "Building A",
                    "city": "Utrecht",
                    "postal_code": "3511 SW",
                    "state": "",
                    "country": "NL"
                }
            }
        }
    ],
    "page": 2,
    "limit": 2,
    "total_number_of_pages": 4,
    "links": {
        "first": "https://test.api.solvimon.com/v1/customers?page=1&limit=2",
        "previous": "https://test.api.solvimon.com/v1/customers?page=1&limit=2",
        "current": "https://test.api.solvimon.com/v1/customers?page=2&limit=2",
        "next": "https://test.api.solvimon.com/v1/customers?page=3&limit=2"
    }
}