• Home
  • FAQ
  • Features
  • Docs
  • About
  • Pricing
Log In
Log InJoin Now

Add New Pets

Create public pet profiles with the PawPlacer API

Use POST /api/pets to create a new pet profile from your own systems. The endpoint validates required fields, maps your status label to the appropriate internal status, and enforces rate limits to protect shelter data.

Request Overview

POST https://pawplacer.com/api/pets
x-api-key: YOUR_API_KEY
Content-Type: application/json
PropertyRequirement
Rate limit10 requests/hour
Authenticationx-api-key header
Body formatJSON

Required Fields

FieldAccepted values
nameAny non-empty string
speciesdog, cat, rabbit
age_categoryyoungest, young, adult, senior
sexmale, female
sizexSmall, small, medium, large, xLarge
statusYour custom status name or label (case-insensitive)
healthunknown, poor, good, great

If the provided status label does not exist, PawPlacer falls back to your default “available” status.

Optional Fields

CategoryFields
Identificationcustom_id, microchip_id
Visualsimage_urls (array of URLs), show_public (boolean)
Demographicsbreed (array), color (array), weight (string), coat_length
Datesintake_date, outcome_date, age_birthday (ISO 8601 strings)
Compatibilitygood_with, bad_with (values listed below)
Behaviortemperaments (values listed below), special_needs (array)
Notesdescription, status_change_notes
Administrationprimary_veterinarian_id (UUID), template_id (UUID)
Financialadoption_fee (string or number)
Custom datacustom_field_data object keyed by field_key

Allowed Compatibility Values

activeLifestyle, cats, disabledMental, disabledPhysical, dogs, families, firstTimeOwners, frequentTravelers, kids, otherPets, outdoorsLiving, sedentaryLifestyle, seniors, smallApartments

Allowed Temperament Values

affectionate, aggressive, cuddly, curious, docile, energetic, fearful, gentle, independent, loyal, mischievous, moody, playful, protective, quiet, rough, shy, smart, social, stubborn, vocal

Custom Fields

  1. Call GET /api/pets/custom-fields.
  2. Use the field_key values returned (not the human-readable label).
  3. Provide values that match each field’s type (text, number, select, etc.).
  4. Invalid keys trigger a 400 response that includes a list of available fields.

Example Request

const response = await fetch('https://pawplacer.com/api/pets', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.PAWPLACER_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Max',
    species: 'dog',
    age_category: 'young',
    sex: 'male',
    size: 'medium',
    status: 'Available',
    health: 'good',
    show_public: true,
    breed: ['Labrador Retriever'],
    good_with: ['families', 'kids'],
    temperaments: ['playful', 'loyal'],
    adoption_fee: 250,
    custom_field_data: {
      favorite_toy: 'Tennis ball'
    }
  })
});

if (!response.ok) {
  throw await response.json();
}

const pet = await response.json();

Success Response

The endpoint returns the newly created pet with normalized data. Status values are resolved to their display label, and arrays are always present even when empty.

{
  "id": "d4738cf8-f31f-453d-a6c1-ba321a845c55",
  "name": "Max",
  "species": "dog",
  "breed": ["Labrador Retriever"],
  "color": [],
  "age_years": null,
  "age_months": null,
  "age_category": "young",
  "sex": "male",
  "size": "medium",
  "status": "Available",
  "health": "good",
  "spayed": false,
  "adoption_fee": "250",
  "microchip_id": null,
  "good_with": ["families", "kids"],
  "bad_with": [],
  "temperaments": ["playful", "loyal"],
  "image_urls": [],
  "coat_length": null,
  "custom_field_data": {
    "favorite_toy": "Tennis ball"
  },
  "custom_id": null,
  "intake_date": null,
  "outcome_date": null,
  "show_public": true,
  "special_needs": [],
  "status_change_notes": null,
  "weight": null,
  "created_at": "2025-07-29T13:34:20.242277+00:00",
  "updated_at": "2025-07-29T13:34:20.242277+00:00"
}

Error Responses

StatusReasonExample Payload
400Missing required fields{ "error": "Missing required fields: name, species" }
400Invalid enumerated value{ "error": "Invalid health. Must be one of: unknown, poor, good, great" }
400Invalid custom field key{ "error": "Invalid custom field keys: favoriteToy", "available_fields": { … } }
401Missing or invalid API key{ "error": "API key required" }
429Rate limit exceeded{ "error": "Rate limit exceeded. Maximum 10 requests per hour." }
500Unexpected server issue{ "error": "Something went wrong" }

Retry only after resolving validation errors or waiting for the rate limit window to reset.

Best Practices

  • Convert numeric fields like adoption_fee to strings if your language does not preserve large numbers automatically.
  • Provide show_public: true when you want the pet to appear in public listings immediately.
  • Call GET /api/pets after creation if you rely on the list endpoint for displays; it reflects the new pet instantly.
PreviousGet Pet DataNextDeveloper API

PawPlacer

© Copyright 2026 PawPlacer. All Rights Reserved.

Contact
  • Email
About
  • About Us
  • Funding Philosophy
  • Careers
  • FAQ
  • Pricing
  • Changelog
Legal
  • Terms of Service
  • Privacy Policy
  • Cookie Policy