persons | PetHub Dev Net (Alpha)

By PetHub, 23 January, 2023

/Perks

The /Perks endpoint focuses on the current list of lost pets posted on PetHub.com. Use this to create, read/pull, update and delete Lost Pet Posters.

Digging into /Perks

The /perks endpoint offers the following:

/perks	Description
/
/{perkid}	GET - PUT - DELETE -

The Swagger 2.0 / OAS YAML rendering is below including the data structures necessary for POST or returned by GET.

/Persons

The /Persons endpoint focuses on the user account on PetHub.com.

Use this to create a user account, retrieve a user's information, update their details, and retrieve a list of content they own (including pet profiles, documents, safety contacts, and so on). Then, if it is necessary to dive deeper into detail, use the other APIs to access specific details about those Types of content.

Security: this information is only available if the user has provided both access to the requesting application and permissions to access the type of information being requested. If a user provides access to their account but has not given permission to view Documents or Insurance information, for example, an error 400 (Bad Request) will be returned.

Digging into /Persons

The /persons endpoint:

/persons	Description
/	POST - Creates a new user account GET - search for a person's basic account information using their email address or username. Examples: https://pethub.io/v1/persons?email=john@example.com https://pethub.io/v1/persons?username=johndoe
/{uuid}¹	GET - returns basic account information such as email address, unique username, creation date, last login PUT - updates an existing user's account DELETE - Removes the user account and any content provided by the user (requires elevated permissions)
/{uuid}/authorized	GET - list of API key IDs user has approved for accessing their account and data (requires elevated permissions)
/{uuid}/perks	POST - add a perk to a user's list of perks GET - list of perks claimed by the user (can filter by expiration and status) Example: https://pethub.io/v1/persons/3295c76acbf4caaed33c36b1b5fc2cb1/perks?status=active (returns only active perks and excludes those that have expired) DELETE - remove a perk from a user's list of claimed perks
/{uuid}/pets	GET - the pets type causes the API to return a basic list of the user's pets perfect for using in a list that allows drilling deeper into an individual pet's information Example: https://pethub.io/v1/persons/3295c76acbf4caaed33c36b1b5fc2cb1/pets?species=dog (returns list of user's pets that are dogs)
/{uuid}/policies	POST - add a policy to a user's profile GET - list of all insurance policies added to the site by the user and to which pets the policy applies DELETE - remove a policy from a user's account
/{uuid}/profile	GET - deeper information about the user's account information, including first name, last name, main telephone number(s), additional email addresses, and mailing address PUT - updates a user's profile
/{uuid}/safetyCircle	POST - add a safety circle contact (including to which pet(s) is/are known by the person GET - list of Safety Circle contacts the user has added to the website. Also includes a list of pets each of the contacts knows (optional query attribute pet_id may be used to filter by pet) PUT - update a contact's information (including which pet(s) are known by the contact) DELETE - remove an emergency contact from the user's list
/{uuid}/subscriptions	POST - add a new subscription to the user's account GET - which subscriptions have been purchased by the user, to which pet they apply, when they were purchased, and when they expire DELETE - terminate a user's subscription

¹ {uuid} is the universally unique identifier returned when a GET request is made to the /persons endpoint by an authorized API integrator

The Swagger 2.0 / OAS YAML rendering is below including the data structures necessary for POST or returned by GET.

Swagger 2.0 File

Endpoints

PetHub APIs support a number of endpoints that, with your feedback, we will continue to add to our library. The APIs below are what are currently in our catalog.

We've broken these up into 3 sections:

Sniffing Around - both the most commonly used API calls for starting an interaction with a user's account and also the calls you'll need when initially registering your application with PetHub and getting a user's permission to utilize their data
Digging Deeper - endpoints that help you dig deeper into a user's or pet's information
Webhooks - proactively pull information as well as register to have PetHub notify you when specific events have taken place (such as tags being scanned or lost pet alerts being sent, for example)

The fun stuff:

Sniffing Around:
- Authorizations - before a 3rd party application may interact with a PetHub user's account and data, it may first receive authorization from the PetHub user
- Persons - the end-user with the account on PetHub who has control of their own and their pet's content
- Pets - the profiles of the animals managed by the PetHub platform
Digging Deeper:
- Activities - walking, agility, eating, playing, training, sleeping, pooping, and more. This is how you list it and add to it for a particular pet
- Foods - manufacturer, formula, type (wet? kibble? raw?), amount, timing, and special preparation instructions can be found or added to for a pet with this endpoint
- LostPets - pull a list of lost pet posters for a user, specific pet, by geo location, and more. Or, add to our list of Lost Pet posters
- Perks - view which discounts a PetHub subscriber has claimed or the entire list of Perks that could be claimed
- Species - pull the list of species supported by the PetHub platform or look-up the species for a specific pet
- Tags - ability to look-up tag information including a pet's profile information if publicly published by the pet owner
Webhooks:
- Alerts - announcements about missing or found animals
- Notifications - tag scanning events (webhook) for a particular pet or particular tag ID

Each of these can be accessed with permission from the user whose data is being requested. In addition, the user can see which applications have been given permission to use their data which can be revoked at any time. Lastly, the user can control which of these types of resources each application is allowed to access on a read / write / update / delete basis.