Filtering & paging — Partner API (PAPI)
Any endpoint that returns a list can be filtered, sorted and split into pages using three optional query parameters. They work the same way on every list endpoint, and you can combine them. Spell the names exactly: they are case-sensitive, and one that does not match is ignored without an error.
A quick example
Say a customer calls in and gives you their organisation number. Rather than pulling your whole customer list and searching it, ask the API to do it:
GET /v1/customers/all/details?filterBy=organisationNumber=2222222222Any customer with that organisation number, instead of every customer you resell to.
filterBy — narrow the list
Write the property you want to match, an operator, and the value. No spaces around the operator.
filterBy=property=valueChoosing a property
Use the property name exactly as it appears in the response. Reach into nested objects with a dot. If the property is a list, the filter matches when any item in it matches.
Operators
| Operator | Meaning |
|---|---|
| = | Equals. The only operator that accepts wildcards. |
| > | Greater than. For numbers. |
| < | Less than. For numbers. |
Writing values
Text is matched without regard to upper or lower case, wildcards included.
| Example | Matches |
|---|---|
| /v1/customers/all/details?filterBy=name=acme ab | That exact name. |
| /v1/customers/all/details?filterBy=name=acme* | Customers whose name starts with "acme". One * per value, at the start or the end — it cannot mean "contains". |
| /v1/customers/{customer}/extensions/users?filterBy=email=*@acme.se | That customer's users with an acme.se email address. |
| /v1/customers/all/details?filterBy=contactAddressDto.city=stockholm | Customers whose contact address is in Stockholm. The dot reaches into the nested contactAddressDto object. |
Combining conditions
| Example | Meaning |
|---|---|
| /v1/customers/all/details?filterBy=state=Active, Suspended | Either state, leaving out the inactivated ones. |
| /v1/customers/all/details?filterBy=name=acme*&filterBy=state=Active | Both at once: the name starts with "acme" and the customer is active. |
The space after the comma matters: leave it out and you get the wrong results rather than an error. Send it as %20 if your HTTP client does not encode it for you.
sortBy — put the list in order
Name the property to sort on. Add > in front to reverse the order.
sortBy=property| Example | Result |
|---|---|
| /v1/customers/all/details?sortBy=name | Customers by name, A to Z. |
| /v1/customers/all/details?sortBy=>name | Customers by name, Z to A. |
| /v1/customers/all/details?sortBy=countryKey&sortBy=name | By country, then by name inside each country. |
Worth knowing
- Send the parameter again for each extra property. A comma-separated list in one sortBy is rejected.
- Results with no value for the property come last.
- Some HTTP clients want the leading > percent-encoded as %3E.
paginateBy — take one page at a time
Give the page size and the page number, separated by a comma. Page numbers start at 0.
paginateBy=pageSize,pageNumber| Example | Returns |
|---|---|
| /v1/customers/all/details?paginateBy=25,0 | Customers 1 to 25. |
| /v1/customers/all/details?paginateBy=25,1 | Customers 26 to 50. |
Worth knowing
- Both numbers are required. paginateBy=25 on its own is rejected, so ask for the first page as paginateBy=25,0.
- A page past the end gives you an empty list, not an error.
- Filtering happens first, then sorting, then paging.
How many pages are there?
These responses carry a header counting the results that matched your filter, before paging. Divide it by your page size to know how many pages to fetch.
post-filter-result-size: 137Putting it together
GET /v1/customers/all/details?filterBy=state=Active&sortBy=name&paginateBy=50,0The first 50 active customers, alphabetically.
If it does not work
| Response | What it means |
|---|---|
| 200, full list | The parameter name is wrong. filterBy, sortBy and paginateBy are case-sensitive, and anything else is ignored without an error — filterby returns everything. |
| 400 | The property name is wrong. The message names the getter it could not find. |
| 200, empty list | Both were understood. Nothing matched the value you asked for. |
Good to know
- Values are not case-sensitive, property names are: fixedNumber works, fixednumber returns 400.
- Dates can be sorted on and matched exactly. Narrowing a date range with > or < is not supported today.
- These parameters are not listed in the reference. They are added on top of the endpoints rather than by each one, but work on every list endpoint.