Petnow LogoPetnow

Pet Management API

Create, read, update, and delete pet profiles using the Petnow API.

Overview

The Pet Management API allows you to perform CRUD (Create, Read, Update, Delete) operations on pet profiles.

Create Pet

Create a new pet profile.

Endpoint: POST /v2/pets

Request

curl -X POST "https://api.petify.petnow.io/v2/pets" \
  -H "x-petnow-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "species": "DOG",
    "breed": "Golden Retriever",
    "metadata": "{\"name\": \"Buddy\", \"age\": 3, \"owner\": \"John Doe\"}"
  }'
import requests
import json

url = "https://api.petify.petnow.io/v2/pets"
headers = {
    "x-petnow-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "species": "DOG",
    "breed": "Golden Retriever",
    "metadata": json.dumps({
        "name": "Buddy",
        "age": 3,
        "owner": "John Doe"
    })
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)
# {"success": true, "data": {"id": "pet-uuid-1234"}}
const response = await fetch("https://api.petify.petnow.io/v2/pets", {
  method: "POST",
  headers: {
    "x-petnow-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    species: "DOG",
    breed: "Golden Retriever",
    metadata: JSON.stringify({
      name: "Buddy",
      age: 3,
      owner: "John Doe"
    })
  })
});

const result = await response.json();
console.log(result);
// {success: true, data: {id: "pet-uuid-1234"}}

Request Parameters

FieldTypeRequiredDescription
speciesstring✅Species: DOG or CAT
breedstring❌Breed
metadatastring❌Additional info as JSON string

Response

{
  "success": true,
  "data": {
    "id": "pet-uuid-1234"
  }
}

Using Metadata: You can store additional information such as name, age, and owner details in the metadata field as a JSON string.

List Pets

Retrieve all registered pets.

Endpoint: GET /v2/pets

Request

curl -X GET "https://api.petify.petnow.io/v2/pets" \
  -H "x-petnow-api-key: YOUR_API_KEY"
import requests

url = "https://api.petify.petnow.io/v2/pets"
headers = {
    "x-petnow-api-key": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
result = response.json()
print(result)
const response = await fetch("https://api.petify.petnow.io/v2/pets", {
  method: "GET",
  headers: {
    "x-petnow-api-key": "YOUR_API_KEY"
  }
});

const result = await response.json();
console.log(result);

Response

{
  "success": true,
  "data": [
    {
      "id": "pet-uuid-1234",
      "species": "DOG",
      "breed": "Golden Retriever",
      "metadata": "{\"name\": \"Buddy\", \"age\": 3}",
      "hasFingerprint": true,
      "createdAt": "2026-01-15T10:30:00Z"
    },
    {
      "id": "pet-uuid-5678",
      "species": "CAT",
      "breed": "Russian Blue",
      "metadata": "{\"name\": \"Nabi\", \"age\": 2}",
      "hasFingerprint": false,
      "createdAt": "2026-01-10T14:20:00Z"
    }
  ]
}

data is the pet array directly (not wrapped in a pets field). Each item includes hasFingerprint (a boolean indicating whether the pet has any registered fingerprints).

Get Pet Details

Retrieve detailed information about a specific pet.

Endpoint: GET /v2/pets/{petId}

Request

curl -X GET "https://api.petify.petnow.io/v2/pets/pet-uuid-1234" \
  -H "x-petnow-api-key: YOUR_API_KEY"
import requests

pet_id = "pet-uuid-1234"
url = f"https://api.petify.petnow.io/v2/pets/{pet_id}"
headers = {
    "x-petnow-api-key": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
result = response.json()
print(result)
const petId = "pet-uuid-1234";
const response = await fetch(`https://api.petify.petnow.io/v2/pets/${petId}`, {
  method: "GET",
  headers: {
    "x-petnow-api-key": "YOUR_API_KEY"
  }
});

const result = await response.json();
console.log(result);

Response

{
  "success": true,
  "data": {
    "id": "pet-uuid-1234",
    "species": "DOG",
    "breed": "Golden Retriever",
    "metadata": "{\"name\": \"Buddy\", \"age\": 3, \"owner\": \"John Doe\"}",
    "hasFingerprint": true,
    "createdAt": "2026-01-15T10:30:00Z"
  }
}

Response Fields

FieldTypeDescription
idstringPet ID
speciesstringDOG or CAT
breedstringBreed
metadatastringAdditional info as JSON string
hasFingerprintbooleanWhether the pet has any registered fingerprints
createdAtstringCreation timestamp (ISO 8601)

Update Pet

Update a pet's metadata.

Endpoint: PATCH /v2/pets/{petId}

Request

curl -X PATCH "https://api.petify.petnow.io/v2/pets/pet-uuid-1234" \
  -H "x-petnow-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "breed": "Golden Retriever Mix",
    "metadata": "{\"name\": \"Buddy\", \"age\": 4, \"owner\": \"John Doe\", \"vaccinated\": true}"
  }'
import requests
import json

pet_id = "pet-uuid-1234"
url = f"https://api.petify.petnow.io/v2/pets/{pet_id}"
headers = {
    "x-petnow-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "breed": "Golden Retriever Mix",
    "metadata": json.dumps({
        "name": "Buddy",
        "age": 4,
        "owner": "John Doe",
        "vaccinated": True
    })
}

response = requests.patch(url, headers=headers, json=data)
result = response.json()
print(result)
const petId = "pet-uuid-1234";
const response = await fetch(`https://api.petify.petnow.io/v2/pets/${petId}`, {
  method: "PATCH",
  headers: {
    "x-petnow-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    breed: "Golden Retriever Mix",
    metadata: JSON.stringify({
      name: "Buddy",
      age: 4,
      owner: "John Doe",
      vaccinated: true
    })
  })
});

const result = await response.json();
console.log(result);

Request Parameters

FieldTypeRequiredDescription
metadatastring✅Additional info as JSON string
breedstring❌Breed

Response

{
  "success": true,
  "data": {
    "isSuccessful": true
  }
}

Update returns only { "isSuccessful": true } — it does not echo back the updated pet. Call Get Pet Details afterwards if you need the updated values.

Delete Pet

Delete a pet profile. A deleted pet is excluded from verification and identification immediately, and it no longer counts as a registered pet for billing. To use the service for that pet again, it must be re-registered (a new profile and a new capture).

Endpoint: DELETE /v2/pets/{petId}

Request

curl -X DELETE "https://api.petify.petnow.io/v2/pets/pet-uuid-1234" \
  -H "x-petnow-api-key: YOUR_API_KEY"
import requests

pet_id = "pet-uuid-1234"
url = f"https://api.petify.petnow.io/v2/pets/{pet_id}"
headers = {
    "x-petnow-api-key": "YOUR_API_KEY"
}

response = requests.delete(url, headers=headers)
print(response.status_code)  # 204 No Content
const petId = "pet-uuid-1234";
const response = await fetch(`https://api.petify.petnow.io/v2/pets/${petId}`, {
  method: "DELETE",
  headers: {
    "x-petnow-api-key": "YOUR_API_KEY"
  }
});

console.log(response.status);  // 204 No Content

Response

Returns 204 No Content on success.

Warning: Deletion is not reversible for the integrator — there is no restore API, so confirm the petId before calling.

Deleting a pet that is already gone returns 404 with PETNOWB2B20000, so a repeated call is safe.

Pets created by Web Integration

Pets registered through Web Integration are referenced by your externalPetId only — their Petify petId is not exposed to you, so they cannot be deleted through this API. Delete them in the Petify Console under Biometric Registration Results by searching for the externalPetId (see Petify Console). The Console delete has the same effect as DELETE /v2/pets/{petId}: the pet is excluded from matching immediately and the externalPetId becomes registrable again.

Keep your own externalPetId ↔ member mapping on your side. It is the only handle you have for a Web Integration pet, and you will need it to find and delete the record when a member cancels.

Cleaning up incomplete records

When a registration flow aborts after POST /v2/pets succeeded — for example the upload or addFingerprints step failed — the pet profile remains with hasFingerprint: false. Such a pet has no biometric data, but it still counts as a registered pet at the billing snapshot. Delete it rather than leaving it behind:

  1. List pets with GET /v2/pets.
  2. Filter for hasFingerprint == false (skip any profile whose registration is still in progress).
  3. DELETE /v2/pets/{petId} each one. 204 means deleted; 404 PETNOWB2B20000 means it was already gone — either way the re-run is safe.
curl -s "https://api.petify.petnow.io/v2/pets" \
  -H "x-petnow-api-key: YOUR_API_KEY" \
| jq -r '.data[] | select(.hasFingerprint == false) | .id' \
| while read -r pet_id; do
    curl -s -o /dev/null -w "$pet_id %{http_code}\n" -X DELETE \
      "https://api.petify.petnow.io/v2/pets/$pet_id" \
      -H "x-petnow-api-key: YOUR_API_KEY"
  done

We recommend calling DELETE directly in your error handling whenever a registration flow fails after the profile was created, and auditing for hasFingerprint: false profiles periodically (e.g. before each billing date).

Member cancellation checklist

When a member leaves your service, remove their pet so it is neither matched nor billed:

  1. Look up the pet's petId from your own mapping (or GET /v2/pets and match on metadata).
  2. Call DELETE /v2/pets/{petId}.
  3. Confirm the response is 204 (or 404 PETNOWB2B20000 if it was already deleted).
  4. Drop the mapping on your side.

For pets registered through Web Integration, replace steps 1–3 with the Console delete described above.

Metadata Schema Example

Here's an example schema for the metadata field:

{
  "name": "Buddy",
  "age": 3,
  "gender": "male",
  "owner": {
    "name": "John Doe",
    "phone": "010-1234-5678",
    "email": "user@example.com"
  },
  "vaccinated": true,
  "registrationNumber": "123456789",
  "notes": "Has allergies"
}

Tip: Since metadata is stored as a JSON string, you need to parse it when retrieving. You can freely define field names and structure according to your business requirements.

Next Steps

On this page

OverviewCreate PetRequestRequest ParametersResponseList PetsRequestResponseGet Pet DetailsRequestResponseResponse FieldsUpdate PetRequestRequest ParametersResponseDelete PetRequestResponsePets created by Web IntegrationCleaning up incomplete recordsMember cancellation checklistMetadata Schema ExampleNext Steps