Create Records

Use POST /api/pets to create pet profiles and POST /api/people to create adopter or foster records from your own systems. Both endpoints validate required fields, enforce rate limits, and support idempotency keys for safe retries.

Request Overview

POST https://pawplacer.com/api/pets
x-api-key: YOUR_API_KEY
Content-Type: application/json

Required Fields

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

Optional Fields

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"
}

Idempotency

Use an Idempotency-Key header when your integration may retry the same create request. PawPlacer will replay the original successful response for the same key and payload, and it will reject the request with 409 idempotency_conflict if the same key is reused with a different body.

Error Responses

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.

---

POST /api/people – Create Adopter or Foster

POST https://pawplacer.com/api/people
x-api-key: YOUR_API_KEY
Content-Type: application/json

Required Fields

Optional Fields

Example Request

const response = await fetch('https://pawplacer.com/api/people', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.PAWPLACER_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'adopter',
    name: 'Jane Smith',
    email: 'jane@example.com',
    phone: '555-0100',
    address: '123 Main St',
    custom_field_data: {
      has_yard: true
    }
  })
});

const adopter = await response.json();

Success Response

New records are created with status: "pending" by default. The response includes all person fields:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "adopter",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "555-0100",
  "address": "123 Main St",
  "status": "pending",
  "status_change_notes": null,
  "custom_field_data": { "has_yard": true },
  "tags": [],
  "capacity": null,
  "created_at": "2026-04-10T10:00:00.000000+00:00",
  "updated_at": "2026-04-10T10:00:00.000000+00:00"
}

Idempotency

Use an Idempotency-Key header for safe retries, same behavior as POST /api/pets.

Error Responses