Animal

Response Codes and Explanations

Animal Registration is the event of an animal being reported to the system. The user can submit the request to register an animal in either synchronous or asynchronous mode.

Following submission of the animal registration using POST /animals, the system will validate the data content and return an immediate response indicating whether the content has been accepted for validation in case of async or the actual output in case of sync. The following response codes are possible:

• Code 200. This response indicates the registration request submission has been successful, and the response contains the unique animal identifier for the registered animal.
• Code 202. 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 registration request as it is validated by the system.
• Code 400. This response indicates that the submission has been rejected by the system because some or all of the data supplied was found to be in error. The Error structure in the returned message provides a list of error codes, along with a textual description of each error. Additional information is provided in the errors, identifying 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 registration.
• Code 500. This response indicates that something went wrong with the internal server and the request should be resubmitted.

In case when the request is submitted in async mode and once the registration request has been accepted by the system, the caller then calls GET /requeststatus/{requestId} repeatedly to track its progress through the validation process. The requestId parameter is the unique identifier returned in response to a successful POST /animals. This is used by the system to identify the transaction that is being queried. To prevent overloading the system, the caller should call GET /requeststatus/{requestId} a frequency no less than specified in the return parameter X-Retry-After.

Request Response Structure

Consider a scenario where a keeper registers an animal born at the holding (within the statutory time limit).

To register an animal, use the POST /animals endpoint, supplying the following information in the content body, with the resulting response:

{
  "animal": {
    "identifier": "UK12345678910",
    "species": "Cattle",
    "name": "Ian",
    "sex": "female",
    "productionType": "meat"
  },
  "breed": {
    "code": "DEX"
  },
  "importParents": {
    "sire": {
      "identifier": ""
    },
    "geneticDam": {
      "identifier": ""
    },
    "birthDam": {
      "identifier": "UK12345678910"
    }
  },
  "birth": {
    "site": {
      "identifiers": [
        {
          "identifier": "27/811/2976"
        }
      ]
    },
    "date": "2025-06-15",
    "year": 0,
    "mark": "556773",
    "assistedBirthFlag": false,
    "multipleBirthsFlag": false
  },
  "death": {
    "carcassCollectionSite": {
      "identifiers": [
        {
          "identifier": ""
        }
      ]
    },
    "date": "2025-06-15",
    "reason": {
      "name": "Abattoir Kill"
    },
    "site": {
      "identifiers": [
        {
          "identifier": ""
        }
      ]
    },
    "tseTestRequiredFlag": false,
    "createdDateTime": "2025-06-15T11:07:52.360Z",
    "updatedDateTime": "2025-06-15T11:07:52.360Z"
  },
  "registration": {
    "birthDam": {
      "identifier": "UK12345678910"
    },
    "geneticDam": {
      "identifier": ""
    },
    "sire": {
      "identifier": "UK12345678910"
    },
    "site": {
      "identifiers": [
        {
          "identifier": "27/811/2976"
        }
      ]
    },
    "date": "2025-06-15",
    "category": "birthRegistration",
    "identificationDate": "2025-06-15"
  }
}

Payload Details