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
| Property | Requirement |
|---|---|
| Rate limit | 10 requests/hour |
| Authentication | x-api-key header |
| Body format | JSON |
Required Fields
| Field | Accepted values |
|---|---|
name | Any non-empty string |
species | dog, cat, rabbit |
age_category | youngest, young, adult, senior |
sex | male, female |
size | xSmall, small, medium, large, xLarge |
status | Your custom status name or label (case-insensitive) |
health | unknown, poor, good, great |
If the provided status label does not exist, PawPlacer falls back to your default “available” status.
Optional Fields
| Category | Fields |
|---|---|
| Identification | custom_id, microchip_id |
| Visuals | image_urls (array of URLs), show_public (boolean) |
| Demographics | breed (array), color (array), weight (string), coat_length |
| Dates | intake_date, outcome_date, age_birthday (ISO 8601 strings) |
| Compatibility | good_with, bad_with (values listed below) |
| Behavior | temperaments (values listed below), special_needs (array) |
| Notes | description, status_change_notes |
| Administration | primary_veterinarian_id (UUID), template_id (UUID) |
| Financial | adoption_fee (string or number) |
| Custom data | custom_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
- Call
GET /api/pets/custom-fields. - Use the
field_keyvalues returned (not the human-readable label). - Provide values that match each field’s type (text, number, select, etc.).
- 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
| Status | Reason | Example Payload |
|---|---|---|
| 400 | Missing required fields | { "error": "Missing required fields: name, species" } |
| 400 | Invalid enumerated value | { "error": "Invalid health. Must be one of: unknown, poor, good, great" } |
| 400 | Invalid custom field key | { "error": "Invalid custom field keys: favoriteToy", "available_fields": { … } } |
| 401 | Missing or invalid API key | { "error": "API key required" } |
| 429 | Rate limit exceeded | { "error": "Rate limit exceeded. Maximum 10 requests per hour." } |
| 500 | Unexpected 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_feeto strings if your language does not preserve large numbers automatically. - Provide
show_public: truewhen you want the pet to appear in public listings immediately. - Call
GET /api/petsafter creation if you rely on the list endpoint for displays; it reflects the new pet instantly.