🐾 SmartTag Universal Pet API

Overview

The Universal Pet API allows developers to programmatically manage pet records, including all pet and owner information, secondary & veterinary contact details, and pet images. This REST API supports the creation and management of pet profiles with associated metadata.

Authentication

All API requests require an API key passed in the x-api-key header. Keys are associated with specific shelter/implant groups and must be valid in the system for pets to be imported and assigned to the correct shelter/implant group.

Required Headers

x-api-key: your_api_key_here
Content-Type: application/json

Base URLs

Endpoints

Request Format

Send a JSON payload with an array of pet objects. Each pet can include owner, secondary contact, and veterinary contact information.

{
  "pets": [
    {
      "microchip_number": "string (max 15 chars)",
      "pet_name": "string",
      "pet_type": "string",
      "pet_breed": "string",
      "pet_sec_breed": "string",
      "pet_color": "string",
      "pet_sec_color": "string",
      "pet_gender": "string",
      "pet_weight": "string",
      "pet_dob": "string (YYYY-MM-DD)",
      "pet_neutered": "string (Yes or No)",
      "pet_allergies": "string",
      "pet_unique_features": "string",
      "pet_special_needs": "string",
      "pet_images": ["url1", "url2", "url3"],

      "pet_owner": {
        "email": "string (required)",
        "first_name": "string",
        "last_name": "string",
        "address_1": "string",
        "address_2": "string",
        "city": "string",
        "state": "string",
        "zip": "string",
        "country": "string",
        "phone": "string",
        "mobile_phone": "string"
      },

      "secondary_contact": {
        "first_name": "string",
        "last_name": "string",
        "email": "string",
        "phone": "string",
        "address_1": "string",
        "address_2": "string",
        "city": "string",
        "state": "string",
        "zip": "string",
        "country": "string"
      },

      "vet_contact": {
        "clinic_name": "string",
        "dr_name": "string",
        "email": "string",
        "phone": "string",
        "address_1": "string",
        "address_2": "string",
        "city": "string",
        "state": "string",
        "zip": "string",
        "country": "string"
      }
    }
  ]
}

Field Reference

Response Format

Production Endpoint Response

{
  "summary": {
    "total": 1,
    "created": 1,
    "updated": 0,
    "skipped": 0,
    "errors": 0
  },
  "details": [
    {
      "status": "success",
      "action": "created",
      "pet_id": 12345,
      "microchip_number": "900141000564647",
      "pet_url": "https://idtag.com/pet/900141000564647/",
      "updated_fields": ["pet_name", "pet_type", "pet_owner", "images"]
    }
  ]
}

Test Endpoint Response

{
  "summary": {
    "total": 1,
    "validated": 1,
    "would_create": 0,
    "would_update": 1,
    "would_skip": 0,
    "errors": 0
  },
  "details": [
    {
      "status": "would_update",
      "message": "Pet would be updated",
      "microchip_number": "900141000564647",
      "pet_id": "2392746",
      "fields_to_update": {...},
      "owner_data": {...}
    }
  ],
  "api_info": {
    "endpoint": "test",
    "note": "This is a test endpoint. No data has been written to the database."
  }
}

Important Notes

1. Microchip Validation

• Microchip numbers must be between 7-15 characters (all SmartTag microchips are 15 digits)
• SmartTag microchips start with: 987, 965,900139, 900141, or 900074
• Third-party microchips require $7.50/chip fee (invoiced monthly)

2. User Data Requirements

• Animals will be created regardless of available owner information
• Without an email address, we cannot send registration emails or account notifications
• Without any owner information, ownership defaults to the implant group

3. Batch Processing & Image Handling

• API processes pets in batches of 10
• Supports multiple image URLs per pet (jpg, png, webp)
• Parallel download processing with 30-second timeout
• First image will be set as the pet's featured image

Error Handling

Best Practices

Testing Workflow

Key Recommendations

• Data Validation: Validate microchip numbers (7-15 characters) and ensure required fields are present
• Error Handling: Maintain logs of failed submissions for retry with exponential backoff
• Image Processing: Use direct URLs that don't require authentication, optimize sizes (max 2MB)
• Rate Limiting: Implement reasonable delays between batch submissions

Code Examples

cURL Example

curl -X POST https://idtag.com/wp-json/pet-api/v1/pets \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "pets": [
      {
        "microchip_number": "900141000564647",
        "pet_name": "Fluffy",
        "pet_type": "Cat",
        "pet_breed": "Domestic Medium Hair",
        "pet_color": "Brown/White",
        "pet_gender": "Male",
        "pet_weight": "8.56",
        "pet_dob": "2024-01-19",
        "pet_owner": {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@example.com",
          "address_1": "123 Main St",
          "city": "Anytown",
          "state": "CA",
          "zip": "12345",
          "country": "United States",
          "phone": "+15551234567"
        }
      }
    ]
  }'

JavaScript (Fetch API) Example

const apiKey = 'your_api_key_here';
const baseUrl = 'https://idtag.com/wp-json/pet-api/v1';

const petData = {
  pets: [{
    microchip_number: '900141000564647',
    pet_name: 'Fluffy',
    pet_type: 'Cat',
    pet_owner: {
      first_name: 'John',
      last_name: 'Doe',
      email: 'john.doe@example.com',
      city: 'Anytown',
      state: 'CA'
    }
  }]
};

fetch(`${baseUrl}/pets`, {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(petData)
})
.then(response => response.json())
.then(data => {
  console.log('Success:', data);
  console.log(`Created: ${data.summary.created}`);
})
.catch(error => console.error('Error:', error));

Python Example

import requests

api_key = 'your_api_key_here'
base_url = 'https://idtag.com/wp-json/pet-api/v1'

headers = {
    'x-api-key': api_key,
    'Content-Type': 'application/json'
}

pet_data = {
    'pets': [{
        'microchip_number': '900141000564647',
        'pet_name': 'Fluffy',
        'pet_type': 'Cat',
        'pet_owner': {
            'first_name': 'John',
            'last_name': 'Doe',
            'email': 'john.doe@example.com',
            'city': 'Anytown',
            'state': 'CA'
        }
    }]
}

response = requests.post(
    f'{base_url}/pets',
    headers=headers,
    json=pet_data
)

if response.status_code == 200:
    result = response.json()
    print(f"Success! Created: {result['summary']['created']}")
else:
    print(f"Error: {response.status_code}")

Support & Contact