Filtering

The Public API has a powerful filtering system.

It allows you to filter either Cases, Companies or Persons.

The filtering system is currently only available for use with GraphQL.

In the code example, you can see how a basic use of it looks. Here we are filtering cases for any case named "test".

Each type filter is defined by its type, e.g. CaseFilters:

query getCases($amount: Int, $filters: [CaseFilters]) {
    cases(amount: $amount, filters: $filters) {
        items {
            item {
                id
                name
            }
        }
    }
}

variables: {
    filters: {
        { name: { equals: "test" } }
    }
}

We get the elements that matches the filter:

{
    "data": {
        "cases": {
            "items": [
                {
                    "item": {
                        "name": "test"
                    }
                },
                {
                    "item": {
                        "name": "test"
                    }
                }
            ],
        }
    }
}

The syntax of these filters allows each field to have multiple filters.

The operators are string based and can be seen alongside the filter definitions.

The various filters are described underneath:

CaseFilters

Name	Type	Supported operators
name	String	equals, notEquals
timeCreated	Integer	equals, notEquals, lessThan, greaterThan
timeLastEdited	Integer	equals, notEquals, lessThan, greaterThan
externalId	String	This has a special set of operators, and is explained in the next section. It looks up the related Persons and Companies as the cases do not have any externalIds.

CompanyFilters

Name	Type	Supported operators
name	String	equals, notEquals
timeCreated	Integer	equals, notEquals, lessThan, greaterThan
timeLastEdited	Integer	equals, notEquals, lessThan, greaterThan
externalId	String	This has a special set of operators, and is explained in the next section

PersonFilters

Name	Type	Supported operators
name	String	equals, notEquals
timeCreated	Integer	equals, notEquals, lessThan, greaterThan
timeLastEdited	Integer	equals, notEquals, lessThan, greaterThan
externalId	String	This has a special set of operators, and is explained in the next section

Special case: ExternalId

Again the filter syntax is almost the same, except for the externalId name and having two operators:

query ($amount: Int, $filters: [CaseFilters]) {
    cases(amount: $amount, filters: $filters) {
        items {
            item {
                id
                name
                status
            }
        }
    }
}

variables {
    filters: {
        { externalId: { type: "ExternalId_Generic_CustomerNumber", in: ["1234567890"] } }
    }
}

We get the elements that matches the filter:

{
  "data": {
    "cases": {
      "items": [
        {
          "item": {
            "id": "1",
            "name": "test 3",
            "status": "PENDING"
          }
        }
      ]
    }
  }
}

When filtering on ExternalId_Generic_BusinessRegistrationNumber, the format of the value needs to be passed in the format {countryCode}{registrationNumber}. For example, a Swedish company with the registration number 1234567890, will have the value SE1234567890.

Here is an example of how to filter on a Swedish company with the registration number 1234567890:

query ($amount: Int, $filters: [CompanyFilters]) {
    companies(amount: $amount, filters: $filters) {
        items {
            item {
                id
                name
                ExternalId_GenericBusinessRegistrationNumber {
                    payload
                }
            }
        }
    }
}

variables {
    filters: {
        { externalId: { type: "ExternalId_Generic_BusinessRegistrationNumber", in: ["SE1234567890"] } }
    }
}

{
    "data": {
        "companies": {
            "items": [
                {
                    "item": {
                        "id": "1",
                        "name": "test",
                        "ExternalId_GenericBusinessRegistrationNumber": [
                            {
                                "payload": "{\"countryCode\":\"SE\",\"registrationNumber\":\"1234567890\"}"
                            }
                        ]
                    }
                }
            ]
        }
    }
}

The ExternalId filter allows API users to query cases persons or companies based on an id that is from another external system, like business registries, integrations or internal customer numbers.

It takes two operators that must both be present, the type, which is a string and an in-selection, which is an array of strings or integers.

Only Persons and Companies have ExternalIds. When filtering with this on cases, it looks into the related Persons and Companies of that case, and returns the case if matching relations were found.

Underneath you can see the ExternalIds that are currently supported by the API for filtering:

Name	Description
ExternalId_Vendor_Economic_CustomerNumber	A customer number from Visma e-conomic
ExternalId_DK_CVR_APIId	The unique id in the CVR API for this item
ExternalId_DK_CVR_Number	The CVR number of a company
ExternalId_NO_BusinessRegistrationNumber	The Norwegian registration number of a company
ExternalId_Generic_CustomerNumber	The internal customer number assigned
ExternalId_Generic_BusinessRegistrationNumber	A business registration number for a company