View on GitHub

easitrace

« Back to Contents

Movement Services | SCOT-MOVES

SCOT-MOVES is the Movement Service for Cattle and Sheep in Scotland.

Overview

This document covers the transaction types and capabilities available through Easitrace for SCOT-MOVES.

SCOT-MOVES supports 8 transaction capabilities:

Transaction Type Capability Description
GET-ADDTNL-HOLDINGS Get Additional Holdings Retrieve additional cattle holdings/properties
GET-ANM Animal Query Query animals currently on a property
ALLOC Allocate Animals Allocate animals to a specific property
REG Register Register birth of animals at a property
MOV-OFF Movement Off Record movement of animals off a property
MOV-ON Movement On Record movement of animals onto a property
MOV-INTERNAL Move Internal Record movement between holdings within same business
DTH Death Record death of animals at a property

Sections

Authentication

ScotMoves authentication is handled through the ScotEID system. For detailed authentication setup, see the ScotMoves Authentication Guide.

ScotMoves requires:

For more details, see Services Authentication.

Field Keys: Generic vs Specific

SCOT-MOVES 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": "89/677/0009"
  }
}

{
  "fields": {
    "ScotMoves.Movement.DepartureLocation": "89/677/0009"
  }
}

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

Get Additional Holdings

Retrieve additional cattle holdings/properties associated with the specified property. This transaction queries SCOT-MOVES for related holdings.

Results for this transaction can be obtained via GET /api/properties/{id}/transactions/{transactionId}/historical API. It will return an array of transactions, each representing a single holding with details in a fields property. Each such transaction is linked to the original via the parentTransactionId field.

Fields

No fields are required for this transaction type.

Example Transaction

{
  "reference": "SCOTMOVES-HOLDING",
  "transactionDate": "2019-08-13T21:30:00Z",
  "type": "GET-ADDTNL-HOLDINGS",
  "serviceTag": "SCOT-MOVES",
  "speciesCode": "C",
  "propertyIdentifier": "89/677/0009",
  "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.

Animal Query

Query and retrieve animals currently on a property. This transaction allows you to get a list of animals registered at a specific holding.

Results for this transaction can be obtained via GET /api/properties/{id}/transactions/{transactionId}/historical API. It will return an array of transactions, each representing a single animal with details in a fields property. Each such transaction is linked to the original via the parentTransactionId field.

Fields

Optional:

Note: The response format changes based on this field:

Example Transaction

{
  "reference": "SCOTMOVES-ANIMAL-QUERY",
  "transactionDate": "2019-08-13T21:30:00Z",
  "type": "GET-ANM",
  "serviceTag": "SCOT-MOVES",
  "speciesCode": "C",
  "propertyIdentifier": "89/677/0009",
  "fields": {
    "ScotMoves.GetAnimals.IncludeSubHoldings": true
  },
  "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.

Allocate Animals

Allocate animals to a specific property/holding. This transaction assigns animals to an initial CPH (County-Parish-Holding) identifier.

Fields

Optional:

Animal Requirements

Example Transaction

{
  "reference": "SCOTMOVES-ALLOCATE",
  "transactionDate": "2019-08-13T21:30:00Z",
  "type": "ALLOC",
  "serviceTag": "SCOT-MOVES",
  "speciesCode": "C",
  "propertyIdentifier": "89/677/0009",
  "fields": {
    "ScotMoves.Movement.InitialCPH": "89/677/0009"
  },
  "animals": [
    {
      "rfid": "982000123456789",
      "visual": "UK100015401645"
    },
    {
      "rfid": "982000123456790",
      "visual": "UK100015501619"
    }
  ],
  "untaggedAnimals": []
}

For more information about submitting Transactions see Submitting transactions.

Register animals

Register the birth of animals at a property. This transaction records newborn calves in the SCOT-MOVES system.

Fields

Required:

Required per animal:

Optional per animal:

Example Transaction

{
  "reference": "SCOTMOVES-REGISTER",
  "transactionDate": "2019-08-13T21:30:00Z",
  "type": "REG",
  "serviceTag": "SCOT-MOVES",
  "speciesCode": "C",
  "propertyIdentifier": "89/677/0009",
  "fields": {
    "ScotMoves.Register.BirthLocation": "89/677/0009",
    "ScotMoves.Register.MainLocation": "89/677/0009"
  },
  "animals": [
    {
      "visual": "543210123458",
      "damOfficialId": "543210123058",
      "sireOfficialId": "543210123158",
      "breedCode": "AA",
      "birthDate": "2020-07-22T22:27:08.712Z",
      "sexCode": "M",
      "fields": {
        "UserReference": "Calf 1"
      }
    },
    {
      "visual": "543210123459",
      "damOfficialId": "543210123058",
      "sireOfficialId": "543210123158",
      "breedCode": "AA",
      "birthDate": "2020-07-22T22:27:08.712Z",
      "sexCode": "M",
      "fields": {
        "UserReference": "Calf 2"
      }
    }
  ],
  "untaggedAnimals": []
}

For more information about submitting Transactions see Submitting transactions.

Movements

Movements Off

Record movement of animals off a property. This transaction notifies SCOT-MOVES when animals leave a holding.

Fields

Required:

Optional:

Animal Requirements

For animals provided as part of a movement off, only the visual property is required, although it must be in the following format:
NB: Spaces are shown by ⋅, numbers by N.

UK⋅N⋅NNNNNN⋅NNNN⋅N

Example Transaction

{
  "transactionDate": "2020-08-29T22:27:08.712Z",
  "type": "MOV-OFF",
  "speciesCode": "C",
  "serviceTag": "SCOT-MOVES",
  "propertyIdentifier": "89/677/0009",
  "fields": {
    "ScotMoves.Movement.DepartureLocation": "89/677/0009",
    "ScotMoves.Movement.DestinationLocation": "84/567/0037"
  },
  "animals": [
    {
      "visual": "5432101234601"
    },
    {
      "visual": "5432101234602"
    }
  ],
  "untaggedAnimals": []
}

For more information about submitting Transactions see Submitting transactions.

Movements On

Record movement of animals onto a property. This transaction notifies SCOT-MOVES when animals arrive at a holding.

Fields

Required:

Optional:

Animal Requirements

For animals provided as part of a movement on, only the visual property is required, although it must be in the following format:
NB: Spaces are shown by ⋅, numbers by N.

UK⋅N⋅NNNNNN⋅NNNN⋅N

Example Transaction

{
  "transactionDate": "2020-08-29T22:27:08.712Z",
  "type": "MOV-ON",
  "speciesCode": "C",
  "serviceTag": "SCOT-MOVES",
  "propertyIdentifier": "84/567/0037",
  "fields": {
    "ScotMoves.Movement.DepartureLocation": "89/677/0009",
    "ScotMoves.Movement.DestinationLocation": "84/567/0037"
  },
  "animals": [
    {
      "visual": "5432101234601"
    },
    {
      "visual": "5432101234602"
    }
  ],
  "untaggedAnimals": []
}

For more information about submitting Transactions see Submitting transactions.

Move Internal

Record movement of animals between holdings within the same business. This transaction type is used when moving animals between different CPHs that belong to the same keeper.

Difference from MOV-OFF/MOV-ON: Use Move Internal when both the departure and destination holdings belong to the same business/keeper. Use MOV-OFF and MOV-ON for movements between different keepers.

Fields

Required:

Optional:

Animal Requirements

Example Transaction

{
  "reference": "SCOTMOVES-MOVE-INTERNAL",
  "transactionDate": "2020-08-29T22:27:08.712Z",
  "type": "MOV-INTERNAL",
  "serviceTag": "SCOT-MOVES",
  "speciesCode": "C",
  "propertyIdentifier": "89/677/0009",
  "fields": {
    "ScotMoves.Movement.DepartureLocation": "89/677/0009",
    "ScotMoves.Movement.DestinationLocation": "89/677/0010",
    "ScotMoves.Movement.MovementDate": "2020-08-29"
  },
  "animals": [
    {
      "visual": "UK100015401645"
    },
    {
      "visual": "UK100015501619"
    }
  ],
  "untaggedAnimals": []
}

For more information about submitting Transactions see Submitting transactions.

Record animal death

Record the death of animals at a property. This transaction notifies SCOT-MOVES when animals die at a holding.

Fields

Required:

Animal Requirements

For animals provided as part of a death record, only the visual property is required, although it must be in the following format:
NB: Spaces are shown by ⋅, numbers by N.

UK⋅N⋅NNNNNN⋅NNNN⋅N

Example Transaction

{
  "transactionDate": "2020-07-22T22:27:08.712Z",
  "type": "DTH",
  "speciesCode": "C",
  "serviceTag": "SCOT-MOVES",
  "propertyIdentifier": "89/677/0009",
  "fields": {
    "ScotMoves.Death.MainLocation": "89/677/0009",
    "ScotMoves.Death.Date": "2020-08-22"
  },
  "animals": [
    {
      "visual": "UK100015401645"
    },
    {
      "visual": "UK100015501619"
    }
  ],
  "untaggedAnimals": []
}

For more information about submitting Transactions see Submitting transactions.