View on GitHub

easitrace

« Back to Contents

Movement Services | LIS

LIS (Livestock Information Service) is the unified movement tracking service for livestock in Great Britain, designed to replace BCMS (cattle), ARAMS (sheep, goats), and eAML2 (pigs).

Overview

This document covers the transaction types and capabilities available through Easitrace for LIS.

LIS supports 5 transaction capabilities:

Transaction Type Capability Description
MOV-OFF Movement Off Record movement of animals off a property
MOV-ON Movement On Record movement of animals onto a property
MOV-IN Incoming Movements Retrieve incoming movements at a property
UPDATEMOV-OFF Update Movement Off Update details of a movement departure
UPDATEMOV-ON Update Movement On Update details of a movement arrival

Sections

Field Keys: Generic vs Specific

LIS transactions use a dual-key field system to support both backward compatibility and cross-service consistency.

What are Generic and Specific Keys?

Why Both Exist

This dual-key approach allows:

  1. Cross-Service Consistency: Application developers can use the same generic key names regardless of which movement service they’re integrating with
  2. Backward Compatibility: Existing integrations using specific keys continue to work
  3. Future-Proofing: New services can be added without breaking existing code

How It Works for API Consumers

When submitting a transaction, you can use either the generic key or the specific key in the fields object. The system automatically maps between them.

Example - Both are equivalent:

{
  "fields": {
    "Departure.Identifier": "01/007/0001"
  }
}

{
  "fields": {
    "LIS.Farm.Sheep.Departure.Location": "01/007/0001"
  }
}

For more details on the field system, see Transaction Fields Documentation.

Movement Off

Record movement of animals off a property. This transaction notifies LIS when animals leave a holding.

Fields

Required:

Optional:

Animal Requirements

Example Transaction

{
  "reference": "LIS-MOV-OFF-001",
  "transactionDate": "2024-03-10T10:30:00Z",
  "type": "MOV-OFF",
  "serviceTag": "LIS",
  "speciesCode": "S",
  "propertyIdentifier": "01/007/0001",
  "fields": {
    "LIS.Farm.Sheep.Departure.Location": "01/007/0001",
    "LIS.Farm.Sheep.Destination.Location": "33/444/5555",
    "LIS.Farm.Sheep.Movement.TransferDate": "2024-03-10T00:00:00Z",
    "LIS.Farm.Sheep.Movement.DepartureDate": "2024-03-10T08:00:00Z",
    "LIS.Farm.Sheep.Movement.LoadingDate": "2024-03-10T07:30:00Z",
    "LIS.Farm.Sheep.Movement.DeparturePostCode": "SW1A 1AA",
    "LIS.Farm.Sheep.Movement.DepartureFirstName": "John",
    "LIS.Farm.Sheep.Movement.DepartureLastName": "Smith",
    "LIS.Farm.Sheep.Hauler.Type": "Haulier",
    "LIS.Farm.Sheep.Movement.HailierName": "Lucky Transport",
    "LIS.Farm.Sheep.Hauler.AuthNumber": "HAL123456"
  },
  "animals": [
    {
      "rfid": "982000123456789",
      "visual": "UK100015401645"
    },
    {
      "rfid": "982000123456790",
      "visual": "UK100015501619"
    }
  ],
  "untaggedAnimals": []
}

For more information about submitting Transactions see Submitting transactions.

Movement On

Record movement of animals onto a property. This transaction notifies LIS when animals arrive at a holding.

Fields

Required:

Optional:

Animal Requirements

Example Transaction

{
  "reference": "LIS-MOV-ON-001",
  "transactionDate": "2024-03-10T14:30:00Z",
  "type": "MOV-ON",
  "serviceTag": "LIS",
  "speciesCode": "S",
  "propertyIdentifier": "33/444/5555",
  "fields": {
    "LIS.Farm.Sheep.Destination.Location": "33/444/5555",
    "LIS.Farm.Sheep.Movement.ArrivalDate": "2024-03-10T00:00:00Z",
    "LIS.Farm.Sheep.Departure.Location": "01/007/0001",
    "LIS.Farm.Sheep.Movement.DepartureDate": "2024-03-10T08:00:00Z",
    "LIS.Farm.Sheep.Movement.UnLoadingDate": "2024-03-10T14:00:00Z",
    "LIS.Farm.Sheep.Movement.DestinationPostCode": "SW1A 2AA",
    "LIS.Farm.Sheep.Movement.DestinationFirstName": "Jane",
    "LIS.Farm.Sheep.Movement.DestinationLastName": "Doe"
  },
  "animals": [
    {
      "rfid": "982000123456789",
      "visual": "UK100015401645"
    },
    {
      "rfid": "982000123456790",
      "visual": "UK100015501619"
    }
  ],
  "untaggedAnimals": []
}

For more information about submitting Transactions see Submitting transactions.

Incoming Movements

Retrieve a list of incoming movements at a property. This transaction queries LIS for movements that are expected to arrive at the specified location.

Results for this transaction can be obtained via GET /api/properties/{id}/transactions/{transactionId}/historical API. It will return an array of movements, each with details in a fields property.

Fields

Optional:

Example Transaction

{
  "reference": "LIS-INCOMING-001",
  "transactionDate": "2024-03-10T10:30:00Z",
  "type": "MOV-IN",
  "serviceTag": "LIS",
  "speciesCode": "S",
  "propertyIdentifier": "33/444/5555",
  "fields": {},
  "animals": [],
  "untaggedAnimals": []
}

Once the transaction succeeds, the results can be queried by providing the transaction id to GET /api/properties/{id}/transactions/{transactionId}/historical API.

For more information about submitting Transactions see Submitting transactions.

Update Movement Off

Update details of a previously submitted movement off transaction.

Fields

Required:

Optional:

Example Transaction

{
  "reference": "LIS-UPD-MOV-OFF-001",
  "transactionDate": "2024-03-10T15:00:00Z",
  "type": "UPDATEMOV-OFF",
  "serviceTag": "LIS",
  "speciesCode": "S",
  "propertyIdentifier": "01/007/0001",
  "fields": {
    "LIS.Farm.Sheep.Departure.Location": "01/007/0001",
    "LIS.Farm.Sheep.Destination.Location": "33/444/5555",
    "LIS.Farm.Sheep.Movement.TransferDate": "2024-03-10T00:00:00Z",
    "LIS.Farm.Sheep.Movement.DepartureDate": "2024-03-10T08:00:00Z"
  },
  "animals": [],
  "untaggedAnimals": []
}

For more information about submitting Transactions see Submitting transactions.

Update Movement On

Update details of a previously submitted movement on transaction.

Fields

Required:

Optional:

Example Transaction

{
  "reference": "LIS-UPD-MOV-ON-001",
  "transactionDate": "2024-03-10T15:00:00Z",
  "type": "UPDATEMOV-ON",
  "serviceTag": "LIS",
  "speciesCode": "S",
  "propertyIdentifier": "33/444/5555",
  "fields": {
    "LIS.Farm.Sheep.Departure.Location": "01/007/0001",
    "LIS.Farm.Sheep.Destination.Location": "33/444/5555",
    "LIS.Farm.Sheep.Movement.TransferDate": "2024-03-10T00:00:00Z",
    "LIS.Farm.Sheep.Movement.DepartureDate": "2024-03-10T08:00:00Z",
    "LIS.Farm.Sheep.Movement.ArrivalDate": "2024-03-10T14:00:00Z"
  },
  "animals": [],
  "untaggedAnimals": []
}

For more information about submitting Transactions see Submitting transactions.

Supported Species

LIS supports the following species:

Currently, the implementation is primarily focused on Sheep (S).

Property Identifier Format

LIS uses CPH (Common Holding Number) as the property identifier format.

Format: ##/###/#### (8 digits with 2 forward slashes)
Example: 01/007/0001

All CPH values in LIS transactions must conform to this format:

Authentication Requirements

LIS uses Azure B2C for authentication. The system requires:

OAuth2 Bearer Token Authentication

The Service Provider is responsible for:

  1. Initiating the OAuth2 authentication flow with Azure B2C
  2. Passing the authorization code to Easitrace
  3. Exchanging the code for a refresh token (valid for 90 days)
  4. Storing credentials at the property level

Token Expiration and Refresh

For detailed information on LIS authentication flow, see LIS Authentication.

For general authentication concepts and other services, see Services Authentication.