Main Content

API Calls

Introduction

The Petfinder API (Application Programming Interface) allows you to access the Petfinder database of hundreds of thousands of pets ready for adoption and over ten thousand animal welfare organizations. You can use the API to build your own dynamic websites or applications backed by the same data used on Petfinder.com.

Capabilities

With the Petfinder API, you can:

  • Search for and display pet listings based on pet characteristics, location, and status.
  • Search for and display animal welfare organizations based on organization name, ID, and location.

You can, for example, display a random selection of available pets on a webpage; set up pages to display pets in various categories; allow visitors to your site to search for adoptable pets based on a number of criteria; or display profiles of local organizations.

Using the API

This is a RESTful API, meaning that it uses predictable URLs to access resources and, in case of an error, returns meaningful HTTP response codes. This enables the use of GET, POST, and HTTP authentication, which standard HTTP clients understand. The API supports cross-origin resource sharing, which allows you to use it securely from a client-side web application. You use the API by sending requests with a specific structure to our servers. In order to maintain security, it uses access tokens for API requests.

Getting Authenticated

The Petfinder API uses OAuth for secure authentication.

In order to begin, you need:

  • A Petfinder account; if you do not have one, create an account.
  • A Petfinder API Key (otherwise called Client ID) and Secret. (Visit www.petfinder.com/developers to request one.)
  • A way of sending requests to our server along with information that will tell it you are allowed to do so. We recommend cURL for testing.

Once you have your API Key and your Secret, you can use these to request an access token. This token will enable you to receive information from our servers.

To get a token, make the following request, replacing {CLIENT-ID} and {CLIENT-SECRET} with your own information:

curl -d "grant_type=client_credentials&client_id={CLIENT-ID}&client_secret={CLIENT-SECRET}" https://api.petfinder.com/v2/oauth2/token

The server will send back a response in this format:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "..."
}

Breaking this down:

  • The "token_type" value of "Bearer" means the server will not expect other identification along with the token; it is sufficient alone.
  • The "expires_in" gives the time in seconds the token may be used; after this, your system must request a new one and use that.
  • The "access_token" is the token itself. You’ll need to have your system store this as a variable and include it in the header of every API request until it expires and you request another.

Request Structure

The API is accessed through GET requests following this overall pattern:

curl -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" GET https://api.petfinder.com/v2/{CATEGORY}/{ACTION}?{parameter_1}={value_1}&{parameter_2}={value_2}

Placeholder values—shown within curly braces—should be replaced by your own values, without braces.

Breaking this down:

  • The request begins with the initial cURL command.
  • The -H indicates that it includes header information (used for authentication) which follows within double quotes.
  • It then indicates that this is a GET request and gives the base URL of the request, followed by any path parameters separated by slashes.
  • It finishes with an optional query string consisting of a question mark followed by parameter/value pairs separated by ampersands (e.g. ?size=small&coat=long). Query parameters are optional.

Responses are returned in JSON format, along with a header containing a status code (200 for OK; various others to indicate errors) and time remaining on your access token.

> curl -H "Authorization: Bearer eyJ0eXA..." https://api.petfinder.com/v2/animals?type=dog&page=2
{
    "animals": [
        {
            "id": 120,
            "organization_id": "NJ333",
            "url": "https://www.petfinder.com/dog/spot-120/nj/jersey-city/nj333-petfinder-test-account/?referrer_id=d7e3700b-2e07-11e9-b3f3-0800275f82b1",
            "type": "Dog",
            "species": "Dog",
            "breeds": {
                "primary": "Akita",
                "secondary": null,
                "mixed": false,
                "unknown": false
            },
            "colors": {
                "primary": null,
                "secondary": null,
                "tertiary": null
            },
            "age": "Young",
            "gender": "Male",
            "size": "Medium",
            "coat": null,
            "attributes": {
                "spayed_neutered": false,
                "house_trained": true,
                "declawed": null,
                "special_needs": true,
                "shots_current": false
            },
            "environment": {
                "children": false,
                "dogs": false,
                "cats": false
            },
            "tags": [
                "Cute",
                "Intelligent",
                "Large",
                "Playful",
                "Happy",
                "Affectionate"
            ],
            "name": "Spot",
            "description": "Spot is an amazing dog",
            "photos": [
                {
                    "small": "https://photos.petfinder.com/photos/pets/42706540/1/?bust=1546042081&width=100",
                    "medium": "https://photos.petfinder.com/photos/pets/42706540/1/?bust=1546042081&width=300",
                    "large": "https://photos.petfinder.com/photos/pets/42706540/1/?bust=1546042081&width=600",
                    "full": "https://photos.petfinder.com/photos/pets/42706540/1/?bust=1546042081"
                }
            ],
            "videos": [
                {
                    "embed": "<iframe src=\"https://www.youtube.com/embed/xaXbs1fRFRM\" frameborder=\"0\" allowfullscreen></iframe>"
                }
            ],
            "status": "adoptable",
            "published_at": "2018-12-22T20:31:32+0000",
            "contact": {
                "email": "petfindertechsupport@gmail.com",
                "phone": "111-333-5555, 222-333-5555, 333-333-5353, 111-333-2222",
                "address": {
                    "address1": "Test address 1",
                    "address2": "Test address 2",
                    "city": "Jersey City",
                    "state": "NJ",
                    "postcode": "07097",
                    "country": "US"
                }
            },
            "_links": {
                "self": {
                    "href": "/v2/animals/120"
                },
                "type": {
                    "href": "/v2/types/dog"
                },
                "organization": {
                    "href": "/v2/organizations/nj333"
                }
            }
        }
    ],
    "pagination": {
        "count_per_page": 20,
        "total_count": 1,
        "current_page": 1,
        "total_pages": 1,
        "_links": {
            "previous": {
                "href": "/v2/animals?type=dog&page=1"
            },
            "next": {
                "href": "/v2/animals?type=dog&page=3"
            }
        }
    }
}

Errors

When working with the API, you may run into errors. To allow your integration to handle these errors gracefully, we use RFC 7807 to provide a consistent response.

General Errors

ERR-401

Access was denied due to invalid credentials. This could be an invalid API key/secret combination, missing access token, or expired access token.

ERR-403

Access denied due to insufficient access.

ERR-404

The requested resource was not found.

ERR-500

The request ran into an unexpected error. If the problem persists, please contact support.

ERR-00001

The request has missing parameters.

ERR-00002

Your request contains invalid parameters.

This response will also include a "invalid-params" array that includes all invalid parameters allowing you to use this information to fix the parameters and try again.

Each invalid parameter includes the location of the parameter using the "in" key (e.g. "query" for a query parameter), the parameter name ("path"), and a message on why it's invalid.

Example

{
    "type": "https://www.petfinder.com/developers/v2/docs/errors/ERR-00002/",
    "status": 400,
    "title": "Invalid Request",
    "detail": "The request contains invalid parameters.",
    "invalid-params": [
        {
            "in": "query",
            "path": "type",
            "message": "test is not a valid animal type."
        }
    ]
}

Endpoints

An "endpoint" is the URL, often including path and query parameters, that you send a request to in order to receive the data you're looking for. The endpoints are organized into broad categories based on the type of information they provide.

Animal

Get Animals

Returns one "page" of details (defaulting to the first 20 results) on a group of animals based on criteria given in the parameters.

If a location query is not given, the animal distance property will be null. Otherwise the distance is distance from the location parameter in miles.

Base Call

GET https://api.petfinder.com/v2/animals

Query Parameters

Name Description Type Values
type Return results matching animal type string Possible values may be looked up via Get Animal Types.
breed Return results matching animal breed string Accepts multiple values, e.g. breed=pug,samoyed. Possible values may be looked up via Get Animal Breeds below.
size Return results matching animal size string small, medium, large, xlarge Accepts multiple values, e.g. size=large,xlarge.
gender Return results matching animal gender string male, female, unknown Accepts multiple values, e.g. gender=male,female.
age Return results matching animal age string baby, young, adult, senior Accepts multiple values, e.g. age=baby,senior.
color Return results matching animal color string Possible values may be looked up via Get Animal Types.
coat Return results matching animal coat string short, medium, long, wire, hairless, curly Accepts multiple values, e.g. coat=wire,curly.
status Return results matching adoption status string adoptable, adopted, found Accepts multiple values (default: adoptable)
name Return results matching animal name (includes partial matches; e.g. "Fred" will return "Alfredo" and "Frederick") string
organization Return results associated with specific organization(s) string Accepts multiple values, e.g. organization=[ID1],[ID2].
good_with_children Return results that are good with children boolean Can be true, false, 1, or 0
good_with_dogs Return results that are good with dogs boolean Can be true, false, 1, or 0
good_with_cats Return results that are good with cats boolean Can be true, false, 1, or 0
house_trained Return results that are house trained boolean Can be true or 1 only
declawed Return results that are declawed boolean Can be true or 1 only
special_needs Return results that have special needs boolean Can be true or 1 only
location Return results by location. string city, state; latitude,longitude; or postal code.
distance Return results within distance of location (in miles). integer Requires location to be set (default: 100, max: 500)
before Return results published before this date/time. string Must be a valid ISO8601 date-time string (e.g. 2019-10-07T19:13:01+00:00)
after Return results published after this date/time. string Must be a valid ISO8601 date-time string (e.g. 2019-10-07T19:13:01+00:00)
sort Attribute to sort by; leading dash requests a reverse-order sort string recent, -recent, distance, -distance, random (default: recent)
page Specifies which page of results to return integer (default: 1)
limit Maximum number of results to return per 'page' response integer (default: 20, max: 100)

Example Response

{
    "animals": [
        {
            "id": 124,
            "organization_id": "NJ333",
            "url": "https://www.petfinder.com/cat/nebula-124/nj/jersey-city/nj333-petfinder-test-account/?referrer_id=d7e3700b-2e07-11e9-b3f3-0800275f82b1",
            "type": "Cat",
            "species": "Cat",
            "breeds": {
                "primary": "American Shorthair",
                "secondary": null,
                "mixed": false,
                "unknown": false
            },
            "colors": {
                "primary": "Tortoiseshell",
                "secondary": null,
                "tertiary": null
            },
            "age": "Young",
            "gender": "Female",
            "size": "Medium",
            "coat": "Short",
            "name": "Nebula",
            "description": "Nebula is a shorthaired, shy cat. She is very affectionate once she warms up to you.",
            "photos": [
                {
                    "small": "https://photos.petfinder.com/photos/pets/124/1/?bust=1546042081&width=100",
                    "medium": "https://photos.petfinder.com/photos/pets/124/1/?bust=1546042081&width=300",
                    "large": "https://photos.petfinder.com/photos/pets/124/1/?bust=1546042081&width=600",
                    "full": "https://photos.petfinder.com/photos/pets/124/1/?bust=1546042081"
                }
            ],
            "videos": [
                {
                    "embed": "<iframe src=\"https://www.youtube.com/embed/xaXbs1fRFRM\" frameborder=\"0\" allowfullscreen></iframe>"
                }
            ],
            "status": "adoptable",
            "attributes": {
                "spayed_neutered": true,
                "house_trained": true,
                "declawed": false,
                "special_needs": false,
                "shots_current": true
            },
            "environment": {
                "children": false,
                "dogs": true,
                "cats": true
            },
            "tags": [
                "Cute",
                "Intelligent",
                "Playful",
                "Happy",
                "Affectionate"
            ],
            "contact": {
                "email": "petfindertechsupport@gmail.com",
                "phone": "555-555-5555",
                "address": {
                    "address1": null,
                    "address2": null,
                    "city": "Jersey City",
                    "state": "NJ",
                    "postcode": "07097",
                    "country": "US"
                }
            },
            "published_at": "2018-09-04T14:49:09+0000",
            "distance": 0.4095,
            "_links": {
                "self": {
                    "href": "/v2/animals/124"
                },
                "type": {
                    "href": "/v2/types/cat"
                },
                "organization": {
                    "href": "/v2/organizations/nj333"
                }
            }
        }
    ],
    "pagination": {
        "count_per_page": 20,
        "total_count": 320,
        "current_page": 1,
        "total_pages": 16,
        "_links": {}
    }
}

Get Animal

Returns details on the specified animal based on ID.

Base Call

GET https://api.petfinder.com/v2/animals/{id}

Path Parameters

Name Description Type Values
id Animal ID integer Animal ID

Example Response

{
    "animal": {
            "id": 124,
            "organization_id": "NJ333",
            "url": "https://www.petfinder.com/cat/nebula-124/nj/jersey-city/nj333-petfinder-test-account/?referrer_id=d7e3700b-2e07-11e9-b3f3-0800275f82b1",
            "type": "Cat",
            "species": "Cat",
            "breeds": {
                "primary": "American Shorthair",
                "secondary": null,
                "mixed": false,
                "unknown": false
            },
            "colors": {
                "primary": "Tortoiseshell",
                "secondary": null,
                "tertiary": null
            },
            "age": "Young",
            "gender": "Female",
            "size": "Medium",
            "coat": "Short",
            "name": "Nebula",
            "description": "Nebula is a shorthaired, shy cat. She is very affectionate once she warms up to you.",
            "photos": [
                {
                    "small": "https://photos.petfinder.com/photos/pets/124/1/?bust=1546042081&width=100",
                    "medium": "https://photos.petfinder.com/photos/pets/124/1/?bust=1546042081&width=300",
                    "large": "https://photos.petfinder.com/photos/pets/124/1/?bust=1546042081&width=600",
                    "full": "https://photos.petfinder.com/photos/pets/124/1/?bust=1546042081"
                }
            ],
            "videos": [
                {
                    "embed": "<iframe src=\"https://www.youtube.com/embed/xaXbs1fRFRM\" frameborder=\"0\" allowfullscreen></iframe>"
                }
            ],
            "status": "adoptable",
            "attributes": {
                "spayed_neutered": true,
                "house_trained": true,
                "declawed": false,
                "special_needs": false,
                "shots_current": true
            },
            "environment": {
                "children": false,
                "dogs": true,
                "cats": true
            },
            "tags": [
                "Cute",
                "Intelligent",
                "Playful",
                "Happy",
                "Affectionate"
            ],
            "contact": {
                "email": "petfindertechsupport@gmail.com",
                "phone": "555-555-5555",
                "address": {
                    "address1": null,
                    "address2": null,
                    "city": "Jersey City",
                    "state": "NJ",
                    "postcode": "07097",
                    "country": "US"
                }
            },
            "published_at": "2018-09-04T14:49:09+0000",
            "distance": null,
            "_links": {
                "self": {
                    "href": "/v2/animals/124"
                },
                "type": {
                    "href": "/v2/types/cat"
                },
                "organization": {
                    "href": "/v2/organizations/nj333"
                }
            }
        }
}

Get Animal Types

Returns an array of animal types. This provides the possible values for the "type" parameter, covering species, color, coat, and gender.

Base Call

GET https://api.petfinder.com/v2/types

No Parameters

Example Response

{
    "types": [
        {
            "name": "Rabbit",
            "coats": [
                "Short",
                "Long"
            ],
            "colors": [
                "Agouti",
                "Black",
                "Blue / Gray",
                "Brown / Chocolate",
                "Cream",
                "Lilac",
                "Orange / Red",
                "Sable",
                "Silver Marten",
                "Tan",
                "Tortoiseshell",
                "White"
            ],
            "genders": [
                "Male",
                "Female"
            ],
            "_links": {
                "self": {
                    "href": "/v2/types/rabbit"
                },
                "breeds": {
                    "href": "/v2/types/rabbit/breeds"
                }
            }
        },
        {
            "name": "Bird",
            "coats": [],
            "colors": [
                "Black",
                "Blue",
                "Brown",
                "Buff",
                "Gray",
                "Green",
                "Olive",
                "Orange",
                "Pink",
                "Purple / Violet",
                "Red",
                "Rust / Rufous",
                "Tan",
                "White",
                "Yellow"
            ],
            "genders": [
                "Male",
                "Female",
                "Unknown"
            ],
            "_links": {
                "self": {
                    "href": "/v2/types/bird"
                },
                "breeds": {
                    "href": "/v2/types/bird/breeds"
                }
            }
        }
    ]
}

Get A Single Animal Type

Returns information on a single animal type.

Base Call

GET https://api.petfinder.com/v2/types/{type}

Path Parameters

Name Description Type Values
type Animal Type string Possible values may be looked up via Get Animal Types.

Responses

{
    "type": {
        "name": "Dog",
        "coats": [
            "Hairless",
            "Short",
            "Medium",
            "Long",
            "Wire",
            "Curly"
        ],
        "colors": [
            "Apricot / Beige",
            "Bicolor",
            "Black",
            "Brindle",
            "Brown / Chocolate",
            "Golden",
            "Gray / Blue / Silver",
            "Harlequin",
            "Merle (Blue)",
            "Merle (Red)",
            "Red / Chestnut / Orange",
            "Sable",
            "Tricolor (Brown, Black, & White)",
            "White / Cream",
            "Yellow / Tan / Blond / Fawn"
        ],
        "genders": [
            "Male",
            "Female"
        ],
        "_links": {
            "self": {
                "href": "/v2/types/dog"
            },
            "breeds": {
                "href": "/v2/types/dog/breeds"
            }
        }
    }
}

Get Animal Breeds

Returns possible breed values for a given animal type

Base Call

GET https://api.petfinder.com/v2/types/{type}/breeds

Path Parameters

Name Description Type Values
type Animal Type string Possible values may be looked up via Get Animal Types.

Example Response

{
    "breeds": [
        {
            "name": "Affenpinscher",
            "_links": {
                "type": {
                    "href": "/v2/types/dog"
                }
            }
        }
    ]
}

Organization

Get Organizations

Returns details on a group of organizations based on criteria given in parameters.

If a location query is not given, the organization distance property will be null. Otherwise the distance is distance from the location parameter in miles.

Base Call

GET https://api.petfinder.com/v2/organizations

Query Parameters

Name Description Type Values
name Return results matching organization name string
location Return results by location. string city, state; latitude,longitude; or postal code.
distance Return results within distance of location (in miles). integer requires location to be set (default: 100, max: 500)
state Filter results by state string Accepts two-letter abbreviations, e.g. AL, WY
country Filter results by country. string Accepts two-letter abbreviations, e.g. US, CA
query Search on name, city, state (Search that includes synonyms, varying punctuation, etc.) string
sort Field to sort by; leading dash requests a reverse-order sort string distance, -distance, name, -name, country, -country, state, -state
limit Maximum number of results to return integer (default: 20, max: 100)
page Page of results to return integer (default: 1)

Example Response

{
    "organizations": [
        {
            "id": "NJ333",
            "name": "NJ333 - Petfinder Test Account",
            "email": "no-reply@petfinder.com",
            "phone": "555-555-5555",
            "address": {
                "address1": "Test address 1",
                "address2": "Test address 2",
                "city": "Jersey City",
                "state": "NJ",
                "postcode": "07097",
                "country": "US"
            },
            "hours": {
                "monday": null,
                "tuesday": null,
                "wednesday": null,
                "thursday": null,
                "friday": null,
                "saturday": null,
                "sunday": null
            },
            "url": "https://www.petfinder.com/member/us/nj/jersey-city/nj333-petfinder-test-account/?referrer_id=d7e3700b-2e07-11e9-b3f3-0800275f82b1",
            "website": null,
            "mission_statement": null,
            "adoption": {
                "policy": null,
                "url": null
            },
            "social_media": {
                "facebook": null,
                "twitter": null,
                "youtube": null,
                "instagram": null,
                "pinterest": null
            },
            "photos": [
                {
                    "small": "https://photos.petfinder.com/photos/organizations/124/1/?bust=1546042081&width=100",
                    "medium": "https://photos.petfinder.com/photos/organizations/124/1/?bust=1546042081&width=300",
                    "large": "https://photos.petfinder.com/photos/organizations/124/1/?bust=1546042081&width=600",
                    "full": "https://photos.petfinder.com/photos/organizations/124/1/?bust=1546042081"
                }
            ],
            "distance": 0.4095,
            "_links": {
                "self": {
                    "href": "/v2/organizations/nj333"
                },
                "animals": {
                    "href": "/v2/animals?organization=nj333"
                }
            }
        }
    ],
    "pagination": {
        "count_per_page": 20,
        "total_count": 1,
        "current_page": 1,
        "total_pages": 2,
        "_links": {
            "next": {
                "href": "/v2/organizations?page=2"
            }
        }
    }
}

Get Organization

Returns details on a single organization based on ID.

Base Call

GET https://api.petfinder.com/v2/organizations/{id}

Path Parameters

Name Description Type Values
id Organization ID string Organization ID (NJ333)

Example Response

{
    "organization": {
        "id": "NJ333",
        "name": "NJ333 - Petfinder Test Account",
        "email": "no-reply@petfinder.com",
        "phone": "555-555-5555",
        "address": {
            "address1": "Test address 1",
            "address2": "Test address 2",
            "city": "Jersey City",
            "state": "NJ",
            "postcode": "07097",
            "country": "US"
        },
        "hours": {
            "monday": null,
            "tuesday": null,
            "wednesday": null,
            "thursday": null,
            "friday": null,
            "saturday": null,
            "sunday": null
        },
        "url": "https://www.petfinder.com/member/us/nj/jersey-city/nj333-petfinder-test-account/?referrer_id=d7e3700b-2e07-11e9-b3f3-0800275f82b1",
        "website": null,
        "mission_statement": null,
        "adoption": {
            "policy": null,
            "url": null
        },
        "social_media": {
            "facebook": null,
            "twitter": null,
            "youtube": null,
            "instagram": null,
            "pinterest": null
        },
        "photos": [
            {
                "small": "https://photos.petfinder.com/photos/organizations/124/1/?bust=1546042081&width=100",
                "medium": "https://photos.petfinder.com/photos/organizations/124/1/?bust=1546042081&width=300",
                "large": "https://photos.petfinder.com/photos/organizations/124/1/?bust=1546042081&width=600",
                "full": "https://photos.petfinder.com/photos/organizations/124/1/?bust=1546042081"
            }
        ],
        "distance": null,
        "_links": {
            "self": {
                "href": "/v2/organizations/nj333"
            },
            "animals": {
                "href": "/v2/animals?organization=nj333"
            }
        }
    }
}

Developer Resources

Here are some additional resources to help you work with the Petfinder API.