API v1 to v2 Migration

Overview

API v2 introduces the Capture Session concept, streamlining how fingerprint and appearance images are processed. This guide helps you migrate from v1 to v2.

Key Changes

Capture Session Introduction

In v1, metadata (species, purpose) was passed with each file upload. In v2, you first create a capture session and then upload files within that session.

Aspect	API v1	API v2
Metadata	Passed with each upload	Set once at session creation
File Grouping	Manual ID management	Automatic via session
Action Request	List of file IDs	Session ID only

Endpoint Changes

Function	v1 Endpoint	v2 Endpoint
Fingerprint Upload	`POST /v1/fingerprints:upload`	`POST /v2/fingerprints:upload`
Appearance Upload	`POST /v1/appearances:upload`	`POST /v2/appearances:upload`
Pet Verify	`POST /v1/pets/{petId}:verify`	`POST /v2/pets/{petId}:verify`
Pet Identify	`POST /v1/pets:identify`	`POST /v2/pets:identify`
Add Fingerprints	`POST /v1/pets/{petId}:addFingerprints`	`POST /v2/pets/{petId}:addFingerprints`
New	-	`POST /v2/capture-sessions`

Automatic Session Linking: When uploading with the sessionId query parameter, files are automatically linked to the session. No separate session end API call is required, and all files in the session are automatically used when performing actions (verify, identify, addFingerprints).

Code Migration Example

v1 Code (Before)

// v1: Pass metadata with each upload
const fp1 = await fetch('/v1/fingerprints:upload', {
  method: 'POST',
  body: createFormData({
    file: file1,
    species: 'DOG',
    purpose: 'PET_VERIFICATION'
  })
}).then(r => r.json());

const fp2 = await fetch('/v1/fingerprints:upload', {
  method: 'POST',
  body: createFormData({
    file: file2,
    species: 'DOG',
    purpose: 'PET_VERIFICATION'
  })
}).then(r => r.json());

// v1: Verify with file ID list
const verifyResult = await fetch(`/v1/pets/${petId}:verify`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    fingerprints: [fp1.data.id, fp2.data.id]
  })
}).then(r => r.json());

v2 Code (After)

// v2: Create session (metadata once)
const session = await fetch('/v2/capture-sessions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    species: 'DOG',
    purpose: 'PET_VERIFICATION',
    petId: petId
  })
}).then(r => r.json());

// v2: Upload files (automatically linked with sessionId query parameter)
const fp1 = await fetch(`/v2/fingerprints:upload?sessionId=${session.data.sessionId}`, {
  method: 'POST',
  body: createFormData({ file: file1 })
}).then(r => r.json());

const fp2 = await fetch(`/v2/fingerprints:upload?sessionId=${session.data.sessionId}`, {
  method: 'POST',
  body: createFormData({ file: file2 })
}).then(r => r.json());

// v2: Verify with session ID (all uploaded files automatically used)
const verifyResult = await fetch(`/v2/pets/${petId}:verify`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sessionId: session.data.sessionId
  })
}).then(r => r.json());

Session States

Capture sessions have the following states:

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

Upload Requirements

Operation	Minimum Fingerprints
Registration	5
Verification	3
Identification	3

Migration Checklist

Add session creation logic (POST /v2/capture-sessions)
Add sessionId query parameter to file upload URLs
Remove species, purpose metadata from file upload request body
Use session ID instead of file ID list in verify/identify requests
Remove session end logic (automatically handled)
Add session-related error handling
Update endpoint URLs from /v1/ to /v2/

v2 Benefits

Simplified Metadata: Set species and purpose once at session creation
Better Tracking: All uploads for an operation are automatically grouped
Enhanced Validation: Minimum requirements checked before processing
Extensibility: Session-based architecture supports progress tracking, resumable uploads, etc.

Common Migration Errors

Upload Without Session

{
  "error": "Session context is required"
}

Solution: Create a capture session before uploading files.

Missing sessionId Query Parameter

{
  "error": "Session ID is required"
}

Solution: Add ?sessionId={sessionId} query parameter to upload URL.

Missing Pet ID for Verification

{
  "error": "Pet ID is required for verification purpose"
}

Solution: Include petId when creating the capture session.