On this page
Authentication POST /api/animals POST /api/animals/{chipNumber}/events GET /api/animals/{chipNumber} Event Types & Statuses Error Responses Example Integration Support

Furball Registry API

Integrate your shelter management system with the Furball Registry to automatically publish medical records for your animals.

Authentication

All API requests require an API key for authentication.

  1. Register an account at furballregistry.com
  2. Go to Settings > API Keys
  3. Generate a new key — it is shown only once, so copy it immediately
  4. Include it in every request as a Bearer token:
Authorization: Bearer freg_xxxxx

Keys are org-scoped. All animals and events created through the API are attributed to your organization.

Endpoints

POST /api/animals

Upsert an animal by chip number. Creates the animal if new, updates non-null fields if existing. Your organization is automatically added as a custodian.

Request
{
  "chipNumber": "985112345678901",
  "name": "Milo",
  "species": "Dog",
  "breed": "Labrador Mix",
  "gender": "Male",
  "birthDateEstimate": "2024-04-01T00:00:00Z",
  "weight": 45.5,
  "weightUnit": "lbs"
}

Only chipNumber is required. Other fields are optional — only non-null fields are updated.

Response 200 OK
{
  "id": 42,
  "chipNumber": "985112345678901"
}

POST /api/animals/{chipNumber}/events

Clear-and-replace all system-published entries for this animal from your organization. Manual entries (added via the website by any user) are never affected.

This uses the clear-and-replace pattern: send ALL current events every time. The registry deletes your previous system entries and inserts the new batch. No diffing, no partial updates.

Request
{
  "events": [
    {
      "eventType": "Vaccination",
      "eventName": "Rabies",
      "eventStatus": "CompletedOn",
      "eventDate": "2026-04-03T00:00:00Z",
      "text": "Administered by Dr. Smith"
    },
    {
      "eventType": "Test",
      "eventName": "Heartworm",
      "eventStatus": "CompletedOn",
      "eventDate": "2026-04-03T00:00:00Z",
      "eventResult": "Negative"
    },
    {
      "eventType": "Procedure",
      "eventName": "Spay",
      "eventStatus": "Needed",
      "text": "Scheduled for next month"
    }
  ]
}

Requires: Your org must be a custodian of the animal (claimed via POST /api/animals or the website).

Response 200 OK
{
  "count": 3
}

GET /api/animals/{chipNumber}

Get an animal's profile and full timeline of entries from all organizations.

Response 200 OK
{
  "chipNumber": "985112345678901",
  "name": "Milo",
  "species": "Dog",
  "breed": "Labrador Mix",
  "gender": "Male",
  "entries": [
    {
      "id": 1,
      "orgName": "Happy Tails Rescue",
      "authorName": "Happy Tails Rescue",
      "source": "System",
      "isStructured": true,
      "eventType": "Vaccination",
      "eventName": "Rabies",
      "eventStatus": "CompletedOn",
      "eventDate": "2026-04-03T00:00:00Z",
      "eventResult": null,
      "text": "Administered by Dr. Smith",
      "createdAt": "2026-04-05T12:00:00Z"
    }
  ]
}

Event Types & Statuses

EventType values

ValueDescription
VaccinationVaccine administered or scheduled
TestDiagnostic test (heartworm, fecal, FeLV/FIV)
MedicationDrug prescribed or administered
VetVisitVeterinary appointment
ProcedureSurgical or medical procedure (spay, neuter, dental)
NoteGeneral observation or note
ConditionDiagnosis or condition (injury, illness)
OngoingCareOngoing care need (therapy, training, special diet)

EventStatus values

ValueMeaningEventDate?
NeededTo-do, no date setNo
CompletedDone, date unknownNo
CompletedOnDone on a specific dateYes
DueOnScheduled for a specific dateYes

EventResult values (for Tests)

Positive, Negative, Inconclusive, Unknown, or any free text.

Error Responses

StatusMeaning
400Bad request — missing required fields
401Unauthorized — missing or invalid API key
403Forbidden — not a custodian of this animal
404Not found — animal does not exist

Example: Full Integration Flow

# 1. Register the animal
curl -X POST https://furballregistry.com/api/animals \
  -H "Authorization: Bearer freg_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"chipNumber":"985112345678901","name":"Milo","species":"Dog","breed":"Lab Mix"}'

# 2. Push medical events (clear-and-replace)
curl -X POST https://furballregistry.com/api/animals/985112345678901/events \
  -H "Authorization: Bearer freg_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"eventType":"Vaccination","eventName":"Rabies","eventStatus":"CompletedOn","eventDate":"2026-04-03"}]}'

# 3. Read the timeline
curl https://furballregistry.com/api/animals/985112345678901 \
  -H "Authorization: Bearer freg_your_key_here"

Support

Questions? Contact us at support@furballrescue.com.