Lifecycle stage	Live
Open API file	View Open API file
Supported Authorisation types	user-restricted

Overview

We developed the Common Livestock Application (CLA) API to allow livestock holders to submit, view, modify and confirm livestock movements electronically.

The connection is secure and access to endpoints is restricted to registered users.

For more details about the livestock information systems api authentication and security, read the authorisation section.

For more information about how to develop your own client applications, including example clients for this API, read our tutorials.

Versioning

When an API changes, we will make backwards compatible changes where we can. When this is not possible, we will add a note about deprecated endpoints and make a new endpoint available.

The current live version of the Common Livestock Application API is 1.0.

API browser and Open API file

For more details about the Common Livestock Application API, open an API browser like Swagger Editor and copy the Open API file content into it.

You can also generate a client library from the Open API file using Swagger Editor.

HTTP status codes

The Common Livestock Application API uses standard HTTP response code conventions:

1xx codes give information
2xx codes mean success
3xx codes mean a redirection
4xx codes mean a client-side error
5xx codes mean a server-side error

Common status codes are:

200 - OK. The request has been successfuly proceessed to completion
201 - Created. The request was successfully received by the system and has been queued for later processing
400 - Bad Request. The incoming request body or parameters do not conform with the Open API document that describes the API
403 - Forbidden. The request is formed correctly, but the REST API refuses to honour it. This is usually because the user does not have the necessary permissions for the resource
404 - Not Found. The request is formed correctly, but the requested resource could not be found
429 - Too Many Requests. - You have made too many requests within a short time (see Request rate limit for further information)
503 - Service Unavailable. The service is currently unable to handle the request due to a temporary overloading or maintenance activity
504 - Gateway Timeout. - There is a network connection problem within the layers of the API fulfilment stack

We use HTTP status codes to signal overall success or failure of a request. Further detail describing the precise nature of the error is returned in the response body.

Request rate limit

To protect the system against being overloaded with requests, we may limit the number of API requests you can make within a time period.

If you exceed this limit, you may receive an HTTP 429 (Too Many Requests) status code for each request you make within the remainder of the time.

Dealing with large results sets

Some endpoints may return a large number of results depending on the filter criteria provided in the $filterparameter. All collection-based endpoints (e.g. requests to return a list of movements) enforce a maximum count of results returned at once. This maximum is called a results page.

When a request generates more results that can be accommodated on a page, the response includes extra information to allow the caller to identify that paging occurred and provides the URL that can be used to obtain the next page of results. This information is included in the @odata.nextLink property alongside the value property.

{
   "@odata.context": "https://<host>/v1/$metadata#ReviewHoldingMovementRequests",
   "value": [… 50 movement entities],
   "@odata.nextLink": "https://<host>/v1/ReviewHoldingMovementRequest?$skip=50"
}

Absence of the @odata.nextLink indicates that the results set is complete and there are no further pages that can be requested.

It is also possible for a calling application to request a smaller than the maximum number of results to be returned.

Clients request a smaller page size by including the $top query parameter. Requests for further data are enabled by the caller populating the $skip query parameter. The caller would normally set the $skip parameter to a multiple of the $top parameter, but there is no restriction on the value.

For example, manually requesting the third page of animal movements that require review with a client-defined page size of 2 would be done using the GET /v1/ReviewHoldingMovementRequests?$top=2&$skip=4 endpoint.

The $top value indicates that a maximum of two movements should be returned, the $skip value indicates that the first four movements should be skipped.

There is no requirement that $skip is a multiple of $top; a $top of ten and a $skip of five would be permitted and would return results six to fifteen inclusive, assuming there were at least fifteen results available.

When a client requests a page size, the response does not include a nextLink; it is the responsibility of the client to manage any further requests for data using $top and $skip.

URL encoding of data

Special handling is required for parameter strings containing punctuation characters, such as CPH numbers or date/times in functions such /v1/HoldingMovementForReviews

These endpoints must have such parameter values URL encoded to ensure that punctuation characters are not mistaken for other parts of the URL.

Below are examples of how to encode submitted data for these commonly used parameter strings:

Sample	Description
Holding	URL encoding of CPH replaces the forward slashes as follows: holding='26/001/8033' becomes holding='26%2f001%2f8033'
Dates and times	URL encoding of CPH replaces '+' and ':' with the character sequences '%2b' and '%3b' respectively

Tracking IDs

The CLA application provides two methods of tracking a request through the system, one at the protocol level and another at the application level.

At the protocol level, the system supports the use of the HTTP header X-Correlation-ID to allow a caller to identify each unique request.

The X-Correlation-ID, sometimes also referred to as the Transit-ID specifies a globally unique attribute attached to the HTTP request that distinguishes it from every other HTTP request used in the system. The value assigned to the header is often a UUID or GUID generated by the client system, but can be any value that makes the request globally unique. Its purpose it to allow the system to identify duplicate HTTP requests that may occur due to network routing issues or application issues that can occur in large scale, high volume transactional systems. Adding an X-Correlation-ID header is optional; if a calling application does not specify one, it will allocated automatically to each HTTP request received at its point of entry into the system.

Note, the HTTP response also includes an X-Correlation-ID. This allows the caller to capture the unique identifier for the requests within the system, even if the caller does not generate one themselves. Where a user supplies and X-Correlation-ID,the value supplied by the user is echoed in the corresponding header in the response.

At the application level, the payload body of each application request includes a non-mandatory trackingId field.

This is a client generated field up to 36 characters in length which performs a function similar to X-Correlation-ID, but is preserved as part of the submitted data throughout its lifetime within the system. Populating this field allows the caller to provide precise information regarding the transaction should any queries be identified after submission.

Unlike X-Correlation-ID, the system will not generate a value for trackingId if it is unpopulated by the calling application.

Endpoints

/v1/TransferRequests

GET

Description

GET TransferRequests returns all requests made by the registered user to register the movement of animals.

the optional $select, and $filter parameters can be used to restrict the scope of the results set returned.

Authorisation

This endpoint is secured by LIS user authorization security.

You will also need to provide a Subscription Key in the requests header. Read the API Authentication page for details

Request headers

Name	Description
Ocp-Apim-Subscription-Key	LIS API subscription key
x-correlation-id	a unique identifer for this request (we recommend generating a GUID for this).

Parameters

Name	Type	Required	Description
$select	string	false	query string to limit the entities to be included in the response
$expand	string	false	indicates the related entities to be represented inline. The maximum depth is 2.
$filter	string	false	query string used to limit the number of items returned in the results set. When specifying dates, only those with a time part will be accepted.
$orderby	string	false	specifies the order in which items in the results set are returned
$top	int32	false	limits the number of results returned
$skip	int32	false	excluded the specified number of items from the results set

Response

HTTP status: 200 (Success)

This response indicates that system has processed the requests and the results are presented in the response body

HTTP status: 400 (Bad Request)

This response indicates that the submission has been rejected by the system as some, or all of the data supplied was found to be in error.

The CLAErrorResponse structure in the returned message provides a list of error codes, together with a textual description of each error. Additional information is provided in the errors body and identifies the field or fields in the original submission that generated each error.

Following an error response, the system discards the submitted data. The caller must correct the errors identified and resubmit the movement again.

If the caller supplied a value in the trackingId field of the submitted movement, this can be reused in a future submission as the system maintains no record of it.

/v1/TransferRequests

POST

Description

TransferRequests registers the movement of animals between two holdings: the source holding and the destination holding.

Animals reported in a movement report can be identified individually or by batch.

Transfers can be one of two types depending on the role of the user who is submitting the request:

If the submitting user is associated with the source holding, the system treats the movement as an 'OFF' Movement.
If the submitting user is associated with the destination holding, the system treats the movement as an 'ON' Movement.

The userHolding must contain the same value as the sourceHolding when reporting an 'OFF' movement, and the same value as the destinationHolding when reporting an 'ON' movement. The movementDocument must be completed and have all mandatory fields populated for the movement to be accepted as valid.

When reporting an 'ON' movement, both departureDateTime and arrivalDateTime must be specified.

When reporting an 'ON' movement to a market, movementDocument.destinationDetail.destinationHoldingType must be populated with the type of market that the livestock are being transported to. Permitted values are: 'SLAUGHTER MARKET', 'STORE MARKET'.

For market users reporting an off movement from a market holding:

saleDate and saleId must be specified.
movementGroups should be used to group the animals by lot/pen and vendor holding. Each movement group should have these details specified in fromSubLocation and vendorHolding respectively.
for Market OFF movements, movementDocument.departureDetail.departureHoldingType must be populated with the type of market that the livestock are being transported from. Permitted values are: 'SLAUGHTER MARKET', 'STORE MARKET'.

Authorisation

This endpoint is secured by LIS user authorization security.

You will also need to provide a Subscription Key in the requests header. Read the API Authentication page for details

Request headers

Name	Description
Ocp-Apim-Subscription-Key	LIS API subscription key
x-correlation-id	a unique identifer for this request (we recommend generating a GUID for this).

Parameters

None

Response

HTTP status: 201 (Created)

This response indicates that the data content has passed an initial syntax check and has been successfully queued by the system for further processing.

The requestId field in the response contains a unique identifier generated by the system that the caller can use to track the progress of the movement request as it is processed by the system. The requestStatus field shows the request's current processing status.

Possible values are:

Pending - the requests is still queued and the caller should query again after a short delay
Processing - the system is currently processing the request and the caller should query again after a short delay
Success - the system has accepted the request and the system view of the animals on the users holding has been adjusted to account for the details in the movement.
Fail - the request has failed. The failure reasons are detailed in the errors section of the response.
QueueFail - the system could not proceed with validation. The caller should resubmit the request again using POST /v1/TransferRequests
CompletedError - the request contained invalid or inconsistent data. The errors are detailed in the errors section of the response. Any animals referenced by the errors will not have had any action recorded for them but any other animals in the same request, but without an error, will have been recorded.
Rejected - the request contained invalid or inconsistent data. The errors are detailed in the errors section of the response.
Cancelled - a user action such as 'undoing' the request caused the processing to be cancelled during validation.
CompletedWarning - the request was accepted, but some of the content generated warnings. The warning are detailed in the warnings section of the response. The system view of the animals on the users holding has been adjusted to account for the details in the movement.
NotAvailable - this error should be reported to the LI Service Desk, together with the requestId that resulted in the error

If the result is 'Success' or 'CompletedWarning', the submission is complete and there are no further processing steps required by the client. The errors and warnings elements of the response body may be populated with content highlighting issues with the data, but these are for information only. No corrective action is required that requires re-submission of the data.

If the requestStatus returns a value of 'Pending' or 'Processing', this indicates that the movement request has been queued by the system for further validation and processing. The caller must then call GET /v1/TransferRequests({requestId}) repeatedly to track the progress of the request through the validation process. The requestId parameter is the unique identifier returned in response to a successful POST /v1/TransferRequests.

Processing is complete once a call to GET /v1/TransferRequests({requestId}) returns a requestStatus of 'Success', 'Fail', 'QueueFail', 'CompletedError', 'Rejected', 'Cancelled' or 'CompletedWarning'.

To prevent overloading the system, the caller should call GET /v1/TransferRequests at a frequency no higher that once per second.

HTTP status: 400 (Bad Request)

This response indicates that the submission has been rejected by the system as some, or all of the data supplied was found to be in error.

The CLAErrorResponse structure in the returned message provides a list of error codes, together with a textual description of each error. Additional information is provided in the errors body and identifies the field or fields in the original submission that generated each error.

Following an error response, the system discards the submitted data. The caller must correct the errors identified and resubmit the movement again.

If the caller supplied a value in the trackingId field of the submitted movement, this can be reused in a future submission as the system maintains no record of it.

/v1/TransferRequests({requestId})

GET

Name	Type	Required	Description
requestId	integer	true	the unique identifier of the request being queried
$select	string	false	query string to limit the entities to be included in the response
$expand	string	false	Indicates the related entities to be represented inline. The maximum depth is 2.

/v1/CorrectTransferRequests

GET

Description

GET CorrectTransferRequests returns all requests to correct an exisiting movement made by the registered user

the optional $select, and $filter parameters can be used to restrict the scope of the results set returned.

Authorisation

This endpoint is secured by LIS user authorization security.

You will also need to provide a Subscription Key in the requests header. Read the API Authentication page for details

Request headers

Name	Description
Ocp-Apim-Subscription-Key	LIS API subscription key
x-correlation-id	a unique identifer for this request (we recommend generating a GUID for this).

Parameters

Name	Type	Required	Description
$select	string	false	query string to limit the entities to be included in the response
$expand	string	false	indicates the related entities to be represented inline. The maximum depth is 2.
$filter	string	false	query string used to limit the number of items returned in the results set. When specifying dates, only those with a time part will be accepted.
$orderby	string	false	specifies the order in which items in the results set are returned
$top	int32	false	limits the number of results returned
$skip	int32	false	excluded the specified number of items from the results set

Response

HTTP status: 200 (Success)

This response indicates that system has processed the requests and the results are presented in the response body

HTTP status: 400 (Bad Request)

This response indicates that the submission has been rejected by the system as some, or all of the data supplied was found to be in error.

The CLAErrorResponse structure in the returned message provides a list of error codes, together with a textual description of each error. Additional information is provided in the errors body and identifies the field or fields in the original submission that generated each error.

Following an error response, the system discards the submitted data. The caller must correct the errors identified and resubmit the movement again.

If the caller supplied a value in the trackingId field of the submitted movement, this can be reused in a future submission as the system maintains no record of it.

/v1/CorrectTransferRequests

POST

Description

The system provides a facility to amend movement data submitted using TransferRequests after it has been accepted by the system. Note that this facility can only correct requests that have been successfully validated and returned a status of 'Success', 'CompletedError' or 'CompletedWarning'; any movements that have been rejected by the system are not stored, therefore must be resubmitted with the identified errors corrected.

To correct a movement record, the following conditions must be true:

The authenticated user must have originally created the transfer request being corrected.
The original and corrected movement must be for the same species, sourceHolding and destinationHolding.
The system may not allow a transfer request to be corrected if other events have subsequently happened to animals involved in the original transfer request.
The content of the correcting request must contain all the details of the movement that the original movement should be replaced with (i.e. not just the changes)

To make a correction, the caller uses the POST /v1/CorrectTransferRequests endpoint, specifying the requestId returned in the success response of the original TransferRequests submission. The remainder of the message body is populated with the details of the amended movement in a similar structure to that of the original call to TransferRequests.

Just as for the original TransferRequests, following submission of the movement using POST /v1/CorrectTransferRequests, the system will validate the data content and return an immediate response. indicating whether the content has been accepted for validation. Two response codes are possible:

HTTP status: 201 (Created)

This response indicates that the data content has passed an initial syntax check and has been successfully queued by the system for further processing.

The requestId field in the response contains a unique identifier generated by the system that the caller can use to track the progress of the movement request as it is validated by the system. The requestStatus field in the response body shows its current validation status.

Possible values are:

Pending - the request has been queued and the caller should query again after a short delay
Processing - the system is currently processing the request and the caller should query again after a short delay
Success - the system has accepted the request and the system view of the animals on the users holding has been adjusted to account for the details in the corrected movement.
Fail - the request has failed. The failure reasons are detailed in the errors section of the response.
QueueFail - the system could not proceed with validation. The caller should resubmit the request using POST /v1/CorrectTransferRequests
CompletedError - the request contained invalid or inconsistent data. The errors are detailed in the errors section of the response.
Rejected - the request contained invalid or inconsistent data. The errors are detailed in the errors section of the response.
Cancelled - a user action such as 'undoing' the request caused the processing to be cancelled during validation.
CompletedWarning - the request was accepted, but some of the content generated warnings. The warning are detailed in the warnings section of the response. The system view of the animals on the users holding has been adjusted to account for the details in the movement.
NotAvailable - this error should be reported to the LI Service Desk, together with the requestId that resulted in the error

If the result is 'Success' or 'CompletedWarning', the submission is complete and there are no further processing steps required by the client. The errors and warnings elements of the response body may be populated with content highlighting issues with the data, but these are for information only. No corrective action is required that requires re-submission of the data.

If the requestStatus returns a value of 'Pending' or 'Processing', this indicates that the movement request has been queued by the system for further validation and processing. The caller must then call GET /v1/CorrectTransferRequests({requestId}) repeatedly to track the progress of the request through the validation process. The requestId parameter is the unique identifier returned in response to a successful POST /v1/CorrectTransferRequests.

HTTP status: 400 (Bad Request)

This response indicates that the correction has been rejected by the system as some, or all of the data supplied was found to be in error.

The CLAErrorResponse structure in the returned message provides a list of error codes, together with a textual description of each error. Additional information is provided in the errors body and identifies the field or fields in the submitted data that generated each error.

Following an error response, the system discards the submitted data. The caller must correct the errors identified and resubmit the movement again. NOTE: The movement data submitted during the original TransferRequest remains present in the system.

If the caller supplied a value in the trackingId field of the submitted movement, this can be reused in a future submission as the system maintains no record of it.

/v1/CorrectTransferRequests({requestId})

GET

Name	Type	Required	Description
requestId	integer	true	the unique identifier of the CorrectTransferRequests request being queried
$select	string	false	query string to limite the search
$expand	string	false	Indicates the related entities to be represented inline. The maximum depth is 2.

/v1/HoldingMovementForReviews(species='{species}',holding='{holding}')

GET

Description

This endpoint is used to begin the process of confirming receipt of a livestock movement. It returns a list of the unconfirmed livestock movements that the system has recorded for holding(s) associated with the user making the call.

Authorisation

This endpoint is secured by LIS user authorization security.

You will also need to provide a Subscription key in a header. This key can be retrieved by Subscribing to the API.

Request headers

Name	Description
Ocp-Apim-Subscription-Key	LIS API subscription key
x-correlation-id	a unique identifer for this request (we recommend generating a GUID for this).

Parameters

Name	Type	Required	Description
species	string	true	the species for which movement records are required.
holding	string	false	a valid CPH or MHS number that the user is associated with. If this parameter is not supplied, the system will return unconfirmed movements for all holdings that the user is associated with.
$select	string	false	query string to limite the search
$expand	string	false	Indicates the related entities to be represented inline. The maximum depth is 2.

Response

HTTP status: 200 (Success)

This response indicates that the system has identified unconfirmed movements associated with the supplied users holding(s). The return body contains the list, with each list entry containing a requestId that the user will need when confirming the movement. The list could be empty if there are not any reviews waiting.

Once a list of unconfirmed movements has been obtained, the calling application calls POST /v1/ReviewHoldingMovementRequests supplying the requestId of the movement being confirmed and the tag or batch numbers of the animals that are being accepted or rejected. It is permitted to accept some tags or batches and reject others in the same transaction.

HTTP status: 400 (Bad request)

This response indicates that the supplied parameters could not be understood by the system. Correct the parameters and resubmit the request.

HTTP status: 404 (No found)

This will be returned if the parameters are malformed

Duplicate movements

Where both the departure keeper and the destination keeper have reported movements between the same two holdings on the same day, the system can identify this. This can occur when a destination keeper has recorded the 'ON' movement to their holding before the departure keeper has submitted the 'OFF' movement from their holding.

The system flags this in the response to HoldingMovementForReviews by setting the isDuplicate flag for the affected movements and providing the duplicateRequestIds of the requests that the systems considers are duplicates.

The destination keeper accepts or rejects the movement using POST /v1/ReviewHoldingMovementRequests, using the departureRequestId from the departure keepers movement as the key to identify the target.

/v1/ReviewHoldingMovementRequests

GET

Description

GET ReviewHoldingMovementRequests returns all requests to review the movement of animals made by the registered user.

the optional $select, and $filter parameters can be used to restrict the scope of the results set returned.

Authorisation

This endpoint is secured by LIS user authorization security.

You will also need to provide a Subscription Key in the requests header. Read the API Authentication page for details

Request headers

Name	Description
Ocp-Apim-Subscription-Key	LIS API subscription key
x-correlation-id	a unique identifer for this request (we recommend generating a GUID for this).

Parameters

Name	Type	Required	Description
$select	string	false	query string to limit the entities to be included in the response
$expand	string	false	indicates the related entities to be represented inline. The maximum depth is 2.
$filter	string	false	query string used to limit the number of items returned in the results set. When specifying dates, only those with a time part will be accepted.
$orderby	string	false	specifies the order in which items in the results set are returned
$top	int32	false	limits the number of results returned
$skip	int32	false	excluded the specified number of items from the results set

Response

HTTP status: 200 (Success)

This response indicates that system has processed the requests and the results are presented in the response body

HTTP status: 400 (Bad Request)

This response indicates that the submission has been rejected by the system as some, or all of the data supplied was found to be in error.

The CLAErrorResponse structure in the returned message provides a list of error codes, together with a textual description of each error. Additional information is provided in the errors body and identifies the field or fields in the original submission that generated each error.

Following an error response, the system discards the submitted data. The caller must correct the errors identified and resubmit the movement again.

If the caller supplied a value in the trackingId field of the submitted movement, this can be reused in a future submission as the system maintains no record of it.

/v1/ReviewHoldingMovementRequests

POST

Description

This endpoint is used to accept or reject livestock movements returned by HoldingMovementForReviews.

The message body identifies the movement being confirmed or rejected using the requestId returned in the HoldingMovementForReviews. The caller also identifies the tag or batch numbers of the animals that are being accepted or rejected. It is permitted to accept some tags or batches and reject others in the same transaction.

Adding additional tags or batches not present in the originalHoldingMovementForReviews is not possible using ReviewHoldingMovementRequests. To add additional animals to the transfer, a new TransferRequest must be created detailing the missing livestock. The system will treat this as a new 'ON' movement reported by the destination keeper, adjusts the holding register of the arrival keepers holding accordingly, then notifies the departure keeper of the adjustment. The departure keeper will need to confirm the adjustment using HoldingMovementForReviews and ReviewHoldingMovementRequests as for any other movement.

Authorisation

This endpoint is secured by LIS user authorization security.

You will also need to provide a Subscription key in a header. This key can be retrieved by Subscribing to the API.

Request headers

Name	Description
Ocp-Apim-Subscription-Key	LIS API subscription key
x-correlation-id	a unique identifer for this request (we recommend generating a GUID for this).

Parameters

None

Response

HTTP status: 201 (Success)

This response indicates that the request to confirm or reject a movement has been received by the system and is being processed.

The requestId field in the response body contains a unique identifier generated by the system that the caller can use to track the progress of the confirmation or rejection request as it is validated by the system.

Possible values are:

Pending - the requests is still queued and the caller should query again after a short delay
Processing - the system is currently processing the request and the caller should query again after a short delay
Success - the system has accepted the request and the system view of the animals on the users holding has been adjusted to account for the details in the movement.
Fail - the request has failed. The failure reasons are detailed in the errors section of the response.
QueueFail - the system could not proceed with validation. The caller should resubmit the request using POST /v1/ReviewHoldingMovementRequests
CompletedError - the request contained invalid or inconsistent data. The errors are detailed in the errors section of the response.
Rejected - the request contained invalid or inconsistent data. The errors are detailed in the errors section of the response.
Cancelled - a user action such as 'undoing' the request caused the processing to be cancelled during validation.
CompletedWarning - the request was accepted, but some of the content generated warnings. The warning are detailed in the warnings section of the response.
NotAvailable - this error should be reported to the LI Service Desk, together with the requestId that resulted in the error

If the result is 'Success' or 'CompletedWarning', the confirmation or rejection is complete and there are no further processing steps required by the client. The errors and warnings elements of the response body may be populated with content highlighting issues relevant to the request, but these are for information only. No corrective action is required that requires re-submission of the data.

If the requestStatus returns a value of 'Pending' or 'Processing', this indicates that the confirmation or rejection request has been queued by the system for further validation and processing. The caller must then call GET /v1/ReviewHoldingMovementRequests({requestId}) repeatedly to track the progress of the request through the validation process. The requestId parameter is the unique identifier returned in response to a successful POST /v1/ReviewHoldingMovementRequests.

Processing is complete once a call to GET /v1/ReviewHoldingMovementRequests({requestId}) returns a requestStatus of 'Success', 'Fail', 'QueueFail', 'CompletedError', 'Rejected', 'Cancelled' or 'CompletedWarning'.

To prevent overloading the system, the caller should call GET /v1/ReviewHoldingMovementRequests at a frequency no higher that once per second.

HTTP status: 400 (Bad request)

This response indicates that the supplied parameters could not be understood by the system. Correct the parameters and resubmit the request.

HTTP status: 404 (No found)

This will be returned if the parameters are malformed

/v1/ReviewHoldingMovementRequests({requestId})

GET

Name	Type	Required	Description
requestId	integer	true	the unique identifier of the confirmation or rejection request being queried
$select	string	false	query string to limit the search
$expand	string	false	Indicates the related entities to be represented inline. The maximum depth is 2.

/v1/UndoRequests

GET

Description

GET UndoRequests returns all previously submitted undo requests made by the registered user

the optional $select, and $filter parameters can be used to restrict the scope of the results set returned.

Authorisation

This endpoint is secured by LIS user authorization security.

You will also need to provide a Subscription Key in the requests header. Read the API Authentication page for details

Request headers

Name	Description
Ocp-Apim-Subscription-Key	LIS API subscription key
x-correlation-id	a unique identifer for this request (we recommend generating a GUID for this).

Parameters

Name	Type	Required	Description
$select	string	false	query string to limit the entities to be included in the response
$expand	string	false	indicates the related entities to be represented inline. The maximum depth is 2.
$filter	string	false	query string used to limit the number of items returned in the results set. When specifying dates, only those with a time part will be accepted.
$orderby	string	false	specifies the order in which items in the results set are returned
$top	int32	false	limits the number of results returned
$skip	int32	false	excluded the specified number of items from the results set

Response

HTTP status: 200 (Success)

This response indicates that system has processed the requests and the results are presented in the response body

HTTP status: 400 (Bad Request)

This response indicates that the submission has been rejected by the system as some, or all of the data supplied was found to be in error.

The CLAErrorResponse structure in the returned message provides a list of error codes, together with a textual description of each error. Additional information is provided in the errors body and identifies the field or fields in the original submission that generated each error.

Following an error response, the system discards the submitted data. The caller must correct the errors identified and resubmit the movement again.

If the caller supplied a value in the trackingId field of the submitted movement, this can be reused in a future submission as the system maintains no record of it.

/v1/UndoRequests

POST

Description

This endpoint supports the ability for users to undo or rollback requests that have previously been submitted.

In order to succeed, the user submitting the request must be the same as the user who created the request to be undone. In addition, the system may reject an undo request if other events have happened to the animals in the original requests between the time of submission and the time the undo request is processed.

To undo a request, supply a message body containing the requestId that the system returned in response to original request that should be rolled back.

{
  "content": {
    "undoRequestId": "<original request id>",
  }
}

where original request id is the requestId value returned in the success response to the call that is to be rolled back.

Authorisation

This endpoint is secured by LIS user authorization security.

You will also need to provide a Subscription key in a header. This key can be retrieved by Subscribing to the API.

Request headers

Name	Description
Ocp-Apim-Subscription-Key	LIS API subscription key
x-correlation-id	a unique identifer for this request (we recommend generating a GUID for this).

Parameters

None

Response

HTTP status: 201 (Success)

This response indicates that the undo request has been received by the system and is being processed.

The requestId field in the response body contains a unique identifier generated by the system that the caller can use to track the progress of the undo request as it is validated by the system.

Possible values are:

Pending - the requests is still queued and the caller should query again after a short delay
Processing - the system is currently processing the request and the caller should query again after a short delay
Success - the system has accepted the request and the system view of the animals on the users holding has been adjusted to account for the details in the movement.
Fail - the request has failed. The failure reasons are detailed in the errors section of the response.
QueueFail - the system could not proceed with validation. The caller should resubmit the request using POST /v1/UndoRequests
CompletedError - the request contained invalid or inconsistent data. The errors are detailed in the errors section of the response.
Rejected - the request contained invalid or inconsistent data. The errors are detailed in the errors section of the response.
Cancelled - a user action such as 'undoing' the request caused the processing to be cancelled during validation.
CompletedWarning - the request was accepted, but some of the content generated warnings. The warning are detailed in the warnings section of the response.
NotAvailable - this error should be reported to the LI Service Desk, together with the requestId that resulted in the error

If the result is 'Success' or 'CompletedWarning', the request associated with the supplied undoRequestId has been successfully undone and there are no further processing steps required by the client. The errors and warnings elements of the response body may be populated with content highlighting issues relevant to the request, but these are for information only. No corrective action is required that requires re-submission of the data.

If the requestStatus returns a value of 'Pending' or 'Processing', this indicates that the undo request has been queued by the system for further validation and processing. The caller must then call GET /v1/UndoRequests({requestId}) repeatedly to track the progress of the request through the validation process. The requestId parameter is the unique identifier returned in response to a successful POST /v1/UndoRequests.

Processing is complete once a call to GET /v1/UndoRequests({requestId}) returns a requestStatus of 'Success', 'Fail', 'QueueFail', 'CompletedError', 'Rejected', 'Cancelled' or 'CompletedWarning'.

To prevent overloading the system, the caller should call GET /v1/UndoRequests at a frequency no higher that once per second.

HTTP status: 400 (Bad Request)

This response indicates that either the system could not interpret the request (because it was malformed) or could find no record of the supplied requestId.

/v1/UndoRequests({requestId})

GET

Name	Type	Required	Description
requestId	integer	true	the unique identifier of the undo request being queried
$select	string	false	query string to limit the search
$expand	string	false	Indicates the related entities to be represented inline. The maximum depth is 2.

Standing data

Breeds (goats)

breeds

Value
Anglo Nubian
Anglo Nubian X
Angora
Angora X
Bagot
Bagot X
Boer
Boer X
British
British X
British Alpine
British Alpine X
British Guernsey
British Guernsey X
British Saanen
British Saanen X
British Toggenburg
British Toggenburg X
Cashmere
Cashmere X
English
English X
Golden Guernsey
British Toggenburg
British Toggenburg X
Cashmere
Cashmere X
English
English X
Golden Guernsey
Golden Guernsey X
Harness
Harness X
Pygmy
Pygmy X
Saanen
Saanen X
Toggenburg
Toggenburg X

Breeds (sheep)

breeds

Value
Aberblack
Aberblack X
Aberdale
Aberdale X
Aberfield
Aberfield X
Aberfield SR
Aberfield SR X
Abermax
Abermax X
Abertex
Abertex X
Badger Face Welsh Mountain
Badger Face Welsh Mountain X
Balwen Welsh Mountain
Balwen Welsh Mountain X
Beltex
Beltex X
Berrichon
Berrichon X
Beulah Speckled Face
Beulah Speckled Face X
Black Welsh Mountain
Black Welsh Mountain X
Blackface
Blackface X
Bleu du Maine
Bleu du Maine X
Blue Texel
Blue Texel X
Bluefaced Leicester
Bluefaced Leicester X
Border Leicester
Border Leicester X
Brecknock Hill Cheviot
Brecknock Hill Cheviot X
British Bleu De Maine
British Bleu De Maine X
British Charollais
British Charollais X
British Gotland
British Gotland X
British Icelandic
British Icelandic X
British Inra 401
British Inra 401 X
British Milksheep
British Milksheep X
British Rouge De L'Ouest
British Rouge De L'Ouest X
British Saanen
British Saanen X
British Texel
British Texel X
British Vendeen
British Vendeen X
Cambridge
Cambridge X
Castlemilk Moorit
Castlemilk Moorit X
Charmoise
Charmoise X
Charollais
Charollais X
Cheviot
Cheviot X
Clun Forest
Clun Forest X
Colbred
Colbred X
Corriedale
Corriedale X
Cotentin
Cotentin X
Cotswold
Cotswold X
Dalesbred
Dalesbred X
Dartmoor (Greyfaced)
Dartmoor (Greyfaced) X
Derbyshire Gritstone
Derbyshire Gritstone X
Devon & Cornwall Longwool
Devon & Cornwall Longwool X
Devon Closewool
Devon Closewool X
Dorper
Dorper X
Dorset Down
Dorset Down X
Dorset Horn & Poll Dorset
Dorset Horn & Poll Dorset X
Dutch Spotted
Dutch Spotted X
Easy Care
Easy Care X
Eppynt Hardy Speckled Face
Eppynt Hardy Speckled Face X
Est A Laine Merino
Est A Laine Merino X
Exmoor Horn
Exmoor Horn X
Gotland
Gotland X
Hampshire Down
Hampshire Down X
Hebridean
Hebridean X
Herdwick
Herdwick X
Highlander
Highlander X
Hill Radnor
Hill Radnor X
Ile de France
Ile de France X
Jacob
Jacob X
Kent Halfbred
Kent Halfbred X
Kerry Hill
Kerry Hill X
Leicester Longwool
Leicester Longwool X
Lincoln Longwool
Lincoln Longwool X
Llanwenog
Llanwenog X
Lleyn
Lleyn X
Lomond Halfbred
Lomond Halfbred X
Lonk
Lonk X
Manx Loaghtan
Manx Loaghtan X
Masham
Masham X
Meatlinc
Meatlinc X
Nelson South Wales Mountain
Nelson South Wales Mountain X
Norfolk Horn
Norfolk Horn X
North Country Cheviot
North Country Cheviot X
North Country Cheviot Hill
North Country Cheviot Park
North of England Mule
North of England Mule X
Other
Ouessant
Ouessant X
Oxford Down
Oxford Down X
Polwarth
Polwarth X
Portland
Portland X
Primera
Primera X
Romney
Romney X
Ronaldsay
Ronaldsay X
Rouge de L'Ouest
Rouge de L'Ouest X
Rough Fell
Rough Fell X
Roussin
Roussin X
Ryeland
Ryeland X
Scotch Halfbred X
Scotch Mule
Scotch Mule X
Scottish Blackface
Scottish Blackface X
Scottish Greyface
Scottish Greyface X
Shetland
Shetland X
Shetland-Cheviot
Shetland-Cheviot X
Shropshire
Shropshire X
Soay & Boreray
Soay & Boreray X
South Country Cheviot
South Country Cheviot X
South Wales Mountain
South Wales Mountain X
Southdown
Southdown X
Suffolk
Suffolk X
Swaledale
Swaledale X
Talybont Welsh
Talybont Welsh X
Teeswater
Teeswater X
Texel
Texel X
Valais Blacknose
Valais Blacknose X
Vendeen
Vendeen X
Welsh Halfbred
Welsh Halfbred X
Welsh Hill Speckled
Welsh Hill Speckled X
Welsh Mountain
Welsh Mountain X
Welsh Mule
Welsh Mule X
Wensleydale
Wensleydale X
White Face Dartmoor
White Face Dartmoor X
Whitefaced Woodland
Whitefaced Woodland X
Wiltshire Horn
Wiltshire Horn X
Zwartbles
Zwartbles X

Counties

counties

Value
Aberdeenshire
Angus
Argyllshire
Avon
Ayrshire
Banffshire
Bedfordshire
Berkshire
Berwickshire
Blaenau Gwent
Bridgend
Buckinghamshire
Buteshire
Caerphilly
Caithness
Cambridgeshire
Cardiff
Carmarthenshire
Ceredigion
Channel Isles
Cheshire
Clackmannanshire
Co Durham
Conwy
Cornwall
County Antrim
County Armagh
County Down
County Fermanagh
County Londonderry
County Tyrone
Cumbria
Denbighshire
Derbyshire
Devon
Dorset
Dumfries and Galloway
Dunbartonshire
East Lothian
East Sussex
Essex
Fife
Flintshire
Gloucestershire
Greater London
Greater Manchester
Gwynedd
Hampshire
Herefordshire
Hertfordshire
Inverness-shire
Isle of Anglesey
Isle of Man
Kent
Kincardineshire
Kinross-shire
Kirkcudbrightshire
Lanarkshire
Lancashire
Leicestershire
Lincolnshire
Merthyr Tydfil
Mid Lothian
Monmouthshire
Morayshire
Nairnshire
Neath Port Talbot
Newport
Norfolk
North Yorkshire
Northamptonshire
Northumberland
Nottinghamshire
Orkney
Oxfordshire
Peeblesshire
Pembrokeshire
Perthshire
Powys
Renfrewshire
Rhondda Cynon Taff
Ross-shire
Roxburghshire
Selkirkshire
Shetland
Shropshire
Somerset
South Yorkshire
Staffordshire
Stirlingshire
Suffolk
Surrey
Sutherland
Swansea
Torfaen
Tyne & Wear
Vale of Glamorgan
Warwickshire
West Lothian
West Midlands
West Sussex
West Yorkshire
Wigtownshire
Wiltshire
Worcestershire
Wrexham
East Yorkshire
Isles of Scilly
Merseyside
Isle of Wight

Exemption Codes

processingFlags

Sheep code	Sheep Exemption
198	Moving breeding rams to or from a market
197	Moving breeding rams to or from a holding for breeding via an approved Isolation Unit
199	Returning Breeding Rams unsold from a Market via an approved Isolation Unit
173	Returning to their correct home after being inadvertently rounded up from common land
185	Moving for immediate dedicated slaughter (direct, or via dedicated collection centre or dedicated market)
168	Moving to a show via an approved Isolation Unit
AOF017	Moving from a show via an approved Isolation Unit
195	Returning from an AI centre via an approved Isolation Unit
187	Moving to an exhibition or performance with permit (non CPH)
CPRC	Moving animals to a Central Point Recording Centre (CPRC)
InBus	Moving animals within your business that remain under your day to day care and control

Goats code	Goats Exemption
200	Moving breeding goats to or from a holding for breeding via an approved Isolation Unit
173	Returning to their correct home after being inadvertently rounded up from common land
185	Moving for immediate dedicated slaughter (direct, or via dedicated collection centre or dedicated market)
168	Moving to a show via an approved Isolation Unit
185	Moving from a show via an approved Isolation Unit)
AOF017	Moving from a show via an approved Isolation Unit
195	Returning from an AI centre via an approved Isolation Unit
187	Moving to an exhibition or performance with permit (non CPH)
CPRC	Moving animals to a Central Point Recording Centre (CPRC)
InBus	Moving animals within your business that remain under your day to day care and control

FCI Withdrawal Periods

MetFCIWithdrawalPeriod

Code	Description
WITHDRAWAL_NOT_RELEVANT	Withdrawal periods are not relevant to this movement
WITHDRAWAL_MET	Withdrawal periods have been met
WITHDRAWAL_NOT_MET	Withdrawal periods have not been met

Document Types

documentType

Value
CLA

Gender

gender

Value
Female
Male

Gender Species

genderSpecies

Value
Female
Male

Holding Types

departureHoldingType / destinationHoldingType

Value	Description
ABATTOIR	Abattoir
AI CENTRE	Artificial Insemination Centre
ASSEMBLY	Assembly Centre
COLLECTION	Collection Centre
COMMON	Common Land
OTHER	Other
PORT	Port
PRODUCER	Agricultural Holding
QUARANTINE	Quarantine Unit
SALEYARD	Market
SHOWGROUND	Showground

Request Types

requestType

id value	name value
4	Movement / Transfer
15	Correct Movement
32	Undo Request
145	Review Holding Movement
160	Undo Request Partial

Species

species

Value
Deer
Goats
Sheep

Stock Types

stockType

Value
Ewes
Ewe Lambs
Others
Rams
Total Goats
Total Sheep

Transporter Types

transporterType

Value
Departure Keeper
Haulier
Destination Keeper

Titles (person prefixes such as Mr, Mrs, Dr, etc.)

title

Value
Baron
Baroness
Captain
Colonel
Count
Countess
Dame
Dr
Duke
Earl
Father
FR
Lady
Lord
Lt Colonel
Major
Messrs
Miss
Mr
Mrs
Ms
Prof
Rev
Rt Hon
Sir
Viscount

Error codes and error descriptions

Error codes relating to each of the livestock movement services are available in a collection of comma separated (CSV) files named after the service that they relate to. The files have been assembled into a compressed .zip file which is available for download from this location.

Each file contain a list of the error codes and a textual description that can be returned in the errors body of the response the system returns when an endpoint is invoked.

Using $filter to limit results sets

Many of the LIS service endpoints will accept a URI with a $filter System Query Option that identifies the subset of the Entries held by the LIS service that should be returned in the results set in response to a request.

Taking /HoldingMovementsForReviews as an example, a $filter string to limit the results set to be only those Entries occurring between two dates would have the following form:

/HoldingMovementForReviews/ReviewBySpecies(species='Sheep',holding=’<the holding of interest>')?$filter=movementDate ge <start date> and movementDate le <end date>

where <start date> and <end date> are an ISO8601 time string. NOTE that the time string must include a time component; specify midnight to include all entries for the start date.

The operations supported by $filter are shown in the table below:

Operator	Description
Eq	Equal to
Ne	Not equal to
Gt	Greater than
Ge	Greater than or equal to
Lt	Less than
Le	Less than or equal to
Not	Logical negation

Common terms

The paragraphs below list the common terms and data formats that are widely used across all interfaces to the LIS service.

Holding CPH

A ‘holding’ is the land and buildings that are used to house livestock.

CPH (County Parish Holding) is a unique identifier that refers to a holding.

Every holding that keeps livestock must obtain a CPH number from the Rural Payments Agency. The CPH is a 9-digit number (e.g. 12/345/6789). The first 2 digits relate to the county, the next 3 relate to the parish, and the last 4 digits identify the holding.

Holding MHS

A 4-digit number that is usually assigned to an Abattoir by the Food Standards Agency.

Commonly known as an MHS number, this can be used as an alternative to a CPH when recording livestock movements to an abattoir.

Dates and Times

Dates and times are represented in the CLA interface as .NET DateTimeOffset objects.

String representation of the date time is ISO8601 and the format string is 'yyyy-MM-ddTHH:mm:ssK', where:

yyyy - 4 digit year
MM - 2-digit month
dd - 2-digit day
HH - 2-digit hour
mm - 2-digit minutes
ss - 2-digit seconds
K - the timezone as [+/-]hz:mz difference from UTC

Note: UTC can be expressed as either using the character 'Z' or +00:00

Tag numbers

Tag numbers are a unique identifier used for individual animals.

For sheep, the Tag number format starts with the letters UK, followed by either 0 or 1, then 6 digits, an optional space, then 5 more digits

Valid examples are: UK0123456 12345, UK012345612345

For goats, the Tag number format starts with the letters UK, followed by 6 digits, an optional space, then 5 more digits

Radio Frequency Identifier (RFID)

The RF_ID (or RFID) is the ‘Radio Frequency Identifier’ and is the unique number returned by an RFID reader when an electronic tag is read.

CLA can accept RF_ID value in HEX, Decimal and UK WYSIWYG format, such as:

8200ce82dfdae801
0826012345612345
UK012345612345
UK0123456 12345

Batch numbers

A batch is used to denote a flock or herd of animals in a movement record, rather than individuals.

A batch can be defined as <BatchNumber> x <AnimalCount> [<I.D. Mark> - <StockType>], where <I.D. Mark> and <StockType> are both optional.

Examples of batch numbers include:

UK999999 x 2 (Blue)
UK999999 x 2 (Blue – Total Sheep)
UK999999 x 2

For movements relating to sheep and goats, a valid batch number always begins with the characters 'UK' and is followed by 6 digits.

Where a batch number is unknown, the reserved valued 'unknown' can be used. This value is case-insensitive; 'UNKNOWN', 'unknown' and Unknown' will all be accepted.

Devices

A device is used to represent a tag that is attached to an animal.

A key concept of CLA is that a 'tag upload' is the act of registering a tag and a 'device application' is the act of attaching a tag to an animal. A 'tag number' is the actual number of the tag, and so applies regardless of whether the tag is attached to an animal or not.

Processing Flags

Some endpoints include one or more Processing Flags attributes that are used to modify how a request is validated and processed.

Exemption Codes on a movement are an example of ProcessingFlags usage. Specifying an Exemption Code in the ProcessingFlags entry of a livestock movement records the exemptions selected by the user as being appropriate for the movement. The use of a Processing Flag may impact the processing of the movement, especially with respect to the application of standstill rules.

Any Processing Flags values supplied as part of the movement record are stored within the system as pertaining to that movement. It is important, therefore that the submitter of the movement is certain that any ProcessingFlags values supplied are applicable to the livestock movement they are attached.

CLA API

Please use a tracking ID on requests

Overview

Versioning

API browser and Open API file

HTTP status codes

Request rate limit

Dealing with large results sets

URL encoding of data

Tracking IDs

Endpoints

Description

Authorisation

Request headers

Parameters

Response

Description

Authorisation

Request headers

Parameters

Response

Description

Authorisation

Request headers

Parameters

Response

Description

Authorisation

Request headers

Parameters

Response

Description

Description

Authorisation

Request headers

Parameters

Response

Description

Authorisation

Request headers

Parameters

Response

Duplicate movements

Description

Authorisation

Request headers

Parameters

Response

Description

Authorisation

Request headers

Parameters

Response

Description

Authorisation

Request headers

Parameters

Response

Description

Authorisation

Request headers

Parameters

Response

Description

Authorisation

Request headers

Parameters

Response

Description

Authorisation

Request headers

Parameters

Response

Standing data

Error codes and error descriptions

Using $filter to limit results sets

Common terms

Holding CPH

Holding MHS

Dates and Times