API reference

The authoritative reference for the Partner API is the OpenAPI 3 document the API itself serves — it is generated from the running code, so it can never drift from behaviour:

What	Where
Interactive console (Swagger UI, Try it out enabled)	https://api.unitedpetclub.com/docs
OpenAPI document	https://api.unitedpetclub.com/openapi/v1/spec.json
OAuth discovery (RFC 9728; not part of the OpenAPI document)	https://api.unitedpetclub.com/.well-known/oauth-protected-resource — see Discovery metadata

Use the document to generate a client in your language of choice. Every operation carries two extensions you will not find in a generic spec:

• x-required-scope — the scope your application needs (see Authentication).
• x-required-permission — the account-level permission the operation also needs.

The servers entry in the document is whatever origin served it, so a spec fetched from api.unitedpetclub.com targets production.

This page is written by hand

A rendered copy of the reference is not embedded in this site yet — the hosted document above is the reference. This page lists the resource families so you can find your way around.

Conventions shared by every resource

• Paths are /api/{resource}/v1/{collection}; ids are UUIDs.
• Lists accept page (1-based, default 1) and pageSize (1–100, default 20) and return { "data": [...], "pagination": { "page", "pageSize", "total" } }. Out-of-range values are a 400. See Pagination.
• Creates return 201 Created with a Location header pointing at the new resource; deletes return 204 No Content.
• All timestamps are ISO 8601 UTC.
• Errors are application/problem+json — see Errors.

Resource families

Resource	Path prefix	Operations	Scope
Animals	/api/animal/v1/animals	list (filter species), get, create, update (PATCH), archive (DELETE)	animal:read / animal:write
Invoices	/api/billing/v1/platform-invoices, /api/billing/v1/client-invoices (/invoices = platform invoices)	list, get	billing:read
Breeding records	/api/breeding/v1/records	list (filter animalId), get	breeding:read
Messages to clients	/api/communication/v1/messages	send (in-app, to one of the business’s clients)	communication:send
Content items	/api/content/v1/items	list (filter kind), get	content:read
Health records	/api/health/v1/records	list (animalId required), get — a business’s pets only, see below	health:read
Inventory items	/api/inventory/v1/items	list (filter sku), get	inventory:read
Marketplace offers	/api/marketplace/v1/offers (/listings is an alias)	list (filter status, kind, catalogCategoryId), get	marketplace:read
Sales	/api/order/v1/sales (/orders is an alias)	list (filter status), get	order:read
Business profiles	/api/profile/v1/profiles	list (filter kind), get	profile:read
Social channels	/api/social-channel/v1/channels	list (filter provider, status), get	social-channel:read
Social posts	/api/social-publishing/v1/posts	list, get	social-publishing:read
Social engagement	/api/social-engagement/v1/posts/{externalPostId}/metrics, …/channels/{channelId}/threads	latest metrics, threads	social-engagement:read

Business resources

Every resource in the table above acts for the business that connected your app, exactly like the Partner API below:

• The token must come from the authorization-code grant. A token your app gets for itself with client credentials acts for no business and answers 403 0010010000406.
• The business must keep a valid payment card on file (the API is free); without one, 403 0010010000407.
• The business grants the scope on the consent page. Your app declares the scopes it needs when you register it under Account → Developer → Applications, and the consent page offers the business those it declared. The booking scopes work at once; the business-resource scopes (animals, invoices, messages, social and the rest) are offered only after United Pet Club approved a review of your app’s current scopes, so submit the app for review once it declares them (adding a scope later needs a new review). United Pet Club can suspend an app that misuses the API (its tokens then answer 401 0010010000402). An app that registered itself can ask only for the booking scopes of the Partner API.
• You see and change only that business’s data. There is no business or account id to pass, and a resource of another business answers 404, exactly like one that does not exist.

Social resources are the business’s too: the social accounts the business connected and the posts it owns, not those of your developer profile. Connecting or disconnecting a social account and publishing posts happen in the United Pet Club apps, not through this API.

The contracts of 2026-10-18 (every resource above except health records) and the consent scopes for all of them, health:read included, are available: a business can grant them on the consent page, and your app can call them with that business’s token. The Changelog lists what changed on 2026-10-18.

Health records

Health records are medical records, so they are read for a business, about that business’s own pets:

• The token must come from the authorization-code grant: it acts for the business that connected your app, which must keep a valid payment card on file. A token your app gets for itself acts for no business and answers 403 0010010000406; without a card on file, 403 0010010000407.
• The business must own the pet (owner of record or co-owner) or hold full care-circle access to it. Limited access, the kind a groomer or trainer gets, does not include medical records, and a previous owner sees nothing.
• For any other pet, listing its records answers 403 0010010000405, and a record by id answers 404, exactly like a record that does not exist.
• If United Pet Club cannot check the pet at that moment, the call answers 503 0010010000503 with Retry-After; retry later. It never answers records it could not check.

Partner API (a business connected your app)

These routes act for the business whose authorization the token carries; they need a token from the authorization-code grant, and the business must keep a valid payment card on file (they are free; without a card they answer 403 0010010000407). The booking guide walks through them.

Resource	Path (under /api/scheduling/v1)	Operations	Scope
The business	/business	get	scheduling:read
Services	/services	list	scheduling:read
Open slots	/services/{serviceId}/slots	list (from, to; latitude, longitude, postalCode for mobile)	scheduling:read
Booking options	/booking-options	get (serviceId, locale)	scheduling:read
Estimates	/estimate	create	scheduling:read
Appointments	/appointments	list (from, to, state, limit), get, book (Idempotency-Key), …/reschedule, …/cancel	appointment:read / appointment:write
Clients	/clients, /clients/{clientId}, /clients/{clientId}/pets	list (search, page, pageSize), get, pets	client:read
Webhooks	/webhooks	list, get, create, delete, …/rotate-secret, …/enable, …/test, …/deliveries	webhook:manage — see Webhooks

Availability

The contract on this page is what the API exposes and validates today. A family that is not live answers 502 (0010010000502) after authorization succeeds. Confirm availability with Support before building on a family, and watch the Changelog for activation notices.