{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"bc38acae-4ecc-4c6c-a720-ab8a8adae21a","name":"Adopt-a-Pet.com Basic API","description":"## Introduction\n\nThis documentation is for partners of Adopt-a-Pet.com, a national non-profit pet adoption advertising charity. The Adopt-a-Pet.com API (Application Programming Interface) is a series of tools that allows partners to use Adopt-a-Pet.com's pet adoption features and pet data in other applications. These tools can only be used pursuant to the contractual details of the partnership, and acknowledgement of Adopt-a-Pet.com on all pages of the implementation of these tools is required as per that contract. See [Terms of Use](#3f3c7535-c0aa-4858-9413-a561b4473d58).\n\n## Overview\n\nThe Adopt-a-Pet.com API will allow partners to query the Adopt-a-Pet.com database for information that can be used to build pet searching forms, retrieve pet search results, view pet details information including pet photos, search for shelters and pets at shelters, and retrieve other relevant information.\n\n## Audience\n\nThis document is intended for software developers who are already familiar with the concept of an API and object oriented programming concepts. Developers should also be familiar with the Adopt-a-Pet.com interface from a user's point of view.\n\n## Integration Workflow\n\nThese are the required steps for integration of the Adopt-a-Pet.com syndicated pet search:\n\n1. Partner reviews this documentation, and contacts us with any initial questions.\n2. Partner must have signed partnership agreement with Adopt-a- Pet.com, specifying the length, fees and terms of use of our syndicated search feature. Please review the terms of use in this document.\n3. Partner requests and receives an API key for the staging/test version of the API system.\n4. Partner develops and refines the API client software (the site that's making use of the API).\n5. Adopt-a-Pet.com reviews the design and must sign off on use and placement of Adopt-a-Pet.com and its sponsor logos.\n6. The Adopt-a-Pet.com technical team reviews the API integration, does quality assurance, and suggests refinements based upon our experience, and confirms that function calls are performing as intended.\n7. Partner provides Adopt-a-Pet.com with a paragraph of text describing their website, which we will use in an email to animal shelters and place on Adopt-a-Pet.com for animal shelters to see. Shelters can then opt out of inclusion in API request results, if they desire.\n8. Partner requests and receives an API key to test the production version of the API system, but the system is still not made live to the public. This coincides with Adopt-a-Pet.com going live with the opt in/out functionality in its shelter admin area.\n9. Adopt-a-Pet.com communicates with shelters alerting them to the new API partner. Shelters are given one week to respond and opt out if they wish.\n10. Partner may then go live with the production version of the API client software on a Monday, Tuesday or Wednesday, leaving at least two business days before a weekend to trouble shoot any issues with the launch.\n\n## API Features\n\nThe Adopt-a-Pet.com API provides the following features:\n\n* Pet Search\n  * Retrieve pet searching form data (breed listing, search criteria, etc.)\n  * Retrieve the results of a pet search\n  * Retrieve the details for a specific pet\n\nSome features may not be available to all API partners.\n\n## API Security\n\nPlease make sure you protect your API key and ensure that it is not disclosed to the public. It should never be checked into source control (i.e., GitHub), or hard coded within HTML or JavaScript that could be viewed by users on your site.\n\nAll requests to our API endpoint must be made using HTTPS. Your software/client must be capable of understanding and connecting to an SNI (Server Name Indication) server, using SSLv2, TLSv1+ or TLS_v2+. Any requests sent to HTTP vs HTTPS will be redirected, so it is to your advantage to send the request to HTTPS in the first place to reduce request round trip time.\n\n## API Usage Requirements\n\nYou must include a visible Adopt-a-Pet.com logo preceded by the words \"powered by” on all pages where this API is implemented. The logo must be a live link to <https://www.adoptapet.com> and must be an approved version of the logo (which can be found [here](https://drive.google.com/file/d/15HdEJSYmS8W6S7QoISjKrw9HQCBnmWmT/view?usp=sharing)). This enables animal shelters to understand where the data they see is coming from and who to contact to add their pets to the database. It also allows users to know the source of the data and who to contact regarding questions about specific pets they see. This link is not designed to draw users off the partner site, but is for informational and search engine purposes only. As such, the link must not be blocked by \"no-follow\", robots.txt or other search engine blocking methods.\n\n## API Design Overview\n\nThe API is a REST API designed to receive inputs from your custom application using HTTP GET and POST requests that are formatted with a path and a querystring or POST body. For example:\n\n`https://api.adoptapet.com/search/limited_pet_details?key=A34F48&v=2&output=json&pet_id=2342`\n\nThe results of the request will be a text result formatted in one of the available output styles. From there, you can use your own output parser to break the returned data into local data structures, and then process them as you want to.\n\nUsing the API functions provided, you should be able to build a site that functions much like the Adopt-a-Pet.com site, but that has your own customized user interface.\n\nA note about the results of the limited_pet_search method: Exact matches (where all search criteria are met) are always returned before before inexact matches (where only some of the criteria are met). If you choose to show the inexact matches, we recommend adding clear wording to your interface that clarifies the transition in result records. For example: \"These pets aren't exactly what you asked for... but they are close!\"\n\n## Global Inputs and Data Types\n\n### Global Inputs\n\nAll API methods accept the following standard inputs. \n\n* **`key`** - The API key provided to you.\n* **`v`** - The API Version (normally v=2, unless you are asked to use a different one).\n* **`output`** - The output format. Acceptable values are `json` and `xml`. \n\nPlease look at the example Postman environments provided to setup appropriate variables for testing in both staging and production environments. Example responses are also provided here for all API calls.\n\n### Global Data Type Notes\n\n* All input dates should be formatted as \"YYYY-MM-DD\".\n* Input time-stamps should be formatted as \"YYYY-MM-DDTHH:MM\" (essentially, a capital T separating the date and time). The Hour should be in 24-hour format; there is no AM/PM indicator. All times are based on US East Coast time zone, EST/EDT.\n\nThe output data structures will generally be one of these four types:\n\n* String – a value containing alphanumeric text. Blank or null values of this type are denoted by an empty string: \"\"\n* Integer – a whole, non-negative, numeric value. Null values of this type are represented by an empty string\n* Boolean - a value of 1 or 0 (representing true or false, respectively)\n* Modified Boolean – a value of 1 or 0 (representing true or false, respectively) with the null value represented as an empty string, indicating \"unknown\". The null/unknown values usually represent pet traits such as \"Good With Kids\" in which the shelter/rescue does not know if the trait applies or not \n* html – a value that is typically longer than a simple String and is intended to contain free-form text, which may contain html tags and formatting. Note that some of the html text that may be returned has been written by shelter workers or other volunteers, and no guarantees can be made about the technical validity of this html text.\n\n## Error Codes\n\nAPI function call responses will always always include a top level attribute of status and a value of ok, or fail in the event of an error. A nested error data structure will also be included in the response, and it has the following attributes:\n\n* code – required, a numeric code from the table below\n* msg – required, a technical name from the table below\n* details – optional, additional free-form text explaining the error. For validation errors, we return a data structure with records for \"missing,\" \"invalid,\" and \"unknown\" elements.\n\nThe table below describes failure error codes that may be returned from API function calls:\n\n| Error Code | Error Message        | Meaning |\n| ---------- | -------------------- | ------- |\n| 400        | input_invalid        | A field had invalid or badly formatted data |\n| 401        | invalid_key          | The API key submitted was invalid, or was submitted from an unauthorized domain |\n| 403        | access_denied        | Your partner account does not have permission to perform the request submitted |\n| 412        | input_missing        | A required field was not submitted in the request. |\n| 450        | validation_failure   | An error in the information submitted prevented the request from being completed. Check the `missing`, `invalid`, or `unknown` attributes for further information. |\n| 500        | tech_failure         | The system was not able to complete your request for some other reason |\n| 503        | resource_unavailable | The system has received too many requests from you and will not complete your request<sup>1</sup> |\n\n<sup>1</sup> All requests are subject to throttling on an hourly basis. If you start receiving this error and your site traffic is high enough, please contact Adopt-a-Pet.com to discuss raising your limits.\n\nExample Error Response\n\n```json\n{\n    \"status\":\"fail\",\n    \"error\":{\n        \"code\":412\n        \"details\":\"Field \\\"pet_id\\\" was missing.\",\n        \"msg\":\"input_missing\",\n    }\n}\n```","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"2253549","collectionId":"bc38acae-4ecc-4c6c-a720-ab8a8adae21a","publishedId":"RznHHwtr","public":true,"publicUrl":"https://partner-apis.adoptapet.com","privateUrl":"https://go.postman.co/documentation/2253549-bc38acae-4ecc-4c6c-a720-ab8a8adae21a","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","version":"8.10.1","publishDate":"2019-05-16T20:45:04.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[{"name":"Basic API - Staging","id":"7eaf85bb-4838-495d-aa8d-7bbe356072f7","owner":"2253549","values":[{"key":"url","value":"api-staging.adoptapet.com","enabled":true},{"key":"key","value":"hg4nsv85lppeoqqixy3tnlt3k8lj6o0c","enabled":true},{"key":"version","value":"3","enabled":true},{"key":"output","value":"json","enabled":true}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":"https://adoptapet.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"Basic API - Staging","value":"2253549-7eaf85bb-4838-495d-aa8d-7bbe356072f7"}],"canonicalUrl":"https://partner-apis.adoptapet.com/view/metadata/RznHHwtr"}