Petnow LogoPetnow

Server API Overview

Learn how to use the Petnow Server API and authentication methods.

Overview

Petnow Server API is a RESTful API that allows you to implement pet biometric recognition features directly from your server. We recommend calling the API from your server instead of using the mobile SDK's API Module.

Why use Server API?

  • Securely manage API Keys on your server
  • Handle requests independently of client app network issues
  • Centralize business logic and data processing on your server

Base URL

EnvironmentURL
Productionhttps://api.petify.petnow.io

API reference: every endpoint, with request and response schemas, status codes, and code samples, is listed in the sidebar under Server API. Start with Create a pet or Create a capture session. The pages are generated from the OpenAPI schema of the Petify server.

Authentication

All API requests require the x-petnow-api-key header.

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

headers = {
    "x-petnow-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

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

API Key Issuance

Issue your API Key directly from the Petify Console under My Page → API Key Management (a registered payment method is required first). See the Petify Console doc for sign-up and key issuance.

For questions, contact support@petnow.io.

Keep your API Key on the server only. Do not include it in client apps. If your API Key is exposed, contact us immediately for reissuance.

Capture Session Concept

API v2 uses the Capture Session concept. The entire process of uploading and processing biometric data is managed through sessions.

Session Lifecycle

Session States

StateDescription
STARTEDSession is active and ready to receive uploads
FINISHEDSession successfully ended with captured data
ABORTEDSession was cancelled or failed
TIMEOUTSession expired without proper closure

Session Purpose

PurposeDescriptionPet ID Required
PET_PROFILE_REGISTRATIONRegister new pet✅ Yes
PET_VERIFICATIONVerify specific pet (1:1)✅ Yes
PET_IDENTIFICATIONIdentify pet (1:N)❌ No

Complete Workflows

Pet Registration Flow

Pet Verification Flow

Pet Identification Flow

Uploading Images

Make every upload call on your app server with the x-petnow-api-key header. Do not call the upload routes directly from a client app, because that exposes the API key. A mobile or React Native client sends the captured file:// images to your app server, which then uploads them.

  • Create a capture session first, then pass its id as the sessionId query parameter of every upload. The server links each uploaded file to the session. There is no separate session-end call.
  • Upload at least 5 fingerprint images for registration and at least 3 for verification or identification. More images improve recognition accuracy.
  • An appearance image is required for every purpose. Upload the appearance images that the UI module provides. If you leave them out, the job fails with CaptureSessionIsNotFinishedException (PETNOWB2B20012).

Start a job only after every upload has finished

Call addFingerprints, verify, or identify only after every fingerprint and appearance upload for the session has returned 201. There is no session-end call, so this call tells the server that the session is complete. The job may not use an image that arrives after the call, and that upload still returns 201. If you upload in parallel, wait for all uploads to finish before you start the job.

Registration, Verification, and Identification

FeatureDescriptionUse Case
RegistrationAdd fingerprints to a petRegister a new pet
Verification1:1 matchingConfirm "Is this the right pet?"
Identification1:N matchingFind "Who is this pet?"

Registration. Create the pet profile first (POST /v2/pets), then run the registration capture session for that petId and call addFingerprints. Registration does not run identification automatically, so the server does not prevent the same animal from being registered twice under different profiles. If your product must prevent duplicates, run an identification session first and decide in your own code before you create the profile. The fingerprint-addition job returns only status: there is no petId or addedCount field.

Verification. The verify job returns isVerified (whether the match passed) and score (0-100) once status is SUCCESS.

Identification. A SUCCESS job returns the compared pets in pets, with these fields:

FieldTypeDescription
petsarrayEvery pet that the probe was compared with, matches and non-matches. Closest match first, so every isMatch: true item comes before every isMatch: false item. It is empty ([]) when you have no registered pet to compare with
pets[].idstringPet ID
pets[].scorenumberConfidence score (0-100)
pets[].isMatchbooleantrue when the server judges this pet to be the same animal as the probe. Always present
pets[].metadatastringPet metadata (JSON string)

For example, a job with one match and one non-match returns:

{
  "success": true,
  "data": {
    "status": "SUCCESS",
    "pets": [
      {
        "id": "pet-uuid-1234",
        "score": 95,
        "isMatch": true,
        "metadata": "{\"name\": \"Buddy\", \"owner\": \"John Doe\"}"
      },
      {
        "id": "pet-uuid-5678",
        "score": 41,
        "isMatch": false,
        "metadata": "{\"name\": \"Max\", \"owner\": \"Jane Smith\"}"
      }
    ]
  }
}

A job that compared pets but found no match returns them all with isMatch: false:

{
  "success": true,
  "data": {
    "status": "SUCCESS",
    "pets": [
      {
        "id": "pet-uuid-5678",
        "score": 41,
        "isMatch": false,
        "metadata": "{\"name\": \"Max\"}"
      }
    ]
  }
}

A job with no pet to compare with returns an empty list:

{
  "success": true,
  "data": {
    "status": "SUCCESS",
    "pets": []
  }
}

Plan gating: identification requires a plan that includes it (Petify Plus). An account without that entitlement is answered with HTTP 402 and PETNOWB2B10011 (identification not in plan) or PETNOWB2B10012 (a plan must be selected first, for accounts that are moving from the legacy plan). Handle both codes now. Choose or upgrade your plan in the Petify Console. See Error Codes for the codes.

Interpreting Scores

score is a similarity value from 0 to 100. The server applies its own match threshold, and you do not configure it. For verification, the result is isVerified. For identification, each item of pets carries isMatch. Use isMatch to decide which pets are a match. Do not set your own score cut-off: the same score can belong to both a match and a non-match.

pets lists every compared pet, ordered by match strength with the closest match first. The score usually decreases down the list. For cats it can occasionally rise between two adjacent items, so do not rely on the score for the order.

  • No registered pets to compare with: pets is [].
  • Candidates, but no match: every item has isMatch: false. Treat this as "no confident match".
  • One or more matches: the isMatch: true items come first.

A match against a different pet can still occur, especially with many similar-looking animals among your registered pets, so combine isMatch with your own context rather than treating it as proof on its own:

  • Show only the top N of the matches (for example Top 3) instead of the full list.
  • Pre-filter with your own data, such as species, breed, region, owner, or other metadata, before you accept a candidate.
  • Add a user confirmation step: show the candidate and let the user confirm.

Clients must ignore response fields they do not know. Petify can add fields without a version change.

See Troubleshooting for capture-quality causes of low or noisy scores.

Job Status and Polling

Registration, verification, and identification run as asynchronous jobs. Every job has one of these statuses:

StatusDescription
PENDINGProcessing
SUCCESSCompleted successfully
FAILEDFailed

Result fields are present only on SUCCESS. isVerified and score (verification) and pets[] (identification) appear only in the SUCCESS response. The fingerprint-addition job returns only status.
A FAILED response contains only status: there is no separate error or reason field. If the failure comes from a bad request, the server returns an error response when you submit the job (see Error Codes). If a job fails asynchronously, for example because of insufficient image quality, capture again and retry.

ItemRecommended Value
Polling Interval2-3 seconds
Max Wait Time60 seconds
Max Retry Count20-30 times

Exponential backoff reduces server load. Start at 1 second and increase to at most 5 seconds.

Instead of polling, you can receive the result at your server as a signed event. See Webhooks.

Managing Pets

Metadata. The metadata field of a pet is a JSON string. Store the name, age, owner, or any other data your product needs, and parse the string when you read it. You choose the field names and structure:

{
  "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"
}

List and update. GET /v2/pets returns the pet array directly in data, not wrapped in a pets field. Each item includes hasFingerprint. PATCH /v2/pets/{petId} returns only { "isSuccessful": true } and does not echo the updated pet. Call Get a pet afterwards if you need the new values.

Deleting a pet

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, re-register it with a new profile and a new capture.

Deletion is not reversible for the integrator. There is no restore API, so confirm the petId before you call Delete a pet.

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 can be registered again.

Keep your own externalPetId to member mapping on your side. It is the only handle you have for a Web Integration pet, and you 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 because 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

Call DELETE directly in your error handling whenever a registration flow fails after the profile was created. Also audit for hasFingerprint: false profiles periodically, for example 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 call 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 to 3 with the Console delete described above.

API Endpoint Summary

Each endpoint name links to its reference page.

Capture Sessions

MethodEndpointDescription
POST/v2/capture-sessionsCreate a capture session

Pet Management

MethodEndpointDescription
POST/v2/petsCreate a pet
GET/v2/petsList pets
GET/v2/pets/{petId}Get a pet
PATCH/v2/pets/{petId}Update a pet
DELETE/v2/pets/{petId}Delete a pet

Biometric Upload

MethodEndpointDescription
POST/v2/fingerprints:upload?sessionId={sessionId}Upload a fingerprint image
POST/v2/appearances:upload?sessionId={sessionId}Upload an appearance image

Registration, Verification, and Identification

MethodEndpointDescription
POST/v2/pets/{petId}:addFingerprintsAdd fingerprints to a pet
POST/v2/pets/{petId}:verifyVerify a pet
POST/v2/pets:identifyIdentify a pet

Job Status

MethodEndpointDescription
GET/v2/fingerprint-addition-jobs/{jobId}Get a fingerprint addition job
GET/v2/verification-jobs/{jobId}Get a verification job
GET/v2/identification-jobs/{jobId}Get an identification job

Hosted Sessions

MethodEndpointDescription
POST/v2/hosted-sessionsIssue a hosted session
GET/v2/hosted-sessions/{sessionId}Get a hosted session
GET/v2/hosted-results/{code}Get a result with a result code
GET/v2/hosted-results/{code}:displayDisplay a result in the browser

Next Steps

On this page