Add additional query options to GET endpoints

[jdoemel]

Please add additional query options to GET endpoints

• lactation-status and can specify 1 or as many as they like. MILKING, DRY, HEIFER, BULL
• alternative-identifiers and can specify 1 or as many as they like.
• is-archived. True/False. Allows requests for Active vs Inactive animals. No parameter includes Active and Inactive

Given partners are pulling animal data from Developer API GET endpoints,
When partners want to filter animals by current archive status,
Then partners can use an is-archived query parameter.

is-archived=true returns SOLD/DIED animals.
is-archived=false returns only ALIVE animals.
If is-archived is not provided, the endpoint continues to return ALIVE/SOLD/DIED animals.

Given partners are pulling animal data from Developer API GET endpoints,
When partners want to filter animals by current lactation status,
Then partners can use the lactation-status query parameter.

The parameter supports one or multiple values in a single request.

Examples:
&lactation-status=milking
&lactation-status=milking&lactation-status=dry&lactation-status=heifer

When multiple values are provided, results include animals currently matching any supplied lactation status.
milking
dry
heifer
bull

Given partners are pulling animal data from Developer API GET endpoints,
When partners want to filter animals by specific alternative identifiers,
Then partners can use an alternative-identifiers query parameter.

Supported values:

The parameter supports one or multiple values in a single request.

Examples:
&alternative-identifiers=com.vas.animals.managementNumber
&alternative-identifiers=com.vas.animals.managementNumber&alternative-identifiers=com.vas.animals.registrationId

When alternative-identifiers is used, results include animals where the selected identifier field has a non-null, non-empty, non-zero value.
When multiple values are provided, results include animals matching any supplied alternative identifier.

Sharing examples but would be unlimited given what a particular partner offers
com.vas.animals.managementNumber
com.vas.animals.name
com.vas.animals.registrationId
com.vas.animals.electronicId
com.vas.animals.controlNumber
com.vas.animals.visualId
com.vas.animals.transponderNumber
com.vas.animals.responderNumber

[cookeac]

Notes:

• Look at current active / inactive (alive / not alive) semantics - to determine how the is-archived filter could be structured.
• alternative-identifiers is a scheme identifier (maybe make that explicit) and its a filter - only animals with that scheme in their id or alternativeIdentifiers array.

The use cases for filtering include API or proxy costs for data returned, mobile network costs or overhead, etc.

There would be value in making some of the filter/query parameter documentation more complete and discoverable.

[cookeac]

Some thoughts from the NZ/EU time meeting on 2026-07-09:

• We are not convinced that all these parameters need to be standardised - an implementation could still implement these without them needing to be part of the standard.
• The is-archived filter is interesting. Some implementations already filter the list to alive and on the location by default, unless you specify that you want archived /dead/sold animals.

We will leave this one open and add further comments as people think and review their implementations.

[erwinspeybroeck]

I agree - we don't need to standardise all parameters

The GET animals in our implementation only returns the ALIVE animals. The dead or sold could be thousands of animals. We now have an old possibility to request for a file (via FTP) with all alive animals, and the animals removed from the farm until a year ago, including the dams of these animals and grand dams, and all info for all these animals (milk recording - testday, lactation, ..- , reproduction, ...). This is used by herd mabagement systems as a start up. We are still thinking how we can get that into the API platform.