The Sheep Service went live 28th March 2022, Cattle Service coming soon.

CLA API

Version:

v1.0

Status:

Loading

Please use a tracking ID on requests

When making requests via this API, please use a unique tracking Id via each payload. This will ensure there is no duplicate data and will throw an error if the situation occurs. You can read about tracking IDs within our movements section.

Lifecycle stageLive
Open API fileView Open API file
Supported Authorisation types
  • user-restricted
  1. Overview
  2. Versioning
  3. API browser and Open API file
  4. HTTP status codes
  5. Request rate limit
  6. Dealing with large results sets
  7. URL encoding of data
  8. Tracking IDs
  9. Endpoints
  10. Standing data
  11. Error codes and error descriptions
  12. Using $filter to limit results sets
  13. Common terms

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:

SampleDescription
HoldingURL encoding of CPH replaces the forward slashes as follows: holding='26/001/8033' becomes holding='26%2f001%2f8033'
Dates and timesURL 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
/v1/TransferRequests
POST
/v1/TransferRequests({requestId})
GET
/v1/CorrectTransferRequests
GET
/v1/CorrectTransferRequests
POST
/v1/CorrectTransferRequests({requestId})
GET
/v1/HoldingMovementForReviews(species='{species}',holding='{holding}')
GET
/v1/ReviewHoldingMovementRequests
GET
/v1/ReviewHoldingMovementRequests
POST
/v1/ReviewHoldingMovementRequests({requestId})
GET
/v1/UndoRequests
GET
/v1/UndoRequests
POST
/v1/UndoRequests({requestId})
GET

Standing data

Breeds (goats)
breeds
Breeds (sheep)
breeds
Counties
counties
Exemption Codes
processingFlags
FCI Withdrawal Periods
MetFCIWithdrawalPeriod
Document Types
documentType
Gender
gender
Gender Species
genderSpecies
Holding Types
departureHoldingType / destinationHoldingType
Request Types
requestType
Species
species
Stock Types
stockType
Transporter Types
transporterType
Titles (person prefixes such as Mr, Mrs, Dr, etc.)
title

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 occuring 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:

OperatorDescription
EqEqual to
NeNot equal to
GtGreater than
GeGreater than or equal to
LtLess than
LeLess than or equal to
NotLogical 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.