Developers

Integrate with TailRegister

Any software can read programme data through the TailRegister API: a state dashboard, another department’s system, an NGO app or a data warehouse. The interface is read-only, described in OpenAPI 3.0, and versioned under /v1.

Download openapi.json API reference

Getting access

Programme data belongs to the organisation that runs the programme, for example a state’s animal husbandry department. Its administrator creates an access key for your system in the TailRegister console under Integration, and can revoke it at any time. Every use of a key is recorded in the audit trail. Ask the organisation you are working with for a key; for anything else, write to anand@blutek.consulting.

Send the key in the X-API-Key header on every request.
A key reads every unit of its organisation. It cannot change records and cannot read staff details.
Times are ISO 8601 in UTC; dates are YYYY-MM-DD. Errors return JSON with a message and the HTTP status (401 bad key, 403 not permitted, 404 not found).
The collar status endpoint is public and needs no key.

Live sandbox: coming soon. A demonstration organisation with sample data and a published key, so you can try every call from this page.

Quick start

Programme totals

Totals, daily activity and a breakdown by unit for the whole organisation.

curl

curl -H "X-API-Key: $TAILREGISTER_KEY" https://tailregister.com/v1/stats/summary

JavaScript

const res = await fetch('https://tailregister.com/v1/stats/summary', {
  headers: { 'X-API-Key': process.env.TAILREGISTER_KEY },
})
const summary = await res.json()

Python

import os, requests
r = requests.get("https://tailregister.com/v1/stats/summary",
                 headers={"X-API-Key": os.environ["TAILREGISTER_KEY"]})
summary = r.json()

Find a dog by collar or microchip

Pass a collar code, the scanned collar URL, or a 15-digit microchip number.

curl

curl -G -H "X-API-Key: $TAILREGISTER_KEY" --data-urlencode "code=900215000123456" https://tailregister.com/v1/dogs/lookup

JavaScript

const url = new URL('https://tailregister.com/v1/dogs/lookup')
url.searchParams.set('code', '900215000123456')
const { dog } = await (await fetch(url, { headers: { 'X-API-Key': process.env.TAILREGISTER_KEY } })).json()

Python

r = requests.get("https://tailregister.com/v1/dogs/lookup", params={"code": "900215000123456"},
                 headers={"X-API-Key": os.environ["TAILREGISTER_KEY"]})
dog = r.json()["dog"]

Keep your own database in step

Start at cursor 0 and follow the returned cursor while has_more is true. Afterwards, poll with the last cursor to receive only what changed.

curl

curl -H "X-API-Key: $TAILREGISTER_KEY" "https://tailregister.com/v1/sync/pull?cursor=0&limit=500"

JavaScript

let cursor = 0, hasMore = true
while (hasMore) {
  const res = await fetch(`https://tailregister.com/v1/sync/pull?cursor=${cursor}&limit=500`, {
    headers: { 'X-API-Key': process.env.TAILREGISTER_KEY },
  })
  const page = await res.json()
  save(page)                       // your code: upsert dogs, events and photos
  cursor = page.cursor; hasMore = page.has_more
}

Python

cursor, has_more = 0, True
while has_more:
    page = requests.get("https://tailregister.com/v1/sync/pull", params={"cursor": cursor, "limit": 500},
                        headers={"X-API-Key": os.environ["TAILREGISTER_KEY"]}).json()
    save(page)                     # your code: upsert dogs, events and photos
    cursor, has_more = page["cursor"], page["has_more"]

Public collar status (no key)

What a citizen sees after scanning a collar: sterilisation and vaccination only.

curl

curl https://tailregister.com/v1/public/tags/TN-00BRRAEV

JavaScript

const tag = await (await fetch('https://tailregister.com/v1/public/tags/TN-00BRRAEV')).json()

Python

tag = requests.get("https://tailregister.com/v1/public/tags/TN-00BRRAEV").json()

API reference

GET `/v1/dogs`

List dogs.

Parameter	In	Type	Description
`q`	query	string	Collar code, part of a microchip number, or part of the capture address
`status`	query	string	registered, captured, in_centre, released, adopted or dead
`sex`	query	string	male, female or unknown
`org_unit_id`	query	string	Limit to this unit and everything beneath it
`care`	query	string	sterilised, not_sterilised, vaccinated or booster_overdue
`limit`	query	integer	1–200, default 50
`offset`	query	integer	Rows to skip

Responses

200 A page of dogs and the total matching

application/json DogList

401 Missing, invalid or revoked key

application/json Error

403 Not permitted, account suspended, or integration not licensed

application/json Error

GET `/v1/dogs/lookup`

Find one dog by collar code, collar URL or microchip number.

Parameter	In	Type	Description
`code` required	query	string	Collar code, scanned URL or 15-digit microchip number

Responses

200 The dog

application/json

dog: Dog

401 Missing, invalid or revoked key

application/json Error

403 Not permitted, account suspended, or integration not licensed

application/json Error

404 No dog carries that code

application/json Error

GET `/v1/dogs/points`

Capture positions for mapping.

Parameter	In	Type	Description
`q`	query	string	Collar code, part of a microchip number, or part of the capture address
`status`	query	string	registered, captured, in_centre, released, adopted or dead
`sex`	query	string	male, female or unknown
`org_unit_id`	query	string	Limit to this unit and everything beneath it
`care`	query	string	sterilised, not_sterilised, vaccinated or booster_overdue

Responses

200 Positions

application/json array of DogPoint

401 Missing, invalid or revoked key

application/json Error

403 Not permitted, account suspended, or integration not licensed

application/json Error

GET `/v1/dogs/{id}`

One dog with its full history and photo list.

Parameter	In	Type	Description
`id` required	path	string	Dog id

Responses

200 Dog, events and photos

application/json DogDetail

401 Missing, invalid or revoked key

application/json Error

403 Not permitted, account suspended, or integration not licensed

application/json Error

404 Not found

application/json Error

GET `/v1/photos/{id}/file`

Download a photograph.

Parameter	In	Type	Description
`id` required	path	string	Photo id from the dog record

Responses

200 The image

image/jpeg string

401 Missing, invalid or revoked key

application/json Error

403 Not permitted, account suspended, or integration not licensed

application/json Error

GET `/v1/stats/summary`

Programme totals, daily activity and a breakdown by unit.

Parameter	In	Type	Description
`org_unit_id`	query	string	Unit to summarise; default is the whole organisation
`from`	query	string	First day of the daily series
`to`	query	string	Last day of the daily series

Responses

200 Summary

application/json StatsSummary

401 Missing, invalid or revoked key

application/json Error

403 Not permitted, account suspended, or integration not licensed

application/json Error

GET `/v1/org-units`

Organisation units (state, districts, local bodies, centres).

Responses

200 Units ordered so that parents precede children

application/json array of OrgUnit

401 Missing, invalid or revoked key

application/json Error

403 Not permitted, account suspended, or integration not licensed

application/json Error

GET `/v1/sync/pull`

Incremental feed of every change since a cursor.

Start with cursor 0 and repeat with the returned cursor while `has_more` is true; afterwards poll with the last cursor to receive only what changed.

Parameter	In	Type	Description
`cursor`	query	integer	Cursor from the previous call; 0 to start
`limit`	query	integer	1–1000, default 500

Responses

200 Changed dogs, events and photos

application/json PullResponse

401 Missing, invalid or revoked key

application/json Error

403 Not permitted, account suspended, or integration not licensed

application/json Error

GET `/v1/export/dogs.csv`

Dog register as CSV.

Parameter	In	Type	Description
`q`	query	string	Collar code, part of a microchip number, or part of the capture address
`status`	query	string	registered, captured, in_centre, released, adopted or dead
`sex`	query	string	male, female or unknown
`org_unit_id`	query	string	Limit to this unit and everything beneath it
`care`	query	string	sterilised, not_sterilised, vaccinated or booster_overdue

Responses

200 CSV, UTF-8

text/csv string

401 Missing, invalid or revoked key

application/json Error

403 Not permitted, account suspended, or integration not licensed

application/json Error

GET `/v1/export/events.csv`

Events in a period as CSV.

Parameter	In	Type	Description
`from` required	query	string	First day
`to` required	query	string	Last day
`org_unit_id`	query	string	Limit to a unit

Responses

200 CSV, UTF-8

text/csv string

401 Missing, invalid or revoked key

application/json Error

403 Not permitted, account suspended, or integration not licensed

application/json Error

GET `/v1/public/tags/{code}`

Public status of a collar (no key needed). No key needed.

Parameter	In	Type	Description
`code` required	path	string	Collar code

Responses

200 Sterilisation and vaccination status only

application/json PublicTag

404 Unknown code

application/json Error

Schemas

`Dog`

idrequired: string
qr_coderequired: string | null
chip_norequired: string | null
sexrequired: string one of male female unknown
age_grouprequired: string | null one of puppy young adult old
colourrequired: string | null
markingsrequired: string | null
weight_kgrequired: number | null
org_unit_idrequired: string
statusrequired: string one of registered captured in_centre released adopted dead
captured_atrequired: string | null
sterilised_atrequired: string | null
last_vaccinated_atrequired: string | null
vaccination_due_onrequired: string | null
released_atrequired: string | null
latrequired: number | null
lngrequired: number | null
addressrequired: string | null
created_atrequired: string
updated_atrequired: string
revrequired: number

`DogList`

itemsrequired

array of

idrequired: string
qr_coderequired: string | null
chip_norequired: string | null
sexrequired: string one of male female unknown
age_grouprequired: string | null one of puppy young adult old
colourrequired: string | null
markingsrequired: string | null
weight_kgrequired: number | null
org_unit_idrequired: string
statusrequired: string one of registered captured in_centre released adopted dead
captured_atrequired: string | null
sterilised_atrequired: string | null
last_vaccinated_atrequired: string | null
vaccination_due_onrequired: string | null
released_atrequired: string | null
latrequired: number | null
lngrequired: number | null
addressrequired: string | null
created_atrequired: string
updated_atrequired: string
revrequired: number
org_unit_namerequired: string
photo_idrequired: string | null

totalrequired

number

`DogDetail`

dogrequired

idrequired: string
qr_coderequired: string | null
chip_norequired: string | null
sexrequired: string one of male female unknown
age_grouprequired: string | null one of puppy young adult old
colourrequired: string | null
markingsrequired: string | null
weight_kgrequired: number | null
org_unit_idrequired: string
statusrequired: string one of registered captured in_centre released adopted dead
captured_atrequired: string | null
sterilised_atrequired: string | null
last_vaccinated_atrequired: string | null
vaccination_due_onrequired: string | null
released_atrequired: string | null
latrequired: number | null
lngrequired: number | null
addressrequired: string | null
created_atrequired: string
updated_atrequired: string
revrequired: number

eventsrequired

array of

idrequired: string
dog_idrequired: string
typerequired: string one of capture intake surgery tagging vaccination postop_check release adoption death resight
occurred_atrequired: string
recorded_atrequired: string
latrequired: number | null
lngrequired: number | null
accuracy_mrequired: number | null
addressrequired: string | null
org_unit_idrequired: string
user_idrequired: string
user_name: string
device_idrequired: string | null
datarequired: object
revrequired: number

photosrequired

array of

idrequired: string
dog_idrequired: string
event_idrequired: string | null
mimerequired: string
bytesrequired: number
taken_atrequired: string
revrequired: number

`DogPoint`

idrequired: string
latrequired: number
lngrequired: number
statusrequired: string one of registered captured in_centre released adopted dead
sexrequired: string one of male female unknown

`OrgUnit`

idrequired: string
parent_idrequired: string | null
typerequired: string one of state district local_body centre
namerequired: string
coderequired: string | null
pathrequired: string

`StatsSummary`

totalsrequired

registeredrequired: number
sterilisedrequired: number
vaccinatedrequired: number
releasedrequired: number
in_centrerequired: number
adoptedrequired: number
deadrequired: number
vaccination_overduerequired: number

by_sexrequired

malerequired: number
femalerequired: number
unknownrequired: number

dailyrequired

array of

daterequired: string
capturerequired: number
surgeryrequired: number
vaccinationrequired: number
releaserequired: number

by_unitrequired

array of

org_unit_idrequired: string
namerequired: string
typerequired: string one of state district local_body centre
registeredrequired: number
sterilisedrequired: number
vaccinatedrequired: number
releasedrequired: number

`PullResponse`

dogsrequired

array of

idrequired: string
qr_coderequired: string | null
chip_norequired: string | null
sexrequired: string one of male female unknown
age_grouprequired: string | null one of puppy young adult old
colourrequired: string | null
markingsrequired: string | null
weight_kgrequired: number | null
org_unit_idrequired: string
statusrequired: string one of registered captured in_centre released adopted dead
captured_atrequired: string | null
sterilised_atrequired: string | null
last_vaccinated_atrequired: string | null
vaccination_due_onrequired: string | null
released_atrequired: string | null
latrequired: number | null
lngrequired: number | null
addressrequired: string | null
created_atrequired: string
updated_atrequired: string
revrequired: number

eventsrequired

array of

idrequired: string
dog_idrequired: string
typerequired: string one of capture intake surgery tagging vaccination postop_check release adoption death resight
occurred_atrequired: string
recorded_atrequired: string
latrequired: number | null
lngrequired: number | null
accuracy_mrequired: number | null
addressrequired: string | null
org_unit_idrequired: string
user_idrequired: string
user_name: string
device_idrequired: string | null
datarequired: object
revrequired: number

photosrequired

array of

idrequired: string
dog_idrequired: string
event_idrequired: string | null
mimerequired: string
bytesrequired: number
taken_atrequired: string
revrequired: number

cursorrequired

number

has_morerequired

boolean

`PublicTag`

coderequired: string
organisationrequired: string
registeredrequired: boolean
sex: string one of male female unknown
status: string one of registered captured in_centre released adopted dead
sterilised_on: string | null
vaccinated_on: string | null
vaccination_due_on: string | null

`Error`

errorrequired: string
messagerequired: string

Integrate with TailRegister

Getting access

Quick start

Programme totals

Find a dog by collar or microchip

Keep your own database in step

Public collar status (no key)

API reference

GET /v1/dogs

GET /v1/dogs/lookup

GET /v1/dogs/points

GET /v1/dogs/{id}

GET /v1/photos/{id}/file

GET /v1/stats/summary

GET /v1/org-units

GET /v1/sync/pull

GET /v1/export/dogs.csv

GET /v1/export/events.csv

GET /v1/public/tags/{code}

Schemas

Dog

DogList

DogDetail

DogPoint

OrgUnit

StatsSummary

PullResponse

PublicTag

Error

GET `/v1/dogs`

GET `/v1/dogs/lookup`

GET `/v1/dogs/points`

GET `/v1/dogs/{id}`

GET `/v1/photos/{id}/file`

GET `/v1/stats/summary`

GET `/v1/org-units`

GET `/v1/sync/pull`

GET `/v1/export/dogs.csv`

GET `/v1/export/events.csv`

GET `/v1/public/tags/{code}`

`Dog`

`DogList`

`DogDetail`

`DogPoint`

`OrgUnit`

`StatsSummary`

`PullResponse`

`PublicTag`

`Error`