Server API Overview

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

Environment	URL
Production	`https://api.b2b.petnow.io`
Staging	`https://api.stage-b2b.petnow.io`

API Documentation (Redoc): https://api.b2b.petnow.io/redoc

Authentication

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

curl -X GET "https://api.b2b.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.b2b.petnow.io/v2/pets",
    headers=headers
)

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

API Key Issuance

Request your API Key by contacting the Petnow team via email.

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

State	Description
`STARTED`	Session is active and ready to receive uploads
`FINISHED`	Session successfully ended with captured data
`ABORTED`	Session was cancelled or failed
`TIMEOUT`	Session expired without proper closure

Session Purpose

Purpose	Description	Pet ID Required
`PET_PROFILE_REGISTRATION`	Register new pet	✅ Yes
`PET_VERIFICATION`	Verify specific pet (1:1)	✅ Yes
`PET_IDENTIFICATION`	Identify pet (1:N)	❌ No

Complete Workflows

Pet Registration Flow

Pet Verification Flow

Pet Identification Flow

API Endpoint Summary

Capture Sessions

Method	Endpoint	Description
POST	`/v2/capture-sessions`	Create capture session

Pet Management

Method	Endpoint	Description
POST	`/v2/pets`	Create pet
GET	`/v2/pets`	List pets
GET	`/v2/pets/{petId}`	Get pet details
PATCH	`/v2/pets/{petId}`	Update pet
DELETE	`/v2/pets/{petId}`	Delete pet

Biometric Upload

Method	Endpoint	Description
POST	`/v2/fingerprints:upload?sessionId={sessionId}`	Upload fingerprint (nose) image
POST	`/v2/appearances:upload?sessionId={sessionId}`	Upload appearance image

Verification & Identification

Method	Endpoint	Description
POST	`/v2/pets/{petId}:addFingerprints`	Add fingerprints
POST	`/v2/pets/{petId}:verify`	Verify pet
POST	`/v2/pets:identify`	Identify pet

Job Status

Method	Endpoint	Description
GET	`/v2/fingerprint-addition-jobs/{jobId}`	Fingerprint addition status
GET	`/v2/verification-jobs/{jobId}`	Verification status
GET	`/v2/identification-jobs/{jobId}`	Identification status