Developer API

The PawPlacer public API gives you read and write access to pets, adopters, fosters, adoption fees, and contracts so you can power listings, embeds, forms, and partner workflows. Every request requires an API key created in Settings → API and must be issued from a trusted server-side environment.

Pick your integration path

• Use the official JavaScript SDK for typed helpers, caching, and retries.
• Synchronize adoptable pets to your website or mobile app directly via the public API.
• Embed filtered lists (featured pets, species-specific pages, adoption campaigns).
• Create new pet profiles from intake kiosks or partner systems.
• Populate forms with the same custom fields your staff uses internally.
• Run incremental sync jobs using GET /api/pets?updated_since=....
• Create adopter or foster records from external application forms.
• Display adoption fee schedules and terms & conditions on your own website.

Available Endpoints

Pets

People (Adopters & Fosters)

Adoption Fees & Contracts

All endpoints respond with JSON. CORS is enabled so you can proxy requests through your own backend, but never expose your API key to untrusted clients.

Standard API Metadata

Every public endpoint includes:

• X-Request-Id for tracing support issues
• X-Api-Version and X-Generated-At for contract/timing visibility
• X-RateLimit-* headers to expose current limit window state

OpenAPI 3.1 Contract

Use the official OpenAPI contract for language-agnostic integrations, Postman imports, and client generation:

• Spec URL: https://pawplacer.com/openapi/public-api-v1.yaml

Authentication

PawPlacer supports scoped API keys:

• read keys can call all GET endpoints (pets, people, adoption fees, contracts, custom fields)
• write keys can call POST endpoints (POST /api/pets, POST /api/people) plus all read endpoints

Send your API key in the x-api-key header:

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

Missing keys return 401 with { "error": "API key required", "code": "api_key_required", "request_id": "..." }, and invalid keys return 401 with { "error": "Invalid API key", "code": "invalid_api_key", "request_id": "..." }.

Handling Rate Limits

The API enforces rate limits per API key and endpoint. When a limit is hit you receive 429 and a descriptive JSON error. Best practices:

1. Cache responses for at least 5–10 minutes.
2. Batch frontend requests through your server.
3. Use background jobs to refresh data instead of polling from client devices.

Quick Start Workflow

1. Generate an API key in Settings → API.
2. Call GET /api/pets with the key to render public listings.
3. Call GET /api/people?type=adopter to fetch your adopter records.
4. Fetch GET /api/pets/custom-fields or GET /api/people/custom-fields?type=adopter to learn valid field_key values.
5. Create records via POST /api/pets or POST /api/people when you need to push data into PawPlacer.
6. Fetch GET /api/adoption-fees and GET /api/contracts?type=adopter to display fee schedules and agreements.

Example Requests

const headers = { 'x-api-key': process.env.PAWPLACER_API_KEY };

// List adoptable dogs
const dogs = await fetch('https://pawplacer.com/api/pets?species=dog&status=available&limit=8', { headers }).then(r => r.json());

// Fetch a single pet
const pet = await fetch(`https://pawplacer.com/api/pets/${dogs.pets[0].id}`, { headers }).then(r => r.json());

// List active adopters
const adopters = await fetch('https://pawplacer.com/api/people?type=adopter&status=active', { headers }).then(r => r.json());

// Create an adopter
const newAdopter = await fetch('https://pawplacer.com/api/people', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({ type: 'adopter', name: 'Jane Smith', email: 'jane@example.com' })
}).then(r => r.json());

// Fetch adoption fee rules
const fees = await fetch('https://pawplacer.com/api/adoption-fees', { headers }).then(r => r.json());

// Fetch adoption contract (markdown)
const contract = await fetch('https://pawplacer.com/api/contracts?type=adopter', { headers }).then(r => r.json());

Security Checklist

• Keep API keys in environment variables or secret managers.
• Proxy requests through your own backend when serving public sites.
• Rotate keys immediately if you suspect they were exposed.
• Respect rate limits and handle error responses gracefully.

Next Steps

• Follow the detailed GET guide for response formats and error handling.
• Review the POST guide to understand required fields and validation for pet and people creation.
• Visit Settings → API to create, rotate, or revoke scoped keys for each integration.