Metody API

Dokumentacja Partner API

Ten przewodnik opisuje, jak Twoja integracja komunikuje się z Animal-ID w imieniu Twojej organizacji: uwierzytelnianie, wymagane nagłówki i podstawowe endpointy MVP (właściciele, zwierzęta, procedury, zdjęcia, słowniki).

SDK i biblioteki klienckie

Oficjalne SDK open-source, które opakowują podpisywanie żądań i opisane niżej punkty końcowe — podłącz je zamiast podpisywać żądania ręcznie.

PHP · Composer

Serwerowe SDK dla PHP: podpisywanie żądań HMAC i typowane klienty dla każdego punktu końcowego.

composer require animal-id/aid-partner-sdk

Zobacz na GitHubie

JavaScript · npm

Pakiety dla frameworków w Node i w przeglądarce, zbudowane na wspólnym rdzeniu.

npm i @animal-id/partner-core

@animal-id/partner-coreFramework-agnostic core: signing + typed client.
@animal-id/partner-reactReact hooks & helpers.
@animal-id/partner-vueVue composables.
@animal-id/partner-angularAngular services.
@animal-id/partner-nestjsNestJS module for server-side integrations.

Uwierzytelnianie i podpisywanie żądań

Base URL: https://gw.animal-id.net · all paths are prefixed with /v1/partner.

Every signed request carries four headers. The signature is an HMAC-SHA256 (hex) of a canonical string, keyed with your private key:

stringToSign = METHOD + "\n" + path[?query] + "\n" + sha256_hex(rawBody) + "\n" + timestamp
signature    = hex( hmac_sha256(stringToSign, privateKey) )

Header	Value
`X-Eternity-App-Id`	Your application id.
`X-Eternity-Public-Key`	Your public key.
`X-Eternity-Timestamp`	Unix seconds; must be within ±300s of server time.
`X-Eternity-Signature`	The HMAC-SHA256 hex computed above.
`X-Eternity-Idempotency-Key`	UUID, required on every POST/PATCH/DELETE. Replays return the first response; same key + different body → 409.
`X-Eternity-Animal-ID-Version`	Optional date version (YYYY-MM-DD). Defaults to the version locked when your app was issued; from 2026-07-04, animal registration attaches existing owners by public_id instead of user_gid.
`X-Eternity-Expand`	Optional. JSON array of expand keys to embed extra data on supported endpoints (e.g. `["owners"]`). See an endpoint's “Expansion” section for its allowed keys; unknown keys → 422.
`X-Eternity-Lang-Code`	Opcjonalny. Kod języka (`uk`, `en`, `ru`, `de`, `es`) dla nazw zwracanych przez API — np. `species_name` i `breed_name` na karcie zwierzęcia oraz etykiety w słownikach. Jeśli pominięty, używany jest domyślny język regionu.

Sign and send the exact same body bytes. For GET/DELETE the body is empty (its sha256 is the hash of an empty string). path includes the query string when present. For multipart/form-data uploads (photos) the raw body is not part of the signature either — sign with the sha256 of an empty body.

Every successful response wraps results in a payload array. Single-resource create/get endpoints return a one-element array (e.g. { "payload": [ { … } ] }); the per-endpoint examples below show the single object for brevity.

curl

Node.js

Python

PHP

APP_ID="aid_app_xxx"; PUBLIC_KEY="pk_xxx"; PRIVATE_KEY="sk_xxx"
METHOD="POST"
PATH_Q="/v1/partner/owners"                       # path (+ "?query" if any), exactly as sent
BODY='{"email":"jane@example.com","consent":{"account_creation":true}}'
TS=$(date +%s)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | awk '{print $2}')
STRING_TO_SIGN=$(printf '%s\n%s\n%s\n%s' "$METHOD" "$PATH_Q" "$BODY_HASH" "$TS")
SIG=$(printf '%s' "$STRING_TO_SIGN" | openssl dgst -sha256 -hmac "$PRIVATE_KEY" | awk '{print $2}')

curl -X "$METHOD" "https://gw.animal-id.net$PATH_Q" \
  -H "X-Eternity-App-Id: $APP_ID" \
  -H "X-Eternity-Public-Key: $PUBLIC_KEY" \
  -H "X-Eternity-Timestamp: $TS" \
  -H "X-Eternity-Signature: $SIG" \
  -H "X-Eternity-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "$BODY"

const crypto = require('crypto');

function sign({ method, pathQ, body = '', privateKey }) {
  const ts = Math.floor(Date.now() / 1000).toString();
  const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
  const stringToSign = [method, pathQ, bodyHash, ts].join('\n');
  const signature = crypto.createHmac('sha256', privateKey).update(stringToSign).digest('hex');
  return { ts, signature };
}

const body = JSON.stringify({ email: 'jane@example.com' });
const { ts, signature } = sign({ method: 'POST', pathQ: '/v1/partner/owners', body, privateKey: 'sk_xxx' });

await fetch('https://gw.animal-id.net/v1/partner/owners', {
  method: 'POST',
  headers: {
    'X-Eternity-App-Id': 'aid_app_xxx',
    'X-Eternity-Public-Key': 'pk_xxx',
    'X-Eternity-Timestamp': ts,
    'X-Eternity-Signature': signature,
    'X-Eternity-Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body, // sign and send the SAME bytes
});

import hashlib, hmac, time, json, uuid, requests

def sign(method, path_q, body, private_key):
    ts = str(int(time.time()))
    body_hash = hashlib.sha256(body.encode()).hexdigest()
    string_to_sign = "\n".join([method, path_q, body_hash, ts])
    signature = hmac.new(private_key.encode(), string_to_sign.encode(), hashlib.sha256).hexdigest()
    return ts, signature

body = json.dumps({"email": "jane@example.com"}, separators=(",", ":"))
ts, signature = sign("POST", "/v1/partner/owners", body, "sk_xxx")

requests.post(
    "https://gw.animal-id.net/v1/partner/owners",
    data=body,  # send the SAME bytes you signed
    headers={
        "X-Eternity-App-Id": "aid_app_xxx",
        "X-Eternity-Public-Key": "pk_xxx",
        "X-Eternity-Timestamp": ts,
        "X-Eternity-Signature": signature,
        "X-Eternity-Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
)

<?php
function signRequest(string $method, string $pathQ, string $body, string $privateKey): array {
    $ts = (string) time();
    $bodyHash = hash('sha256', $body);
    $stringToSign = implode("\n", [$method, $pathQ, $bodyHash, $ts]);
    $signature = hash_hmac('sha256', $stringToSign, $privateKey);
    return [$ts, $signature];
}

$body = json_encode(['email' => 'jane@example.com']);
[$ts, $signature] = signRequest('POST', '/v1/partner/owners', $body, 'sk_xxx');

$ch = curl_init('https://gw.animal-id.net/v1/partner/owners');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body, // send the SAME bytes you signed
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-Eternity-App-Id: aid_app_xxx",
        "X-Eternity-Public-Key: pk_xxx",
        "X-Eternity-Timestamp: $ts",
        "X-Eternity-Signature: $signature",
        'X-Eternity-Idempotency-Key: ' . bin2hex(random_bytes(16)),
        'Content-Type: application/json',
    ],
]);
$response = curl_exec($ch);

Webhooki

Odbieraj odroczone zdarzenia — na przykład zgodę właściciela na wniosek weterynarza o dostęp — jako podpisane żądania POST na Twój serwer. Adres URL ustawisz, a sekret podpisu znajdziesz na karcie kluczy API.

POSTSigned webhook deliveryWebhook signature & payload▸

We POST every event to your configured webhook URL, signed with your per-app webhook secret (shown once when generated). Verify the signature before trusting a delivery by recomputing the HMAC over the canonical string and comparing in constant time:

canonical = "POST" + "\n" + path[?query] + "\n" + sha256_hex(rawBody) + "\n" + timestamp
signature = hex( hmac_sha256(canonical, webhookSecret) )

Header	Value
`X-Eternity-Webhook-Id`	Unique delivery id (UUID); stable across resends of the same event.
`X-Eternity-Webhook-Event`	The event key, e.g. animal_access.approved.
`X-Eternity-Webhook-Timestamp`	Unix seconds when the delivery was signed; reject deliveries with a skewed timestamp.
`X-Eternity-Webhook-Signature`	HMAC-SHA256 hex of the canonical string, keyed with your webhook secret (not your API private key).

Delivery body (JSON)

{
  "id": "5f1c0b8e-3a2d-4c7b-9b1a-2e6f0d4c8a91",
  "event": "animal_access.approved",
  "occurred_at": "2026-06-24T09:15:00+00:00",
  "result": {
    "animal_id": "8xK3pQzVnB7rL2qF",
    "requester_user_gid": 90231,
    "status": "granted",
    "requested_at": "2026-06-23T09:00:00+00:00",
    "expires_at": "2026-06-30T09:00:00+00:00",
    "retry_after_seconds": 0,
    "decided_at": "2026-06-24T09:15:00+00:00"
  }
}

Field	Description
`id`	The unique event id (matches the X-Eternity-Webhook-Id header).
`event`	The event key, e.g. animal_access.approved.
`occurred_at`	When the event occurred (ISO 8601).
`result`	The access decision. Mirrors GET /v1/partner/animals/{id}/access-request and adds animal_id, requester_user_gid and decided_at.

Events

Key	Meaning
`animal_access.approved`	An owner approved your pending access request — you may now edit the animal.
`animal_access.denied`	An owner denied your access request — you can request again after it expires.
`consent.approved`	Osoba, którą zapytałeś, wyraziła zgodę — możesz korzystać z uprawnienia, dopóki nie wygaśnie.
`consent.denied`	Osoba, którą zapytałeś, odrzuciła wniosek. Nic nie zostało przyznane.
`consent.revoked`	Przyznane Ci uprawnienie zostało cofnięte. W przypadku przekazanego klucza przestaje on działać natychmiast.
`consent.expired`	Nikt nie odpowiedział na czas i wniosek stracił ważność. To nie jest odmowa — możesz zapytać ponownie.

Treść zdarzenia o zgodzie

Zdarzenia o zgodzie są dostarczane do Twojej aplikacji platformy, a nie do organizacji: gdy lekarz pozwala Ci trzymać dane dostępowe działające w jego imieniu, żadna przychodnia nie bierze w tym udziału.

{
  "id": "282824f1-b65e-40f4-86d1-62a2bac566df",
  "event": "consent.revoked",
  "occurred_at": "2026-08-26T19:45:00+00:00",
  "result": {
    "consent_id": "qeHSuvlSZHAWpacF",
    "kind": "key_handover",
    "status": "revoked",
    "doctor_id": "c71ORqKq81fRoTcm",
    "clinic_id": null,
    "decided_at": "2026-08-26T19:45:00+00:00"
  }
}

Field	Description
`consent_id`	Wniosek, którego dotyczy ta decyzja — ten sam identyfikator, który zwróciło wywołanie provisioningu.
`kind`	key_handover (dane dostępowe działające w imieniu lekarza) lub clinic_membership (dodanie lekarza do przychodni).
`status`	approved, denied, revoked lub expired.
`doctor_id`	Publiczny identyfikator lekarza — przy przekazaniu klucza. W przeciwnym razie null; także null, jeśli konto zostało od tego czasu usunięte.
`clinic_id`	Publiczny identyfikator przychodni — przy członkostwie w przychodni. W przeciwnym razie null.
`decided_at`	Kiedy nastąpił ten stan (ISO 8601). Przy wygaśnięciu jest to termin końcowy, a nie moment, w którym to zauważyliśmy.

Obsługuj consent.revoked. Uprawnienie można cofnąć w dowolnej chwili, a przekazany klucz przestaje wtedy działać natychmiast — bez tego zdarzenia dowiedziałbyś się o tym dopiero wtedy, gdy kolejne wywołanie zakończy się błędem.

Acknowledge with any 2xx response. A non-2xx status or a timeout is recorded as a failed delivery, which you can resend from the webhook delivery log in your cabinet.

Node.js

PHP

const crypto = require('crypto');

// Express: mount with a raw-body parser so you verify the EXACT bytes received.
// app.post('/animal-id/webhook', express.raw({ type: 'application/json' }), handler)
function verify(req, webhookSecret) {
  const ts   = req.header('X-Eternity-Webhook-Timestamp');
  const sig  = req.header('X-Eternity-Webhook-Signature');
  const path = req.originalUrl;                 // path (+ ?query) exactly as received
  const raw  = req.body;                        // Buffer of the raw request body
  const bodyHash = crypto.createHash('sha256').update(raw).digest('hex');
  const canonical = ['POST', path, bodyHash, ts].join('\n');
  const expected = crypto.createHmac('sha256', webhookSecret).update(canonical).digest('hex');
  return sig && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

<?php
// Verify a webhook delivery from Animal ID before trusting it.
function verifyWebhook(string $rawBody, string $path, string $webhookSecret): bool {
    $ts  = $_SERVER['HTTP_X_ETERNITY_WEBHOOK_TIMESTAMP'] ?? '';
    $sig = $_SERVER['HTTP_X_ETERNITY_WEBHOOK_SIGNATURE'] ?? '';
    $canonical = implode("\n", ['POST', $path, hash('sha256', $rawBody), $ts]);
    $expected = hash_hmac('sha256', $canonical, $webhookSecret);
    return $sig !== '' && hash_equals($expected, $sig);
}

$rawBody = file_get_contents('php://input');     // verify the EXACT bytes received
if (!verifyWebhook($rawBody, $_SERVER['REQUEST_URI'], getenv('AID_WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit;
}
$event = json_decode($rawBody, true);            // ['id' => …, 'event' => …, 'result' => …]
http_response_code(204);                         // acknowledge with any 2xx

Metody API

Zacznij pisać — sekcje filtrują się według słów kluczowych.

Platform API — zakładanie kont

Zakładanie przychodni i lekarzy oraz proszenie ludzi o zgodę, której nie da się wziąć samemu. Od tego zaczyna się integracja: najpierw tworzysz konta, a potem odbierasz dane dostępowe, którymi będziesz z nimi pracować.

Podpisywane Twoim kluczem platformy, wydawanym jednorazowo przy zakładaniu konta partnera. W nagłówku X-Eternity-App-Id wysyłaj uuid aplikacji platformy.
Do danych zwierząt nie sięga nigdy. Klucz platformy na ścieżce /v1/partner/ zwróci 401 — to działa rozdzielenie, a nie błąd konfiguracji.

Provisioning

GET/v1/platform/organizationsZnajdź już istniejącą przychodnię, zanim utworzysz nową.▸

Auth: HMAC with your PLATFORM key.

Request fields

Field	Req.	Type	Dictionary	Description
`query`	yes	string	—	Name or address fragment, at least 2 characters.
`limit`	no	int	—	Maximum results, up to 50 (default 20).

Example response

{
  "payload": [
    {
      "public_id": "TGo1Gwe2ppRkUFO1",
      "org_name": "Лапа",
      "full_address": "Україна, Київ, вул. Прикладна, 1",
      "status": 3,
      "linked": false
    }
  ]
}

Field	Description
`public_id`	Pass it to the member endpoint to seat a doctor here.
`status`	Moderation status. A clinic you provisioned stays out of the public directory until its director claims it.
`linked`	true when this clinic is one you provisioned yourself.

Response statuses

Status	Meaning
`200`	Matches (an empty list when nothing matches).
`422`	Validation error (query missing or shorter than 2 characters).

POST/v1/platform/organizationsUtwórz przychodnię lub znajdź już istniejącą po własnym identyfikatorze.▸

Auth: HMAC with your PLATFORM key. Issued separately from clinic keys; it never reaches animal data.

Request fields

Field	Req.	Type	Dictionary	Description
`external_org_id`	yes	string	—	Your own identifier for this clinic. A repeat call with the same value returns the clinic you already have instead of creating another, so send a stable value.
`name`	yes	string	—	Clinic name.
`director_public_id`	yes	string	—	The doctor who takes the director seat, by their public_id (from POST /owners or the member endpoint below). A clinic cannot exist without a director, and a doctor may direct only one clinic — naming someone who already directs elsewhere is answered with 409.
`email`	no	string	—	Contact email.
`phone`	no	string	—	Contact phone (E.164).
`website`	no	string	—	Website.
`address`	no	string	—	Full address.
`country_id`	no	int	`countries`	Country dictionary id.
`description`	no	string	—	Free-text description.
`lat`	no	number	—	Latitude.
`lng`	no	number	—	Longitude.

Request body (JSON)

{
  "external_org_id": "crm-clinic-118",
  "name": "Лапа",
  "director_public_id": "V1StGXR8Z5jd",
  "email": "clinic@example.com",
  "phone": "+380441234567"
}

Example response

{
  "payload": {
    "public_id": "yAvgJrSYehJo9JXh",
    "name": "Лапа",
    "status": 2,
    "created": true
  }
}

Field	Description
`public_id`	Stable public clinic identifier — pass it into the member endpoint below.
`created`	true when this call created the clinic; false when it resolved the one you already had.
`status`	Moderation status. A provisioned clinic stays out of the public catalogue until its director claims it.

Response statuses

Status	Meaning
`201`	Clinic created.
`200`	Clinic already existed for this external_org_id — same clinic returned.
`409`	The named director already directs another clinic. Name a different doctor.
`422`	Validation error (missing external_org_id, name or director_public_id).

POST/v1/platform/organizations/{clinic_public_id}/membersUmieść lekarza w przychodni i odbierz jego dane dostępowe.▸

Auth: HMAC with your PLATFORM key.

Request fields

Field	Req.	Type	Dictionary	Description
`email`	conditional	string	—	Doctor's email. One of email/phone is required.
`phone`	conditional	string	—	Doctor's phone (E.164). One of email/phone is required.
`first_name`	no	string	—	Given name.
`last_name`	no	string	—	Family name.
`language`	no	string	`languages`	Preferred locale.
`clinic_name`	no	string	—	Label shown on the issued credentials.
`external_doctor_id`	no	string	—	Your own identifier for this doctor. Same field and same rules as external_owner_id: written once, never overwritten, and only ever visible to you.
`consent`	yes	object	—	Consent block (immutable audit).
`consent.account_creation`	yes	bool	—	Must be true. The credentials you receive act as this person, so their agreement is required.

Request body (JSON)

{
  "email": "doctor@example.com",
  "first_name": "Ihor",
  "last_name": "Melnyk",
  "language": "uk",
  "external_doctor_id": "crm-doc-4471",
  "consent": { "account_creation": true }
}

Example response

{
  "payload": {
    "public_id": "LSG9w6B2rwAiPoJD",
    "app_id": "4833d2e5-1a97-4572-ac5d-a03c7614e0d7",
    "public_key": "94af0494...",
    "private_key": "b208c6e0...",
    "created": true
  }
}

Field	Description
`app_id`	App-Id this doctor signs data-plane calls with (X-Eternity-App-Id).
`public_key`	Public half of the doctor's key pair.
`private_key`	Private half. Shown in this response and never again — store it before you close the connection.
`public_id`	The doctor's stable public identifier — use it wherever an owner or director is named.
`created`	true when the account was created by this call; false when the doctor already had one and was matched.

Response statuses

Status	Meaning
`201`	Doctor seated; credentials returned.
`409`	This doctor already holds a key for this clinic, or the clinic is not one you provisioned and its director has not approved you — raise a clinic_membership consent first.
`422`	Validation error (no email/phone, or consent.account_creation not accepted).

Consent

POST/v1/platform/organizations/{clinic_public_id}/members/{doctor_public_id}/credentialsOdbierz dane dostępowe działające w imieniu lekarza, który się na to zgodził.▸

Auth: HMAC with your PLATFORM key.

Example response

{
  "payload": {
    "public_id": "LSG9w6B2rwAiPoJD",
    "app_id": "dcd4895e-550e-424a-9c5d-5206cbce2956",
    "public_key": "11fff5d1...",
    "private_key": "00604b9b...",
    "created": false
  }
}

Field	Description
`private_key`	Shown once and never again. The key is held by you and is separate from the doctor's own — when they withdraw consent yours stops working and theirs does not.

Response statuses

Status	Meaning
`201`	Credentials issued.
`409`	The doctor has not agreed to the handover, or the clinic is not one you may act on. The message names which.

POST/v1/platform/consentsPoproś lekarza lub przychodnię o zgodę.▸

Auth: HMAC with your PLATFORM key.

Request fields

Field	Req.	Type	Dictionary	Description
`kind`	yes	string	—	key_handover — hold credentials that act as this doctor, which only the doctor can allow. clinic_membership — seat this doctor in a clinic you did not provision, which its director decides.
`doctor_public_id`	yes	string	—	The doctor the request concerns.
`clinic_public_id`	conditional	string	—	Required for clinic_membership: the clinic whose director you are asking.

Request body (JSON)

{
  "kind": "clinic_membership",
  "doctor_public_id": "LSG9w6B2rwAiPoJD",
  "clinic_public_id": "jJlmHf0sgxMT3Gni"
}

Example response

{
  "payload": {
    "public_id": "5G5rBYl0hQvpJuCZ",
    "kind": "clinic_membership",
    "status": "pending",
    "expires_at": 1788973565,
    "decided_at": null
  }
}

Field	Description
`public_id`	Poll the status endpoint with this.
`status`	pending until the person answers, then approved or denied.
`expires_at`	Unix seconds. An unanswered request closes itself, and an approval stops working at the same moment — permission is not permanent.

Response statuses

Status	Meaning
`201`	Request raised, or the one you already had returned — asking twice does not create two.
`409`	Nobody can decide this (for example, a clinic with no director).
`422`	Validation error (unknown kind, or clinic_public_id missing for clinic_membership).

GET/v1/platform/consents/{public_id}Sprawdź, na jakim etapie jest wniosek o zgodę.▸

Auth: HMAC with your PLATFORM key.

Example response

{
  "payload": {
    "public_id": "5G5rBYl0hQvpJuCZ",
    "kind": "clinic_membership",
    "status": "approved",
    "expires_at": 1788973565,
    "decided_at": 1787763211
  }
}

Response statuses

Status	Meaning
`200`	Current state.
`404`	No such request, or it belongs to another partner.

Partner API — dane

Zwierzęta, właściciele, procedury i zdjęcia — codzienna powierzchnia pracy. Każdy zapis jest tu odnotowywany w imieniu lekarza, którego kluczem został podpisany.

Podpisywane kluczem lekarza, zwracanym jednorazowo — gdy umieszczasz go w przychodni albo odbierasz jego dane dostępowe po wyrażeniu zgody. W nagłówku X-Eternity-App-Id wysyłaj uuid aplikacji tego lekarza.
Nie może niczego zakładać i przestaje działać w chwili, gdy lekarz cofnie zgodę. Słowniki nie wymagają podpisu w ogóle.

Dictionaries

GET/v1/partner/dictionariesSłowniki referencyjne (wielojęzyczne, z filtrowaniem).▸

Auth: Public (no signature required). CDN-cacheable via ETag.

Request fields

Field	Req.	Type	Dictionary	Description
`include`	no	string (csv)	—	Comma-separated dictionary keys to return; empty → all. Keys: species, pet_species_featured, sex, sizes, lost_statuses, other_identifiers, procedure_types, countries, languages, cites. `pet_species_featured` is the canonical popular-species list keyed by a UUID public_id — pass its code into POST /animals as species_public_id.
`q`	no	string	—	Filter entries by localized name in any active language.
`lang`	no	string	`languages`	Project names to a single locale (uk, en, ru, de, es). Default: all active.

Example response

{
  "payload": [
    {
      "key": "species",
      "items": [
        { "code": 3, "names": { "uk": "Собаки", "en": "Dogs", "ru": "Собаки", "de": "Dogs" } },
        { "code": 4, "names": { "uk": "Коти", "en": "Cats" } }
      ]
    },
    {
      "key": "pet_species_featured",
      "items": [
        { "code": "1b289672-0a74-48d2-9600-7104bedacd8c", "names": { "uk": "Собака", "en": "Dog" } },
        { "code": "b0dd3c3a-4d35-4479-91f9-616ae072c400", "names": { "uk": "Домашні коти", "en": "Domestic cats" } }
      ]
    },
    {
      "key": "countries",
      "items": [
        { "code": "804", "alpha2": "UA", "alpha3": "UKR",
          "names": { "uk": "Україна", "en": "Ukraine", "ru": "Украина", "de": "Ukraine", "es": "Ukraine" } }
      ]
    },
    {
      "key": "languages",
      "items": [
        { "code": "uk", "native": "Українська",
          "names": { "uk": "Українська", "en": "Ukrainian", "ru": "Украинский", "de": "Ukrainian", "es": "Ukrainian" } }
      ]
    }
  ],
  "metadata": { "etag": "W/\"dict-…\"", "generated_at": "2026-05-30T08:00:00+00:00", "languages": ["uk","en","ru","de","es"] },
  "links": [],
  "message": null
}

Field	Description
`payload[].key`	Dictionary key.
`payload[].items[].code`	Stable id used as the value in write endpoints. Numeric for most dictionaries (species, sex, …); for pet_species_featured it is the canonical species public_id (a UUID) → pass it as species_public_id on POST /animals; for countries it is the zero-padded ISO 3166-1 numeric code as a string (e.g. "004", "804"); for languages it is the ISO 639-1 code (e.g. "uk").
`payload[].items[].names`	Map locale → localized name. Locales without a translation fall back to English.
`payload[].items[].alpha2 / alpha3`	Countries only: ISO 3166-1 alpha-2 / alpha-3 codes for convenient mapping.
`payload[].items[].native`	Languages only: the language's own name (endonym), handy for language pickers.
`metadata.etag`	Pass back in If-None-Match to get 304 when unchanged.
`metadata.languages`	Active locales actually present in this build.

Response statuses

Status	Meaning
`200`	OK — dictionaries returned.
`304`	Not Modified — your If-None-Match matches; reuse the cached copy.

GET/v1/partner/dictionaries/speciesWyszukiwanie gatunków (kanoniczne, według public_id).▸

Auth: Public (no signature required).

Request fields

Field	Req.	Type	Dictionary	Description
`q`	no	string	—	Species search term (any taxonomic rank, substring + typo-tolerant). Omit to browse the top matches. Complements the popular-only pet_species_featured dictionary.

Example response

{
  "payload": [
    { "public_id": "1b289672-0a74-48d2-9600-7104bedacd8c", "name": "Dog", "rank": "species", "has_breeds": true },
    { "public_id": "9cd7d2a1-4e45-4922-8f9e-fb84c61ca6ae", "name": "Cats", "rank": "genus", "has_breeds": false }
  ]
}

Field	Description
`payload[].public_id`	Species public_id — pass it as species_public_id on POST /animals, or into /dictionaries/species/{species_public_id}/breeds.
`payload[].name`	Localized species name (request locale, English fallback).
`payload[].rank`	Taxonomic rank (species, genus, family, …).
`payload[].has_breeds`	Whether the species carries a breed list.

Response statuses

Status	Meaning
`200`	OK — matching species.

GET/v1/partner/dictionaries/species/{species_public_id}/breedsRasy dla gatunku (kanoniczne, według public_id).▸

Auth: Public (no signature required).

Request fields

Field	Req.	Type	Dictionary	Description
`species_public_id`	yes	string	—	Path segment: the species public_id (a UUID). Discover it via pet_species_featured or /dictionaries/species.
`q`	no	string	—	Optional breed-name filter (substring, typo-tolerant).

Example response

{
  "payload": [
    { "public_id": "6bb37956-d7fb-426d-8045-9d2fb854ee43", "name": "Belgian Shepherd Dog", "kind": "purebred" },
    { "public_id": "d1f2a0c8-7b3e-4a1d-9c22-0f5e6b7a8c90", "name": "Mixed breed", "kind": "mixed" }
  ]
}

Field	Description
`payload[].public_id`	Canonical breed public_id — pass it as breed_public_id on POST /animals.
`payload[].name`	Localized breed name (request locale, English fallback).
`payload[].kind`	purebred \| mixed \| unknown \| crossbreed \| variety. mixed/unknown/crossbreed are the special sentinel options.

Response statuses

Status	Meaning
`200`	OK — breeds for the species (an empty list for a species with no breeds).
`404`	species_public_id is not a valid UUID (the route did not match).

Owners

POST/v1/partner/ownersUtwórz (lub znajdź) właściciela; zwraca globalny identyfikator użytkownika.▸

Auth: HMAC. Any partner key. · X-Eternity-Idempotency-Key required

Request fields

Field	Req.	Type	Dictionary	Description
`email`	conditional	string	—	Owner email. One of email/phone is required — it is how the owner is later reached/authenticated.
`phone`	conditional	string	—	Owner phone (E.164). One of email/phone is required.
`first_name`	no	string	—	Given name.
`last_name`	no	string	—	Family name.
`language`	no	string	`languages`	Preferred locale.
`country`	no	string	`countries`	Zero-padded ISO 3166-1 numeric code as a string (e.g. "804") — matches the countries dictionary code.
`external_owner_id`	no	string	—	Your own identifier for this person. Stored once, on first contact, and never overwritten — send it so both sides can reconcile the same human later. Max 128 characters.
`consent`	yes	object	—	Consent block (immutable audit).
`consent.account_creation`	yes	bool	—	Must be true — the owner agreed to account creation. The time of capture is recorded server-side.

Request body (JSON)

{
  "email": "jane@example.com",
  "phone": "+380681234567",
  "first_name": "Jane",
  "last_name": "Doe",
  "language": "uk",
  "country": "804",
  "external_owner_id": "crm-4471",
  "consent": {
    "account_creation": true
  }
}

Example response

{
  "payload": {
    "user_gid": 90231,
    "public_id": "V1StGXR8Z5jd",
    "has_account": true,
    "email": "jane@example.com",
    "phone": null,
    "display_hint": "Ол*** К.",
    "language": "uk",
    "country_id": 804,
    "external_owner_id": "crm-4471"
  }
}

Field	Description
`public_id`	Stable public owner id — pass it into POST /animals owners[].public_id (API version >= 2026-07-04).
`user_gid`	Legacy numeric owner id (owner-attach on older API versions).
`has_account`	Whether the owner already has a usable account.
`email`	Email on file for this owner (null if unknown).
`phone`	Phone on file for this owner (null if unknown).
`display_hint`	Masked display name (no PII).
`external_owner_id`	The id YOU sent us for this person, or null if you never did. Scoped to your own integration — you never see what another partner calls the same person.

Response statuses

Status	Meaning
`201`	Created (or resolved an existing owner — idempotent by email/phone).
`409`	X-Eternity-Idempotency-Key reused with a different body, or still being processed.
`422`	Validation error (missing email/phone, or consent.account_creation not accepted).

GET/v1/partner/owners/searchZnajdź właściciela po dokładnym adresie e-mail lub numerze telefonu.▸

Auth: HMAC. Any partner key.

Request fields

Field	Req.	Type	Dictionary	Description
`email_or_phone`	yes	string	—	Exact email or phone (single field; email detected by format).

Example response

{
  "payload": { "user_gid": 90231, "public_id": "V1StGXR8Z5jd", "has_account": true, "email": "jane@example.com", "phone": null, "display_hint": "Ол*** К.", "language": "uk", "country_id": 804, "external_owner_id": "crm-4471" }
}

Field	Description
`public_id`	Stable public owner id — pass it into POST /animals owners[].public_id (API version >= 2026-07-04).
`user_gid`	Legacy numeric owner id (owner-attach on older API versions).
`email`	Email on file for this owner (null if unknown).
`phone`	Phone on file for this owner (null if unknown).
`external_owner_id`	The id YOU sent us for this person, or null if you never did. Scoped to your own integration — you never see what another partner calls the same person.

Response statuses

Status	Meaning
`200`	Owner found.
`404`	No owner with that email_or_phone.
`422`	email_or_phone is required.

Animals

POST/v1/partner/animalsZarejestruj zwierzę (na podstawie czipa).▸

Auth: HMAC. Vet/organization key. · X-Eternity-Idempotency-Key required

Request fields

Field	Req.	Type	Dictionary	Description
`species`	conditional	int	`species`	Legacy species dictionary id. Exactly one of species / species_public_id is required.
`species_public_id`	conditional	string	`pet_species_featured`	Canonical species public_id (a UUID) from the pet_species_featured dictionary. Exactly one of species / species_public_id is required; when present it wins over species.
`is_microchip`	yes	bool	—	Whether the animal is chipped. true → microchip is required; false → microchip is ignored and the registry assigns a temporary WC number.
`microchip`	conditional	string	—	Microchip (transponder). Required only when is_microchip = true.
`nickname`	yes	string	—	Animal name.
`qr_tag`	no	string	—	QR passport serial to attach at registration.
`owners`	no	array	—	Owners; first becomes main_owner, the rest owners (de-duplicated). Each entry either attaches an existing owner OR registers a new one inline.
`owners[].public_id`	conditional	string	—	Attach mode (API version >= 2026-07-04): existing owner public_id from POST/GET owners. Omit to register inline.
`owners[].user_gid`	conditional	int	—	Attach mode (API versions before 2026-07-04): legacy numeric owner id. Omit to register inline.
`owners[].email`	conditional	string	—	Inline mode: owner email. One of email/phone required when there is no public_id/user_gid (upserted — no duplicates).
`owners[].phone`	conditional	string	—	Inline mode: owner phone (E.164).
`owners[].first_name`	no	string	—	Inline mode: given name.
`owners[].last_name`	no	string	—	Inline mode: family name.
`owners[].language`	no	string	`languages`	Inline mode: preferred locale.
`owners[].country`	no	string	`countries`	Inline mode: zero-padded ISO 3166-1 numeric code as a string (e.g. "804") — matches the countries dictionary code.
`owners[].external_owner_id`	no	string	—	Inline mode: your own identifier for this person — same field and same rules as on POST /owners.
`owners[].consent.account_creation`	conditional	bool	—	Inline mode: must be true — the owner agreed to account creation. Required only when registering inline.
`breed`	no	string	—	Breed (free text). Used only when breed_public_id is absent.
`breed_public_id`	no	string	—	Canonical breed public_id (a UUID) from GET /breeds?species_public_id=. Must belong to the species; when present it wins over the free-text breed.
`color`	no	string	—	Color (free text — no dictionary).
`gender_id`	no	int	`sex`	Gender dictionary id.
`dob`	no	date	—	Date of birth (ISO 8601).
`microchip_date`	no	date	—	When the chip was implanted (ISO 8601).
`sterilization`	no	bool	—	Sterilized flag.
`size`	no	int	`sizes`	Size dictionary id.
`identifiers`	no	array	—	Extra identifiers besides microchip/qr.
`identifiers[].type`	yes	int	`other_identifiers`	Identifier type id from the other_identifiers dictionary (tattoo, ring, …).
`identifiers[].value`	yes	string	—	Identifier value.
`identifiers[].added_at`	no	date	—	When the identifier was assigned (ISO 8601).

Request body (JSON)

{
  "species": 3,
  "is_microchip": true,
  "microchip": "900263000123456",
  "nickname": "Барсік",
  "qr_tag": null,
  "gender_id": 1,
  "breed": "Labrador",
  "color": "black",
  "dob": "2022-03-01T00:00:00+00:00",
  "microchip_date": "2022-11-20T00:00:00+00:00",
  "sterilization": true,
  "size": 2,
  "owners": [
    { "public_id": "V1StGXR8Z5jd" },
    {
      "email": "jane@example.com",
      "phone": "+380681234567",
      "first_name": "Jane",
      "last_name": "Doe",
      "external_owner_id": "crm-4471",
      "consent": { "account_creation": true }
    }
  ],
  "identifiers": [
    { "type": 3, "value": "TAT-001", "added_at": "2026-05-01T00:00:00+00:00" }
  ]
}

Example response

{ "payload": { "id": "8xK3pQzVnB7rL2qF" } }

Field	Description
`id`	Unguessable public animal id (NanoID). Use it in all subsequent animal calls.

Response statuses

Status	Meaning
`201`	Animal registered.
`409`	X-Eternity-Idempotency-Key conflict (same key, different body).
`422`	Validation error: missing nickname/is_microchip, or neither species nor species_public_id; an unknown species_public_id/breed_public_id or a breed_public_id that does not belong to the species; is_microchip=true without a valid microchip; a duplicate microchip (transponder already registered, field "transponder"); or an inline owner without email/phone or without consent.account_creation.

GET/v1/partner/animals/by-identifier/{type}/{value}Wyszukiwanie według konkretnego typu identyfikatora. Zawsze tablica.▸

Auth: HMAC. Any partner key.

Request fields

Field	Req.	Type	Dictionary	Description
`type`	yes	path enum	—	microchip or qr_tag.
`value`	yes	path string	—	Identifier value to look up.

Example response

{
  "payload": [
    { "id": "8xK3pQzVnB7rL2qF", "species": 3,
      "species_public_id": "d49c523a-d7ff-41b4-9ab6-0d1d2ce20939", "species_name": "Собака",
      "breed": "Labrador", "breed_public_id": null, "breed_name": null,
      "color": "black", "gender_id": 1,
      "nickname": "Барсік", "microchip": "900263000123456", "qr_tag": null,
      "dob": "2022-03-01", "register_date": "2026-05-30", "sterilization_status": true,
      "lost_status": null, "deceased": false, "died_at": null, "status": 1,
      "abilities": { "can_edit": true } }
  ]
}

Field	Description
`payload`	Array of animal cards — usually one, but a value may resolve to several.
`species_public_id`	Canonical species public_id — the same key you pass back as species_public_id on POST /animals.
`species_name`	Species name in the request language (falls back to English, then to the Latin name).
`breed_public_id`	Canonical breed public_id, or null when the animal carries only the free-text breed.
`breed_name`	Canonical breed name in the request language; null when breed_public_id is null — read `breed` then.
`microchip / qr_tag`	Active identifiers.
`lost_status`	"active" when reported lost, otherwise null.
`deceased`	True once euthanasia/death is recorded.

Abilities

Every animal object carries an abilities object describing what the authenticated partner user may do with this animal. This is the first access flag; more will be added over time.

Field	Description
`abilities.can_edit`	Whether the authenticated partner user may edit this animal — update its data, add procedures and manage photos. True when the user registered the animal, has any relation to it (animal_user_relation), or is an active member of an organization whose registry holds it (org_animals).

Expansion (`X-Eternity-Expand`)

Optional header carrying a JSON array of expand keys (e.g. ["owners"]). Each requested key embeds an extra field into every animal object in the response; omit the header to get the plain card. Unknown keys are rejected with 422.

Key	Adds	Description
`owners`	`owners[]`	The animal's owners — the main owner plus any co-owners — each with contact data and an is_main_owner flag. Available on this partner surface only.

"owners": [
  {
    "user_gid": 90231,
    "public_id": "V1StGXR8Z5jd",
    "has_account": true,
    "email": "jane@example.com",
    "phone": "+380681234567",
    "display_hint": "Ja*** D.",
    "language": "uk",
    "country_id": "804",
    "external_owner_id": "crm-4471",
    "is_main_owner": true
  }
]

Field	Description
`owners[].public_id`	Stable public owner id — pass it into POST /animals owners[].public_id (API version >= 2026-07-04).
`owners[].user_gid`	Legacy numeric owner id (owner-attach on older API versions).
`owners[].has_account`	Whether the owner already has a usable account.
`owners[].email`	Email on file for this owner (null if unknown).
`owners[].phone`	Phone on file for this owner (null if unknown).
`owners[].display_hint`	Masked display name (no PII).
`owners[].language`	Preferred locale.
`owners[].country_id`	Zero-padded ISO 3166-1 numeric code as a string (e.g. "804").
`owners[].external_owner_id`	The id YOU sent us for this person, or null if you never did. Scoped to your own integration — you never see what another partner calls the same person.
`owners[].is_main_owner`	true for the main owner (animal_user_relation type main_owner); false for co-owners.

Response statuses

Status	Meaning
`200`	OK — array (possibly empty).

GET/v1/partner/animals/by-identifier/{value}Wyszukiwanie po wszystkich typach identyfikatorów naraz. Zawsze tablica.▸

Auth: HMAC. Any partner key.

Request fields

Field	Req.	Type	Dictionary	Description
`value`	yes	path string	—	Identifier value; searched across microchip and qr_tag.

Example response

{ "payload": [ { "id": "8xK3pQzVnB7rL2qF", "nickname": "Барсік", "microchip": "900263000123456",
                 "species": 3, "species_public_id": "d49c523a-d7ff-41b4-9ab6-0d1d2ce20939",
                 "species_name": "Собака", "breed": "Labrador",
                 "breed_public_id": null, "breed_name": null } ] }

Field	Description
`species_public_id / breed_public_id`	Canonical keys — the same ones POST /animals accepts. breed_public_id is null while the animal carries only the free-text breed.
`species_name / breed_name`	Names in the request language (falling back to English, then to the Latin/canonical name).

Abilities

Every animal object carries an abilities object describing what the authenticated partner user may do with this animal. This is the first access flag; more will be added over time.

Field	Description
`abilities.can_edit`	Whether the authenticated partner user may edit this animal — update its data, add procedures and manage photos. True when the user registered the animal, has any relation to it (animal_user_relation), or is an active member of an organization whose registry holds it (org_animals).

Expansion (`X-Eternity-Expand`)

Key	Adds	Description
`owners`	`owners[]`	The animal's owners — the main owner plus any co-owners — each with contact data and an is_main_owner flag. Available on this partner surface only.

"owners": [
  {
    "user_gid": 90231,
    "public_id": "V1StGXR8Z5jd",
    "has_account": true,
    "email": "jane@example.com",
    "phone": "+380681234567",
    "display_hint": "Ja*** D.",
    "language": "uk",
    "country_id": "804",
    "external_owner_id": "crm-4471",
    "is_main_owner": true
  }
]

Field	Description
`owners[].public_id`	Stable public owner id — pass it into POST /animals owners[].public_id (API version >= 2026-07-04).
`owners[].user_gid`	Legacy numeric owner id (owner-attach on older API versions).
`owners[].has_account`	Whether the owner already has a usable account.
`owners[].email`	Email on file for this owner (null if unknown).
`owners[].phone`	Phone on file for this owner (null if unknown).
`owners[].display_hint`	Masked display name (no PII).
`owners[].language`	Preferred locale.
`owners[].country_id`	Zero-padded ISO 3166-1 numeric code as a string (e.g. "804").
`owners[].external_owner_id`	The id YOU sent us for this person, or null if you never did. Scoped to your own integration — you never see what another partner calls the same person.
`owners[].is_main_owner`	true for the main owner (animal_user_relation type main_owner); false for co-owners.

Response statuses

Status	Meaning
`200`	OK — array (possibly empty).

GET/v1/partner/animals/by-ownerWyszukiwanie zwierząt po kontakcie właściciela. Zawsze tablica.▸

Auth: HMAC. Any partner key.

Request fields

Field	Req.	Type	Dictionary	Description
`email_or_phone`	yes	string	—	Exact owner email or phone (single field; email detected by format). A phone is resolved to the owner first.

Example response

{ "payload": [ { "id": "8xK3pQzVnB7rL2qF", "nickname": "Барсік", "species": 3,
                 "species_public_id": "d49c523a-d7ff-41b4-9ab6-0d1d2ce20939",
                 "species_name": "Собака", "breed": "Labrador",
                 "breed_public_id": null, "breed_name": null } ] }

Field	Description
`species_public_id / breed_public_id`	Canonical keys — the same ones POST /animals accepts. breed_public_id is null while the animal carries only the free-text breed.
`species_name / breed_name`	Names in the request language (falling back to English, then to the Latin/canonical name).

Abilities

Every animal object carries an abilities object describing what the authenticated partner user may do with this animal. This is the first access flag; more will be added over time.

Field	Description
`abilities.can_edit`	Whether the authenticated partner user may edit this animal — update its data, add procedures and manage photos. True when the user registered the animal, has any relation to it (animal_user_relation), or is an active member of an organization whose registry holds it (org_animals).

Expansion (`X-Eternity-Expand`)

Key	Adds	Description
`owners`	`owners[]`	The animal's owners — the main owner plus any co-owners — each with contact data and an is_main_owner flag. Available on this partner surface only.

"owners": [
  {
    "user_gid": 90231,
    "public_id": "V1StGXR8Z5jd",
    "has_account": true,
    "email": "jane@example.com",
    "phone": "+380681234567",
    "display_hint": "Ja*** D.",
    "language": "uk",
    "country_id": "804",
    "external_owner_id": "crm-4471",
    "is_main_owner": true
  }
]

Field	Description
`owners[].public_id`	Stable public owner id — pass it into POST /animals owners[].public_id (API version >= 2026-07-04).
`owners[].user_gid`	Legacy numeric owner id (owner-attach on older API versions).
`owners[].has_account`	Whether the owner already has a usable account.
`owners[].email`	Email on file for this owner (null if unknown).
`owners[].phone`	Phone on file for this owner (null if unknown).
`owners[].display_hint`	Masked display name (no PII).
`owners[].language`	Preferred locale.
`owners[].country_id`	Zero-padded ISO 3166-1 numeric code as a string (e.g. "804").
`owners[].external_owner_id`	The id YOU sent us for this person, or null if you never did. Scoped to your own integration — you never see what another partner calls the same person.
`owners[].is_main_owner`	true for the main owner (animal_user_relation type main_owner); false for co-owners.

Response statuses

Status	Meaning
`200`	OK — array (empty if the owner has no email on file for phone-only lookups).
`422`	email_or_phone is required.

GET/v1/partner/animals/{id}Pełna karta zwierzęcia.▸

Auth: HMAC. Any partner key.

Request fields

Field	Req.	Type	Dictionary	Description
`id`	yes	path string	—	Animal public id (NanoID).

Example response

{ "payload": { "id": "8xK3pQzVnB7rL2qF", "species": 3,
               "species_public_id": "d49c523a-d7ff-41b4-9ab6-0d1d2ce20939", "species_name": "Собака",
               "breed": "Labrador", "breed_public_id": null, "breed_name": null,
               "nickname": "Барсік", "microchip": "900263000123456", "deceased": false,
               "abilities": { "can_edit": true } } }

Field	Description
`species_public_id`	Canonical species public_id — the same key you pass back as species_public_id on POST /animals.
`species_name`	Species name in the request language (falls back to English, then to the Latin name).
`breed_public_id`	Canonical breed public_id, or null when the animal carries only the free-text breed.
`breed_name`	Canonical breed name in the request language; null when breed_public_id is null — read `breed` then.

Abilities

Every animal object carries an abilities object describing what the authenticated partner user may do with this animal. This is the first access flag; more will be added over time.

Field	Description
`abilities.can_edit`	Whether the authenticated partner user may edit this animal — update its data, add procedures and manage photos. True when the user registered the animal, has any relation to it (animal_user_relation), or is an active member of an organization whose registry holds it (org_animals).

Expansion (`X-Eternity-Expand`)

Key	Adds	Description
`owners`	`owners[]`	The animal's owners — the main owner plus any co-owners — each with contact data and an is_main_owner flag. Available on this partner surface only.

"owners": [
  {
    "user_gid": 90231,
    "public_id": "V1StGXR8Z5jd",
    "has_account": true,
    "email": "jane@example.com",
    "phone": "+380681234567",
    "display_hint": "Ja*** D.",
    "language": "uk",
    "country_id": "804",
    "external_owner_id": "crm-4471",
    "is_main_owner": true
  }
]

Field	Description
`owners[].public_id`	Stable public owner id — pass it into POST /animals owners[].public_id (API version >= 2026-07-04).
`owners[].user_gid`	Legacy numeric owner id (owner-attach on older API versions).
`owners[].has_account`	Whether the owner already has a usable account.
`owners[].email`	Email on file for this owner (null if unknown).
`owners[].phone`	Phone on file for this owner (null if unknown).
`owners[].display_hint`	Masked display name (no PII).
`owners[].language`	Preferred locale.
`owners[].country_id`	Zero-padded ISO 3166-1 numeric code as a string (e.g. "804").
`owners[].external_owner_id`	The id YOU sent us for this person, or null if you never did. Scoped to your own integration — you never see what another partner calls the same person.
`owners[].is_main_owner`	true for the main owner (animal_user_relation type main_owner); false for co-owners.

Response statuses

Status	Meaning
`200`	OK.
`404`	Animal not found.

PATCH/v1/partner/animals/{id}Aktualizuj zmienialne pola / oznacz jako zmarłe.▸

Auth: HMAC. Owner OR vet with an active relation to the animal. · X-Eternity-Idempotency-Key required

Request fields

Field	Req.	Type	Dictionary	Description
`nickname`	no	string	—	New name.
`color`	no	string	—	New color (free text — no dictionary).
`sterilization_status`	no	bool	—	Set sterilized flag.
`deceased`	no	bool	—	true → mark the animal dead.

Request body (JSON)

{
  "nickname": "Барсік",
  "color": "black",
  "sterilization_status": true,
  "deceased": false
}

Example response

204 No Content

Response statuses

Status	Meaning
`204`	Updated.
`403`	No access to this animal — request it (POST /v1/partner/animals/{id}/access-request) and retry once the owner approves.
`409`	X-Eternity-Idempotency-Key conflict.
`422`	Validation error.

POST/v1/partner/animals/{id}/access-requestPoproś właściciela zwierzęcia o przyznanie Ci dostępu.▸

Auth: HMAC. Vet/organization key. · X-Eternity-Idempotency-Key required

Request fields

Field	Req.	Type	Dictionary	Description
`id`	yes	path string	—	Animal public id (NanoID).

Example response

{
  "payload": {
    "status": "pending",
    "requested_at": "2026-06-23T09:00:00+00:00",
    "expires_at": "2026-06-30T09:00:00+00:00",
    "retry_after_seconds": 604800
  }
}

Field	Description
`status`	"granted" — you already have access, no request was created; "pending" — awaiting the owner; "denied" — the owner declined (re-considerable until it expires).
`requested_at`	When the request was raised (null when status="granted").
`expires_at`	When the request expires and you may request again (null when status="granted").
`retry_after_seconds`	Seconds until you may request the same animal again (0 once elapsed; null when status="granted").

Response statuses

Status	Meaning
`201`	A new access request was created — the owner has been notified by email.
`200`	No new request created: you already have access (status "granted"), or an active request already exists (status "pending"/"denied") — wait retry_after_seconds before re-requesting.
`404`	Animal not found.

GET/v1/partner/animals/{id}/access-requestSprawdź, czy Twój wniosek o dostęp został zatwierdzony.▸

Auth: HMAC. Vet/organization key.

Request fields

Field	Req.	Type	Dictionary	Description
`id`	yes	path string	—	Animal public id (NanoID).

Example response

{
  "payload": {
    "status": "granted",
    "requested_at": "2026-06-23T09:00:00+00:00",
    "expires_at": "2026-06-30T09:00:00+00:00",
    "retry_after_seconds": 0
  }
}

Field	Description
`status`	"granted" — access has been approved and is active; "pending" — awaiting the owner; "denied" — declined; "none" — no active request.

Response statuses

Status	Meaning
`200`	OK.
`404`	Animal not found.

Procedures

POST/v1/partner/animals/{id}/proceduresZapisz procedury; otwiera wizytę. Pojedynczy obiekt lub tablica.▸

Auth: HMAC. Vet/organization key with access to the animal. · X-Eternity-Idempotency-Key required

Request fields

Field	Req.	Type	Dictionary	Description
`(body)`	yes	object \| array	—	A single procedure object or an array of them (≤100).
`type`	yes	int	`procedure_types`	Procedure catalogue id: 10 vaccination, 20 rabies vaccination, 30 transponder identification, 40 token identification, 50 deworming, 60 sterilization, 70 euthanasia / death certification.
`occurred_at`	yes	datetime	—	When performed (ISO 8601).
`summary`	no	string	—	Free-text note.
`revaccination_date`	no	date	—	Override next-vaccination date (vaccinations).
`type_specific_payload`	no	object	—	Per-type fields — validated server-side: 10/20 → {vaccine_name, batch_number}; 30 → {transponder_number* — 15 digits}; 40 → {token_number}; 50 → {drug, batch_number?, dose?}; 60 → {method?, anesthesia_type?}; 70 → {reason, death_date}. For type 30: if the animal already carries a microchip, it is kept — the new number is stored as an additional identifier (other_identifiers type 11) instead of replacing the chip.

Request body (JSON)

[
  {
    "type": 10,
    "occurred_at": "2026-05-30T08:00:00+00:00",
    "summary": "Annual shot",
    "revaccination_date": "2027-05-30",
    "type_specific_payload": {
      "vaccine_name": "Nobivac",
      "batch_number": "A123"
    }
  },
  {
    "type": 30,
    "occurred_at": "2026-05-30T08:05:00+00:00",
    "type_specific_payload": {
      "transponder_number": "900263000123456"
    }
  }
]

Example response

{
  "payload": {
    "appointment_id": 7741,
    "procedures": [
      { "id": 99001, "animal_id": "8xK3pQzVnB7rL2qF", "visit_id": 7741, "type": 10,
        "occurred_at": "2026-05-30T08:00:00+00:00", "summary": "Annual shot", "revaccination_date": "2027-05-30",
        "type_specific_payload": { "vaccine_name": "Nobivac", "batch_number": "A123" } }
    ]
  }
}

Field	Description
`appointment_id`	The visit opened/used for this batch.
`procedures[]`	The recorded procedures — same card as GET list/show.
`procedures[].id`	Procedure record id.
`procedures[].type`	Numeric type id (procedure_types dictionary).
`procedures[].type_specific_payload`	Stored type-specific payload.

Response statuses

Status	Meaning
`201`	Recorded; visit opened.
`403`	No access to this animal — request it (POST /v1/partner/animals/{id}/access-request) and retry once the owner approves.
`404`	Animal not found.
`409`	X-Eternity-Idempotency-Key conflict.
`422`	Unsupported type, missing occurred_at, or missing type-specific fields.

GET/v1/partner/animals/{id}/proceduresLista procedur zwierzęcia. Zawsze tablica.▸

Auth: HMAC. Vet/organization key.

Request fields

Field	Req.	Type	Dictionary	Description
`type`	no	int	`procedure_types`	Filter by procedure catalogue id.
`since`	no	datetime	—	Only on/after this time.
`until`	no	datetime	—	Only on/before this time.

Example response

{
  "payload": [
    { "id": 99001, "animal_id": "8xK3pQzVnB7rL2qF", "visit_id": 7741, "type": 10,
      "occurred_at": "2026-05-30T08:00:00+00:00", "summary": null, "revaccination_date": "2027-05-30",
      "type_specific_payload": { "vaccine_name": "Nobivac", "batch_number": "A123" } }
  ]
}

Field	Description
`type`	Procedure catalogue id (procedure_types dictionary).
`visit_id`	Appointment the procedure was recorded under.
`type_specific_payload`	Per-type fields.

Response statuses

Status	Meaning
`200`	OK — array (possibly empty).
`404`	Animal not found.

GET/v1/partner/procedures/{id}Pojedyncza procedura.▸

Auth: HMAC. Vet/organization key.

Request fields

Field	Req.	Type	Dictionary	Description
`id`	yes	path int	—	Procedure record id.

Example response

{
  "payload": {
    "id": 99001, "animal_id": "8xK3pQzVnB7rL2qF", "visit_id": 7741, "type": 10,
    "occurred_at": "2026-05-30T08:00:00+00:00", "summary": null, "revaccination_date": "2027-05-30",
    "type_specific_payload": { "vaccine_name": "Nobivac", "batch_number": "A123" }
  }
}

Response statuses

Status	Meaning
`200`	OK.
`404`	Procedure not found.

Photos

POST/v1/partner/animals/{id}/photosPrześlij zdjęcie (multipart). Właściciel lub weterynarz z powiązaniem.▸

Auth: HMAC + multipart/form-data. Owner OR vet with relation. · X-Eternity-Idempotency-Key required

Request fields

Field	Req.	Type	Dictionary	Description
`file`	yes	file	—	Image file. Max 8 MB per photo (config partner.photos.max_single_mb).
`kind`	no	enum	—	avatar \| gallery \| nose_print. avatar sets the main photo. Default gallery.

Example response

{ "payload": { "id": 33015 } }

Field	Description
`id`	New photo id.

Response statuses

Status	Meaning
`201`	Uploaded.
`403`	No access to this animal — request it (POST /v1/partner/animals/{id}/access-request) and retry once the owner approves.
`422`	Invalid file or larger than 8 MB (reduce size / lower quality).
`413`	Whole request exceeds 15 MB.

DELETE/v1/partner/animals/{id}/photos/{photoId}Miękkie usunięcie zdjęcia.▸

Auth: HMAC. Owner OR vet with relation. · X-Eternity-Idempotency-Key required

Request fields

Field	Req.	Type	Dictionary	Description
`id`	yes	path string	—	Animal public id (NanoID).
`photoId`	yes	path int	—	Photo id.

Example response

204 No Content

Response statuses

Status	Meaning
`204`	Deleted.
`403`	No access to this animal — request it (POST /v1/partner/animals/{id}/access-request) and retry once the owner approves.

Nic nie pasuje do Twojego wyszukiwania.

Dokumentacja Partner API

SDK i biblioteki klienckie

PHP · Composer

JavaScript · npm

Uwierzytelnianie i podpisywanie żądań

Webhooki

Delivery body (JSON)

Events

Treść zdarzenia o zgodzie

Metody API

Request fields

Example response

Response statuses

Request fields

Request body (JSON)

Example response

Response statuses

Request fields

Request body (JSON)

Example response

Response statuses

Example response

Response statuses

Request fields

Request body (JSON)

Example response

Response statuses

Example response

Response statuses

Request fields

Example response

Response statuses

Request fields

Example response

Response statuses

Request fields

Example response

Response statuses

Request fields

Request body (JSON)

Example response

Response statuses

Request fields

Example response

Response statuses

Request fields

Request body (JSON)

Example response

Response statuses

Request fields

Example response

Abilities

Expansion (X-Eternity-Expand)

Response statuses

Request fields

Example response

Abilities

Expansion (X-Eternity-Expand)

Response statuses

Request fields

Example response

Abilities

Expansion (X-Eternity-Expand)

Response statuses

Request fields

Example response

Abilities

Expansion (X-Eternity-Expand)

Response statuses

Request fields

Request body (JSON)

Example response

Response statuses

Request fields

Example response

Response statuses

Request fields

Example response

Response statuses

Request fields

Expansion (`X-Eternity-Expand`)

Expansion (`X-Eternity-Expand`)

Expansion (`X-Eternity-Expand`)

Expansion (`X-Eternity-Expand`)