Create and Update Records

Use POST /api/pets to create pet profiles, PATCH /api/pets/{petIdentifier} to update existing pet profiles, and POST /api/people to create adopter or foster records from your own systems. These endpoints require a Write + read key from Settings > SDK & API, validate fields, enforce rate limits, and support idempotency keys for safe retries.

Request Overview

POST https://pawplacer.com/api/pets
PATCH https://pawplacer.com/api/pets/{petIdentifier}
POST https://pawplacer.com/api/people
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.) in create or update payloads.
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.
• Keep the PawPlacer id returned from create responses when possible; updates accept either that UUID or an assigned custom_id in PATCH /api/pets/{petIdentifier}.
• Use custom_id for external de-duplication and website-to-PawPlacer record matching. Duplicate custom_id values are rejected on create and update.
• Call GET /api/pets after creation or update if you rely on the list endpoint for displays. The list only includes non-deleted pets with show_public: true and a public or unset custom status.

PATCH /api/pets/{petIdentifier} – Update an Existing Pet

PATCH https://pawplacer.com/api/pets/{petIdentifier}
x-api-key: YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: website-pet-sync:DOG-2026-001:2026-06-10

Use either the PawPlacer pet UUID returned from POST /api/pets or an assigned custom_id. If a route value could match both a UUID and a custom_id, PawPlacer treats it as a UUID first.

Send only the fields that should change. At least one field is required. Common supported fields include:

const response = await fetch(`https://pawplacer.com/api/pets/${externalDogId}`, {
  method: 'PATCH',
  headers: {
    'x-api-key': process.env.PAWPLACER_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': `website-pet-sync:${externalDogId}:${updatedAt}`
  },
  body: JSON.stringify({
    description: 'Updated bio from the website CMS.',
    status: 'Available',
    image_urls: ['https://example.org/dogs/max-1.jpg'],
    age_years: '4',
    show_public: true,
    custom_id: externalDogId,
    custom_field_data: {
      favorite_toy: 'Tennis ball'
    }
  })
});

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

const pet = await response.json();

The response is the updated pet payload. The same Idempotency-Key and identical payload replay the original successful response. Reusing the key with a different payload returns 409 idempotency_conflict.

---

POST /api/people – Create Adopter or Foster

Use this endpoint from a trusted server when your existing website forms should create applicant records in PawPlacer instead of embedding PawPlacer's built-in forms.

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