custom-events Endpoint

The custom-events endpoint provides bulk data related to custom events for all animals in the herd. All animals (live, sold, and dead) are included in the response for this endpoint. To see all custom items for a location, use the custom-event-names endpoint.

NOTE: This endpoint requires Bulk Data Access.

IMPORTANT: This endpoint does not retrieve any calculated or standard events. This endpoint will only retrieve events that were uniquely created by the dairy. If you do not see an event in this endpoint, it is possible that the data already exists in a standard endpoint. See VAS Developer API Resources to review all available VAS endpoints.

https://platform-vendor-api.vas.com/locations/com.vas.dairies.id/{location-id}/custom-events/{event-name}
PATH PARAMETERS
{location-id}* integer	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 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.
{event-name}* integer	Specifies the custom event to display in the results.
* 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.
start-date-time string	Specifies a start date and time (optional) for which to include results. Format the date as YYYY-MM-DD. To include a start time as well, add Thh:mm:ss to the date. A "T" is required to separate the date and time. Examples 2020-02-01 specifies a start date of February 1, 2020 2020-02-01T12:00:00 specifies a start date and time of February 1, 2020 at 12:00. If no parameter is defined, all results for the past year are included. To specify a date range, include both a start-date-time and an end-date-time. See the sample request below.
end-date-time string	Specifies an end date and time (optional) for which to include results. Format the date as YYYY-MM-DD. To include an end time as well, add Thh:mm:ss to the date. A "T" is required to separate the date and time. Examples 2020-02-01 specifies an end date of February 1, 2020 2020-02-01T12:00:00 specifies an end date and time of February 1, 2020 at 12:00. If no parameter is defined, all results for the past year are included. To specify a date range, include both a start-date-time and an end-date-time. See the sample request below.

Sample Response (JSON)

{
    "view": {
        "pageSize": 10,
        "currentPage": 1,
        "totalPages": 1,
        "totalItems": 2
    },
    "member": [
        {
            "meta": {
                "modified": "2020-12-03T18:28:59+00:00",
                "created": "2020-12-03T18:28:59+00:00"
            },
            "animal": {
                "identifier": {
                    "id": "100121457",
                    "scheme": "com.vas.animals.id"
                },
                "alternativeIdentifiers": [
                    {
                        "id": "3524",
                        "scheme": "com.vas.animals.managementNumber"
                    },
                    {
                        "id": "",
                        "scheme": "com.vas.animals.name"
                    },
                    {
                        "id": "840003138806658",
                        "scheme": "com.vas.animals.registrationId"
                    },
                    {
                        "id": "840003138806658",
                        "scheme": "com.vas.animals.electronicId"
                    }
                ]
            },
            "location": {
                "id": "21",
                "scheme": "com.vas.dairies.id"
            },
            "pen": {
                "identifier": {
                    "id": "55165",
                    "scheme": "com.vas.pens.id"
                },
                "alternativeIdentifiers": [
                    {
                        "id": "7",
                        "scheme": "com.vas.pens.number"
                    }
                ]
            },
            "eventDateTime": "2020-11-10T08:00:00+00:00",
            "eventName": "SICK",
            "eventDetails": {
                "milkWithholdDate": "2020-07-11T07:00:00+00:00",
                "beefWithholdDate": "2020-11-15T08:00:00+00:00",
                "protocolNumber": "44",
                "protocolName": "MEPill"
            },
            "remark": "MEP",
            "daysInMilk": "84",
            "ageInDays": "",
            "lactation": "3"
        },
        {
            "meta": {
                "modified": "2020-12-03T18:32:37+00:00",
                "created": "2020-12-03T18:32:37+00:00"
            },
            "animal": {
                "identifier": {
                    "id": "100124255",
                    "scheme": "com.vas.animals.id"
                },
                "alternativeIdentifiers": [
                    {
                        "id": "5092",
                        "scheme": "com.vas.animals.managementNumber"
                    },
                    {
                        "id": "",
                        "scheme": "com.vas.animals.name"
                    },
                    {
                        "id": "982123456140820",
                        "scheme": "com.vas.animals.registrationId"
                    },
                    {
                        "id": "982123456140820",
                        "scheme": "com.vas.animals.electronicId"
                    }
                ]
            },
            "location": {
                "id": "21",
                "scheme": "com.vas.dairies.id"
            },
            "pen": {
                "identifier": {
                    "id": "55160",
                    "scheme": "com.vas.pens.id"
                },
                "alternativeIdentifiers": [
                    {
                        "id": "2",
                        "scheme": "com.vas.pens.number"
                    }
                ]
            },
            "eventDateTime": "2020-11-08T08:00:00+00:00",
            "eventName": "SICK",
            "eventDetails": {
                "milkWithholdDate": "2020-09-19T07:00:00+00:00",
                "beefWithholdDate": "2020-09-06T07:00:00+00:00",
                "protocolNumber": "34",
                "protocolName": "Vitamin B"
            },
            "remark": "VITB",
            "daysInMilk": "19",
            "ageInDays": "",
            "lactation": "8"
        }
    ]
}

Response Schema

Data Point

Data Type

Definition

meta data

The meta data specifies historical information for the animal record.

Data Point	Data Type	Definition
modified	string	Date/time stamp (YYYY-MM-DDThh:mm:ss in 24-hour UTC Coordinated Universal Time, also known as Greenwich Mean Time (GMT) time) of the last animal update. Learn more about VAS Developer API Date/Time Formatting.
created	string	Date/time stamp (YYYY-MM-DDThh:mm:ss in 24-hour UTC time) of when the animal record was created. Learn more about VAS Developer API Date/Time Formatting.

animal data

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, EID 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 ISO 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 ID 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

location data

The location data specifies the animal's dairyId information.

Data Point	Data Type	Definition
id	string	VAS-specific A data value that originates from the VAS product line. dairy identifier
scheme	string	Identifies the data source as VAS: com.vas.dairies.id

pen data

The pen data specifies the animal's pen information.

Data Point	Data Type	Definition
identifier (primary pen identifier)
id	integer	VAS-specific pen identifier
scheme	string	Identifies the data source as VAS: com.vas.pen.id
alternativeIdentifiers (other pen identifiers)
id	integer	Pen number at the time of the event
scheme	string	Identifies the data source as VAS: com.vas.pen.number

eventDateTime

string

Date/time stamp (YYYY-MM-DDThh:mm:ss in 24-hour UTC time) of when the event occurred. Learn more about VAS Developer API Date/Time Formatting.

eventName

string

Custom event name (configurable by dairy in PULSE and/or DairyComp 305)

eventDetails data

The eventDetails data includes additional information about the event.

Data Point	Data Type	Definition
milkWithholdDate	string	Date/time stamp (YYYY-MM-DDThh:mm:ss in 24-hour UTC time) of the animal's last milk withhold. Learn more about VAS Developer API Date/Time Formatting.
beefWithholdDate	string	Date/time stamp (YYYY-MM-DDThh:mm:ss in 24-hour UTC time) of the animal's last beef withhold. Learn more about VAS Developer API Date/Time Formatting.
protocolNumber	integer	Protocol number (configurable by dairy in PULSE and/or DairyComp 305)
protocolName	string	Protocol name

remark

string

Additional information on the event, which may be automatically generated by PULSE and/or DairyComp 305, or manually entered

daysInMilk

integer

Number of days into current lactation. For dry cows, total days in most recent lactation prior to being dried off.

ageInDays

integer

Number of days since the animal birth date

lactation

integer

Current lactation number

HTTP Status Codes & Errors

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.