Get Data

Use the PawPlacer public API to fetch pet data, adopter/foster records, adoption fee rules, and contract terms. All endpoints require an API key sent in the x-api-key header.

Endpoint Summary

Cache responses for at least a few minutes to stay well below the hourly limits. The payloads are stable and work well with server-side or per-process caching.

OpenAPI 3.1 contract: https://pawplacer.com/openapi/public-api-v1.yaml

Standard Response Headers

All public GET endpoints include diagnostic and rate-limit headers:

• X-Request-Id — unique request identifier for support/debugging
• X-Api-Version — current public API contract version
• X-Generated-At — response generation timestamp (ISO-8601)
• X-RateLimit-Limit — endpoint hourly limit
• X-RateLimit-Remaining — remaining calls in current window (-1 when unavailable)
• X-RateLimit-Reset — Unix timestamp for next limit reset window
• Retry-After — present on 429 responses

GET /api/pets – List Public Pets

Returns a paginated list of public pets with a full pet profile payload (including custom fields and metadata).

Request

GET https://pawplacer.com/api/pets
x-api-key: YOUR_API_KEY

Optional query parameters

• limit — 1–100 (default 20)
• offset — results to skip (default 0)
• species — dog, cat, or rabbit
• status — matches your custom status labels (case-insensitive)
• search — fuzzy match on name, description, and breed values
• updated_since — ISO-8601 timestamp; returns only pets with updated_at >= updated_since

JavaScript example

const response = await fetch('https://pawplacer.com/api/pets?status=available&species=dog&limit=12', {
  headers: { 'x-api-key': process.env.PAWPLACER_API_KEY }
});

const { pets, total, hasMore } = await response.json();

Response

{
  "pets": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Max",
      "species": "dog",
      "status": "Available",
      "health": "good",
      "show_public": true,
      "breed": ["Labrador Retriever"],
      "color": ["Black"],
      "age_category": "young",
      "age_years": null,
      "age_months": null,
      "age_birthday": null,
      "sex": "male",
      "size": "medium",
      "description": "Friendly and energetic dog",
      "spayed": true,
      "adoption_fee": "250",
      "microchip_id": null,
      "good_with": ["families", "kids"],
      "bad_with": [],
      "temperaments": ["playful", "social"],
      "image_urls": [
        "https://pawplacer.com/pets/max.jpg",
        "https://pawplacer.com/pets/max-2.jpg"
      ],
      "image_url": "https://pawplacer.com/pets/max.jpg",
      "coat_length": "short",
      "custom_id": "EXT-1001",
      "custom_field_data": {
        "favorite_toy": "Tennis ball"
      },
      "intake_date": null,
      "outcome_date": null,
      "primary_veterinarian": "Downtown Vet Clinic",
      "special_needs": [],
      "tags": ["Senior", "Special Care"],
      "status_change_notes": null,
      "weight": null,
      "adopted_on": null,
      "adopted_by": "Jane Foster",
      "created_at": "2026-02-17T12:00:00.000000+00:00",
      "updated_at": "2026-02-17T12:00:00.000000+00:00"
    }
  ],
  "total": 42,
  "limit": 12,
  "offset": 0,
  "hasMore": true
}

Fields returned

• pets — array of public pets. Each object includes a full profile payload:
  • Core: id, name, species, status, health, show_public
  • Demographics: breed, color, age_category, age_years, age_months, age_birthday, sex, size, weight, spayed
  • Behavior/compatibility: good_with, bad_with, temperaments, special_needs
  • Tags: tags (pet tag labels)
  • Identifiers: custom_id, microchip_id
  • Notes + dates: description, intake_date, outcome_date, status_change_notes
  • Relationships (resolved names): primary_veterinarian, adopted_by
  • Media: image_urls, image_url, coat_length
  • Custom data: custom_field_data
  • Metadata: created_at, updated_at, adopted_on
• total, limit, offset, hasMore — pagination metadata

GET /api/pets/{petId} – Single Pet

Fetch a single public pet by ID. This endpoint returns the same field set as the list endpoint.

Request

GET https://pawplacer.com/api/pets/{petId}
x-api-key: YOUR_API_KEY

JavaScript example

const response = await fetch(`https://pawplacer.com/api/pets/${petId}`, {
  headers: { 'x-api-key': process.env.PAWPLACER_API_KEY }
});

const pet = await response.json();

If the pet is not public, deleted, or does not exist, the API responds with 404 and { "error": "Pet not found" }.

GET /api/pets/custom-fields – Custom Field Metadata

Retrieve configured custom form fields so you can send valid keys when creating pets.

Request

GET https://pawplacer.com/api/pets/custom-fields
x-api-key: YOUR_API_KEY

Response

{
  "custom_fields": [
    {
      "field_key": "favorite_toy",
      "label": "Favorite Toy",
      "field_type": "text",
      "required": false,
      "help_text": "Include any comfort objects",
      "options": null,
      "section": "Behavior"
    }
  ]
}

Use the field_key (not the label) when populating custom_field_data in POST /api/pets requests.

Rate Limit Errors

Rate limits are enforced per API key and endpoint on the current hourly window. If the limit is exceeded, the response is 429 with a descriptive error payload, for example:

{
  "error": "Rate limit exceeded. Maximum 100 requests per hour. Cache responses to avoid throttling.",
  "code": "rate_limited",
  "request_id": "3dfabc8f-3f6f-4f4e-bffe-5d0dc5292e6f"
}

Reduce the frequency of calls or increase your cache window before retrying.

Error Reference

Always handle non-200 status codes and back off when you see 429 responses.

GET /api/people – List Adopters or Fosters

Returns a paginated list of adopters or fosters. The type query parameter is required.

Request

GET https://pawplacer.com/api/people?type=adopter
x-api-key: YOUR_API_KEY

Query parameters

• type — required: adopter or foster
• limit — 1–100 (default 20)
• offset — results to skip (default 0)
• status — filter by status (e.g. active, pending)
• search — fuzzy match on name, email, phone
• updated_since — ISO-8601 timestamp

Response

{
  "type": "adopter",
  "people": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "adopter",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "555-0100",
      "address": "123 Main St",
      "status": "active",
      "status_change_notes": null,
      "custom_field_data": {},
      "tags": ["VIP"],
      "capacity": null,
      "created_at": "2026-03-01T10:00:00.000000+00:00",
      "updated_at": "2026-03-01T10:00:00.000000+00:00"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0,
  "hasMore": false
}

GET /api/people/{id} – Single Adopter or Foster

GET https://pawplacer.com/api/people/{id}?type=adopter
x-api-key: YOUR_API_KEY

Returns the same person object shape as the list endpoint. The type parameter is required. Invalid UUIDs return 400. Missing records return 404.

GET /api/people/custom-fields – People Form Fields

GET https://pawplacer.com/api/people/custom-fields?type=adopter
x-api-key: YOUR_API_KEY

Response

{
  "type": "adopter",
  "custom_fields": [
    {
      "field_key": "has_yard",
      "label": "Has Yard",
      "field_type": "boolean",
      "required": false,
      "help_text": null,
      "options": null,
      "section": "Housing"
    }
  ]
}

Use the field_key values when populating custom_field_data in POST /api/people requests.

GET /api/adoption-fees – Fee Configuration

Returns the account's adoption fee rules. Each rule maps a species + attribute combination to a dollar adjustment.

GET https://pawplacer.com/api/adoption-fees
x-api-key: YOUR_API_KEY

Response

{
  "fees": [
    {
      "species": "dog",
      "attribute_type": "age",
      "attribute_value": "youngest",
      "adjustment": 350
    },
    {
      "species": "dog",
      "attribute_type": "health",
      "attribute_value": "poor",
      "adjustment": -50
    }
  ]
}

Pet responses also include a global_adoption_fee field (number or null) that resolves these rules against each pet's attributes when no manual fee override is set.

GET /api/contracts – Terms & Conditions

Returns the terms & conditions content for a given contract type. Content is markdown.

GET https://pawplacer.com/api/contracts?type=adopter
x-api-key: YOUR_API_KEY

Response

{
  "type": "adopter",
  "content": "# Adoption Agreement\n\nBy signing this agreement...",
  "updated_at": "2026-01-15T00:00:00.000000+00:00"
}

Valid types: adopter, foster, volunteer, surrender. Returns empty content and null updated_at if no contract is configured.