Animals

These routes manage the animals of the business that connected your app: the ones it owns of record, and the ones it co-owns.

Access

A token from the authorization-code grant. A client-credentials token answers 403 0010010000406.
The business must keep a valid payment card on file; without one, 403 0010010000407.
Scopes animal:read (list, get) and animal:write (create, update, archive), declared by your app and granted by the business on the consent page — see Business resources.

The animal

{
  "id": "a3c8e1f0-6b2d-4e7a-9c15-0d4f8b2e6a71",
  "upcCode": "UPC-DOG-7Q2M4K",
  "name": "Biscuit",
  "registeredName": "Sunnyvale Golden Biscuit",
  "species": "DOG",
  "breedCode": "LABR",
  "sex": "F",
  "dateOfBirth": "2024-01-01",
  "lifeStatus": "ALIVE",
  "isOwnerOfRecord": true,
  "createdAt": "2026-10-18T09:12:44Z"
}

Field	Meaning
`upcCode`	The animal’s United Pet Club code.
`name`	The call name, else the registered name.
`species`, `breedCode`	Codes, as you send them. Species codes are listed on Species and gestation.
`sex`	`M`, `F`, `I` (intersex) or `U` (unknown).
`isOwnerOfRecord`	`false` when the business is a co-owner.

List animals

GET /api/animal/v1/animals?species=DOG&page=1&pageSize=20

The animals the business owns of record, newest first; archived animals are left out. Co-owned animals answer by id but are not listed. species is a species code (any case). The answer is { "data": [...], "pagination": {...} } — see Pagination.

Get an animal

GET /api/animal/v1/animals/{id}

An animal the business owns of record or co-owns. Any other animal answers 404, exactly like one that does not exist.

Register an animal

POST /api/animal/v1/animals
Content-Type: application/json

{ "name": "Biscuit", "species": "DOG", "breedCode": "LABR", "sex": "F", "dateOfBirth": "2024-01-01" }

Field	Required	Meaning
`name`	yes	The call name. It needs a Latin spelling.
`species`	yes	A species code.
`breedCode`	no	A breed code of that species.
`sex`	no	`M`, `F`, `I`, `U` or `MALE`, `FEMALE`, `INTERSEX`, `UNKNOWN` (default `U`).
`dateOfBirth`	no	`yyyy-MM-dd`.
`confirmedNotDuplicate`	no	`true` to register an animal born on the same day as another of the business’s, after a `409` `Animal_AnimalRegistry_AD_DuplicateBirthDate_RJ`. The same name and the same date of birth stay a duplicate.

The business becomes the owner of record. The answer is 201 Created with a Location header and the animal.

Update an animal

PATCH /api/animal/v1/animals/{id}
Content-Type: application/json

{ "name": "Biscuit II", "dateOfBirth": "2024-01-03" }

name, breedCode, sex and dateOfBirth; a field you leave out (or send as null) is unchanged. The species cannot change. The answer is the updated animal.

Archive an animal

DELETE /api/animal/v1/animals/{id}

DELETE archives the animal: its record, history and UPC code are kept, it leaves the list, and afterwards every route answers 404 for it. It cannot be undone through this API. The answer is 204 No Content.

Errors

Status	`platformResponseCode`	Cause
`400`	`0010010000400`	`page` or `pageSize` out of range, or no `name` / `species` on a create.
`400`	`Animal_AnimalRegistry_VL_Request_RJ`	A malformed request or an unknown `sex`.
`400`	`Animal_AnimalRegistry_VL_Species_FL`	An unknown species code.
`400`	`Animal_AnimalRegistry_VL_Lookup_FL`	An unknown breed code, or a breed of another species.
`400`	`Animal_AnimalRegistry_VL_Name_RJ`, `…_VL_Length_RJ`	A name without a Latin spelling, or too long.
`400`	`Animal_AnimalOwnership_VL_PlaceOwner_RJ`	The business is a place profile, which cannot own animals.
`400`	`Animal_AnimalOwnership_VL_ParentBirthDate_RJ`, `…_VL_OffspringBirthDate_RJ`	The date of birth contradicts the recorded parents or offspring.
`404`	`Animal_AnimalRegistry_GT_Resource_FL`	Not one of the business’s animals, or archived.
`409`	`Animal_AnimalRegistry_AD_Duplicate_RJ`	The business already has an animal with this name and date of birth.
`409`	`Animal_AnimalRegistry_AD_DuplicateBirthDate_RJ`	Another animal of the business was born that day: resend with `confirmedNotDuplicate: true` if it is a different animal.
`409`	`Animal_AnimalRegistry_AD_UpcCode_FL`	A UPC code could not be assigned. Retry the create.

Everything else follows Errors.