{zoneId}/animals Endpoint

The zones/{zoneId}/animals endpoint provides a listing of animals in the zone and select details for each animal. Only live animals are included in the response for this endpoint. To view all animal details, use the {dairyCowId} Endpoint.

NOTE: This endpoint requires Bulk Data Access.

https://platform-vendor-api.vas.com/locations/com.vas.dairies.id/{location-id}/zones/{zoneId}/animals
PATH PARAMETERS

{location-id}*
integerinteger

Location identifier. For routes with “com.vas.dairies.id”, {location-id} is a VAS-specific dairy id, commonly referred to as {dairyId} when not part of an ICARClosed International Committee for Animal Recording (ICAR) is a global organization focused on the standardization of animal identification, recording, genetic evaluation, and data management. location scheme.

{zoneId}*
integer

VAS-specificClosed A data value that originates from the VAS product line. zone identifier

* Required

QUERY PARAMETERS

page
integer

Sets the page number to display in the results. If no parameter is defined, page 1 displays.

pageSize
integer

Sets the number of items to display on one page of results. If no parameter is defined, the response includes 10 items per page. The maximum pageSize is 1000.

curl -X GET \

https://platform-vendor-api.vas.com/locations/com.vas.dairies.id/{location-id}/zones/{zoneId}/animals \

-H 'Authorization: bearer {authorization token}' \

-H 'X-API-Key: {API key}' 

{
    "view": {
        "pageSize": 10,
        "currentPage": 1,
        "totalPages": 1,
        "totalItems": 1
    },
    "member": [
        {
            "animal": {
                "identifier": {
                    "id": "100151618",
                    "scheme": "com.vas.animals.id"
                },
                "alternativeIdentifiers": [
                    {
                        "id": "2",
                        "scheme": "com.vas.animals.managementNumber"
                    },
                    {
                        "id": "test",
                        "scheme": "com.vas.animals.name"
                    },
                    {
                        "id": "-",
                        "scheme": "com.vas.animals.registrationId"
                    },
                    {
                        "id": "982000417922096",
                        "scheme": "com.vas.animals.electronicId"
                    }
                ]
            },
            "location": {
                "id": "8",
                "scheme": "com.vas.dairies.id"
            },
            "animalDetail": {
                "specie": "Cattle",
                "gender": "Female",
                "birthDate": "2020-12-17T08:00:00+00:00",
                "primaryBreed": {
                    "id": "J",
                    "scheme": "com.vas.breed.code"
                },
                "managementTag": "2",
                "name": "test",
                "productionPurpose": "Milk",
                "status": "Alive",
                "reproductionStatus": "Birthed",
                "lactationStatus": "Fresh",
                "offspring": [
                    {
                        "identifier": {
                            "id": "0",
                            "scheme": "com.vas.animals.managementNumber"
                        },
                        "recentOffspring": 1
                    },
                    {
                        "identifier": {
                            "id": "0",
                            "scheme": "com.vas.animals.managementNumber"
                        },
                        "recentOffspring": 2
                    },
                    {
                        "identifier": {
                            "id": "0",
                            "scheme": "com.vas.animals.managementNumber"
                        },
                        "recentOffspring": 3
                    }
                ],
                "parentage": [
                    {
                        "parentOf": {
                            "id": "100151618",
                            "scheme": "com.vas.animal.id"
                        },
                        "identifier": {
                            "id": "161429",
                            "scheme": "com.vas.sire.id"
                        },
                        "alternativeIdentifiers": [
                            {
                                "id": "840000138102117",
                                "scheme": "com.vas.sire.registrationId"
                            },
                            {
                                "id": "11H10157",
                                "scheme": "com.vas.sire.default"
                            }
                        ],
                        "gender": "Male",
                        "relation": "Genetic",
                        "studCode": "0",
                        "sireBreed": "H"
                    },
                    {
                        "parentOf": {
                            "id": "100151618",
                            "scheme": "com.vas.animal.id"
                        },
                        "alternativeIdentifiers": [
                            {
                                "id": "840003219742944",
                                "scheme": "com.vas.dam.registrationId"
                            },
                            {
                                "id": "1534",
                                "scheme": "com.vas.dam.registrationNumber"
                            }
                        ],
                        "damBreed": "H",
                        "gender": "Female",
                        "relation": "Genetic"
                    }
                ],
                "permanentString": "0",
                "isTwin": false,
                "lactation": "1"
            }
        }
    ]
}
Data Point Data Type Definition

The animal data includes multiple data points to identify the animal.

Data Point

Data Type

Definition

identifier (primary animal identifier)

id

integer

VAS-specific dairy cow identifier. This number is used in all VAS products, including PULSE and DairyComp 305. This identifier is unique to each animal in the VAS suite of products, and is the most stable and reliable source of animal identification data. dairyCowId differs from the animal's cowNumber, displayCowNumber, EIDClosed 15-digit electronic ID number associated with the animal eartag, and isoId.

scheme

string

Identifies the data source as VAS: com.vas.animals.id

alternativeIdentifiers (other animal identifiers)

id

integer

Number assigned to an animal, usually visible on the eartag:

This number is commonly reused and is not unique to the animal on farm or in the VAS suite of products. cowNumber differs from the animal's dairyCowId, EID, and isoId.

scheme

string

Identifies the data source as VAS: com.vas.animals.managementNumber

id

string

Name assigned to an animal. This name is commonly reused and is not unique to the animal on farm or in the VAS suite of products.

scheme

string

Identifies the data source as VAS: com.vas.animals.name

id

string

15-digit ISOClosed International Organization for Standardization, a global organization that promotes commercial and industrial standards. number associated with the animal eartag, often the same as the electronicID. If the electronicID changes, the isoId does not.

The isoId is a unique on-farm animal identifier. VAS recommends against changing an animal's isoId, and it is generally considered to be more stable than the EID.

scheme

string

Identifies the data source as VAS: com.vas.animals.registrationId

id

string

15-digit electronic IDClosed Identifier (EID) number associated with the electronic animal eartag, often the same as the IsoId. The EID of an animal changes whenever the button in the electronic tag is replaced: 

The EID is subject to change and is therefore not an ideal source for unique animal identification data.

scheme

string

Identifies the data source as VAS: com.vas.animals.electronicId

The location data specifies the animal's location information.

Data Point

Data Type

Definition

id

string

Location identifier. For routes with “com.vas.dairies.id”, {location-id} is a VAS-specific dairy id, commonly referred to as {dairyId} when not part of an ICAR location scheme.

scheme

string

Identifies the data source as VAS: com.vas.dairies.id

The animalDetail data specifies the arriving animal's information.

 

Data Point

Data Type

Definition

specie

string

Animal species: Cattle

gender

string

Animal's gender: Male or Female

birthDate

string

Date/time stamp (YYYY-MM-DDThh:mm:ss in 24-hour UTCClosed Coordinated Universal Time, also known as Greenwich Mean Time (GMT) time) of the animal's birth date. This date determines whether an animal is a calf. Calves are animals 90 days old or younger (based on today's date). Learn more about VAS Developer API Date/Time Formatting.

The primaryBreed data specifies information about the animal's breed.

Data Point

Data Type

Definition

identifier (primary breed identifier)

id

string

Breed name abbreviation. Learn more about VAS Developer API Cow Breeds.

scheme

string

Identifies the data source as VAS: com.vas.breed.code

managementTag

string

Animal's cowNumber

name

string

Animal name

productionPurpose

enum

Animal's production purpose: Milk

status

string

The condition of the animal: Alive

NOTE: Dead and OffFarm conditions do not apply for this endpoint.

reproductionStatus

enum

Animal's reproduction status, determined by its ReproductionCode (RCClosed Reproductive code):

  • Open: Animal is not pregnant (RC = 0 or 3)
  • DoNotBreed: Animal should not be bred (RC = 1)
  • Birthed: Animal has recently given birth or calved (RC = 2)
  • Inseminated: Inseminated animal (RC = 4)
  • Pregnant: Pregnant animal (RC = 5 or 6)
  • Null: Male animal (RC = 8)

lactationStatus

enum

Animal's lactation status, determined by its lactationNumber and its ReproductionCode (RC):

  • Lactating: Lactating animal (lactationNumber > 0 and RC = 1, 3, 4, or 5)
  • Fresh: Fresh animal (lactationNumber > 0 and RC = 2)
  • Dry: Dry animal (lactationNumber > 0 and RC = 6)
  • Null: The animal's status is one of the following:
    • Bull Calf: Male animal (RC = 8)
    • Virgin Heifer: Animal has never been bred (RC = 0)

The parentage data specifies information about the animal's male parentage.

Data Point

Data Type

Definition

parentOf

id

integer

VAS-specific dairy cow identifier. This number is used in all VAS products, including PULSE and DairyComp 305. This identifier is unique to each animal in the VAS suite of products, and is the most stable and reliable source of animal identification data. dairyCowId differs from the animal's cowNumber, displayCowNumber, EID, and isoId.

scheme

string

Identifies the data source as VAS: com.vas.animals.id

identifier

id

integer

VAS-specific sire identifier. sireId differs from the animal's EID.

scheme

string

Identifies the data source as VAS: com.vas.sire.id

alternativeIdentifiers

id

integer

Sire registration identifier

scheme

string

Identifies the data source as VAS: com.vas.sire.registration.Id

id

integer

Dairy-specific sire identifier

scheme

string

Identifies the data source as VAS: com.vas.sire.default

gender

string

Parent's gender: Male

relation

enum

Parent's relation to the arrival: Genetic

studCode

integer

Semen company identification. For a listing of standard identifiers for the US, see NAAB Stud Codes.

sireBreed

string

Sire breed name. Learn more about VAS Developer API Cow Breeds.

The parentage data specifies information about the animal's female parentage.

Data Point

Data Type

Definition

parentOf

id

integer

VAS-specific dairy cow identifier. This number is used in all VAS products, including PULSE and DairyComp 305. This identifier is unique to each animal in the VAS suite of products, and is the most stable and reliable source of animal identification data. dairyCowId differs from the animal's cowNumber, displayCowNumber, EID, and isoId.

scheme

string

Identifies the data source as VAS: com.vas.animals.id

identifier

id

integer

VAS-specific dam identifier. damId differs from the animal's EID.

scheme

string

Identifies the data source as VAS: com.vas.dam.id

alternativeIdentifiers

id

integer

Dam registration identifier

scheme

string

Identifies the data source as VAS: com.vas.dam.registration.Id

id

integer

Dairy-specific dam identifier

scheme

string

Identifies the data source as VAS: com.vas.dam.default

damBreed

string

Dam breed name. Learn more about VAS Developer API Cow Breeds.

gender

string

Parent's gender: Female

relation

enum

Parent's relation to the arrival: Genetic

permanentString

integer

User-defined value that identifies the animal as part of a group. All animals in a group have the same permanentString value

isTwin

boolean

Identifies the animal as a twin

lactationNumber

integer

Current lactation number
Status Code/Error Description
200 OK

Standard response for a successful HTTP request.

201 Created

A method successfully created a resource.
202 Accepted

The server accepted the request and will execute it at a later point.

204 No Content

The server successfully executed the method but returns no response body.
400 Bad Request

Bad request. Depending on the endpoint, additional error details may be sent in the response.

Use the strategies below to troubleshoot the error: 

  • Check the request for any typos.
  • Check the syntax of the request and verify the parameters provided fall within the expected range.
  • For POST endpoints, verify that the request adheres to the logic of the VAS Developer API:  
    • Events may only be added to an animal's current lactation.
    • Events cannot be added to animals in a sold/died status.
NOTE: The resource URI is case-sensitive. If you are encountering unexpected 400 errors, check your URI for correct capitalization of resource names.
401 Unauthorized

Authentication failed due to invalid authentication credentials.
403 Forbidden

You are not permitted to access this resource.
404 Not Found

The resource could not be found. It is possible that the resource has been moved or deleted, or that there is a typo in your request.
405 Method Not Allowed

The requested method and resource are not compatible.

429 Too Many Requests

You sent too many requests within a given period and exceeded the rate limit.

500 Internal Server Error

A VAS server error has occurred and the request cannot be fulfilled.
502 Bad Gateway

The server did not receive a timely response from another server.

503 Service Unavailable

The server is not available, usually due to overloading or maintenance issues.

504 Gateway Timeout

The server, while acting as a gateway or proxy, cannot get a response in time.

< Return to Pens Resource