Documentation
https://api.husbandry.pro/v2/
To get started with using personal data through the Data API, please register your app on the Husbandry Pro dashboard.
To start using the Sale Animal Data API, please register your account. Once you have completed the registration, your application will undergo an approval process. After approval, you can log in to the system and create an app to generate the API credentials.
Scopes
Scopes are specific permissions defined by the API provider that limit what actions a third-party application can perform on behalf of a user. Each scope represents a particular type of access to certain resources or data.
| Scope |
Description |
| profile.read |
get profile information |
| animal.read |
get animals data |
| animal.activities.read |
get animals activities |
| activity.read |
get browse activities |
Authentication
Husbandry API supports OAuth 2.0 Authorization Code Grants to generate OAuth tokens for app security.
Authorization code grants require users to approve access, which generates an authorization code an app includes in a token request (https://husbandry.pro/api/v2/auth_code.php/authorize) from the OAuth resource.
Requesting an Oauth Token
Gather the following information before starting the authorization code grant flow:
-
Your App Client Id, which you can find in Your Apps.
-
A callback URL your app uses to receive the authorization code. Typically, this is a page or script that starts the token request using the authorization code, and therefore must implement TLS and use an https:// prefix.
Requesting an Authorization Code
https://husbandry.pro/api/v2/auth_code.php/authorize
To begin the flow, direct the user to https://husbandry.pro/api/v2/auth_code.php/authorize with a GET request including the following URL parameters:
| Parameter Name |
Description |
| response_type |
Must always be the value `code` |
| client_id |
An App Client Id. |
| redirect_uri |
A URI your app uses to receive the authorization code or error message; see Redirect URIs below. The URL must have the https:// prefix or the request will fail.
|
| scope |
A URL-encoded, space-separated list of one or more scopes (e.g., shops_r%20shops_w); see Scopes below.
|
| state |
The state parameter must be non-empty and should be a single-use token generated specifically for a given request. It is important that the state parameter is impossible to guess, associated with a specific request, and used once. Use state for CSRF protection.
|
Example
$authorizationUrl = 'https://husbandry.pro/api/v2/auth_code.php/authorize';
// Set the necessary query parameters
$params = [
'response_type' => 'code',
'client_id' => 'xxxxxxxxxx',
'redirect_uri' => 'http:///callback-url-here.php',
'scope' => 'profile',
'state' => 'access_token',
];
$authorizationUrl .= '?' . http_build_query($params);
// Redirect the user to the authorization URL
header('Location: ' . $authorizationUrl);
exit;
If the system grants access, Husbandry sends a request back to the app's redirect_uri with the following GET parameters:
| Parameter Name |
Description |
| state |
The state parameter, exactly as set in the authorization request |
| code |
An OAuth authorization code required to request an OAuth token |
For example, the following response indicates that the user grants access and supplies an authorization code:
https://www.example.com/some/location?
code=bftcubu-wownsvftz...
&state=superstate
Errors
If the user does not consent, or there is some other error (e.g. a missing parameter), Husbandry sends a response to the specified redirect_uri with the following GET parameters:
| Parameter Name |
Description |
| state |
The state parameter, exactly as set in the authorization request |
| error |
An error code from RFC 6749 |
| error_description |
A human-readable explanation of the error (always in English) |
| error_uri |
(Optional) A URL with more information about the error. |
Request an Access Token
Request an OAuth access token using the authorization code in a POST request to the Husbandry API /api/v2/auth_code.php/access_token Most requests to the Etsy Open API require this access token, which has a functional life of 1 hour. The Husbandry API delivers a refresh token with the access token, which you can use to obtain a new access token through the refresh_token grant, and has a longer functional lifetime (90 days).
https://husbandry.pro/api/v2/auth_code.php/access_token
To obtain an access token, make a POST request to https://husbandry.pro/api/v2/auth_code.php/access_token with the following parameters in the request body in application/x-www-form-urlencoded format:
| Parameter Name |
Description |
grant_type |
Must always be the value authorization_code |
client_id |
An Husbandry App Client Id |
redirect_uri |
The same redirect_uri value used in the prior authorization code request. |
code |
The authorization code sent back from Husbandry.pro after granting access. |
Example
$tokenUrl = 'https://husbandry.pro/api/v2/auth_code.php/access_token';
// Set the necessary parameters
$params = [
'grant_type' => 'authorization_code',
'code' => $_GET['code'],
'client_id' => 'xxxxxxxxxx',
'client_secret' => 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'redirect_uri' => 'http://callback-url-here.php',
'state' => 'authorization_code',
];
// Send a POST request to the token endpoint
$ch = curl_init($tokenUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$response = json_decode($response, true);
// Process the response
echo $accessToken = $response['access_token'];
echo $refreshToken = $response['refresh_token'];
Profile
Retrive profile information
https://husbandry.pro/api/v2/api.php/profile
Scope: profile.read
Response
{
"first_name" : "John",
"last_name" : "Doe",
"email" : "[email protected]"
}
Errors
| Code |
Message |
access_denied |
The resource owner or authorization server denied the request. |
insufficient_scope |
The requested scope is insufficient for accessing the requested resource. |
Animal
Retrive animal information
GET: Paginated Animals
https://husbandry.pro/api/v2/api.php/animals
Scope: animal.read
Response
{
"data": [
{
"animal_type": {
"ids": "1f970cc5-9ba9-453e-be72-c3e26df3c08a",
"common_name": "Ball Python",
"scientific_name": "Python regius",
"picture": "https://husbandry.pro/.../63fe01c1b6d2a_Grey-Grey.png"
},
"dam_genetics": [
{
"name": "Pinstripe",
"trait": "Inc/Dominant"
}
],
"dam_id": "",
"date_acquired": "2021-01-14",
"descriptor": "Fire Leopard het Clown",
"display_currency": "1",
"fed_notification_type": "1",
"fed_week_days": "",
"feeder": {
"ids": "8d39310f-390b-41a4-99b8-27856a5bd9ec",
"name": "FT Feeder Rat",
"size": "Weaned",
"weight": "70",
"cost": "2.20"
},
"feeding_intervals": "7",
"feeding_notify": "0",
"feeding_qty": "1",
"full_dob": "",
"ids": "c084d512-90f6-48f0-ba43-191518f2adff",
"is_for_sale": "0",
"is_proven_breeder": "0",
"maturity": "Adult Beast",
"my_id": "BP-0018",
"name": "",
"notes": "",
"photos": [],
"rack": {
"name": "ARS",
"row": "3",
"column": "2"
},
"sex": "F",
"sire_genetics": [
{
"name": "Leopard",
"trait": "Inc/Dominant"
},
{
"name": "Fire",
"trait": "Inc/Dominant"
},
{
"name": "Blade",
"trait": "Inc/Dominant"
},
{
"name": "Clown",
"trait": "Recessive"
}
],
"sire_id": "",
"source": "Acquired",
"status": "active",
"supplier_info": {
"ids": "3d2a1fa8-32f1-44a3-a1cd-0a35bd09600c",
"first_name": "Khalil",
"last_name": "Itani",
"email": "[email protected]"
},
"tags": []
},
{
"animal_type": {
"ids": "1f970cc5-9ba9-453e-be72-c3e26df3c08a",
"common_name": "Ball Python",
"scientific_name": "Python regius",
"picture": "https://husbandry.pro/.../63fe01c1b6d2a_Grey-Grey.png"
},
"custom_status_notes": "",
"dam_genetics": [
{
"name": "Desert Ghost [het]",
"trait": "Recessive"
}
],
"dam_id": "",
"date_acquired": "2021-01-14",
"descriptor": "Lemonblast het DG",
"display_currency": "1",
"fed_notification_type": "1",
"fed_week_days": "",
"feeder": {
"ids": "8d39310f-390b-41a4-99b8-27856a5bd9ec",
"name": "FT Feeder Rat",
"size": "Weaned",
"weight": "70",
"cost": "2.20"
},
"feeding_intervals": "7",
"feeding_notify": "0",
"feeding_qty": "1",
"full_dob": "2020-10-20",
"ids": "572793f0-18a0-497a-92c0-18515155fcdf",
"is_for_sale": "0",
"is_proven_breeder": "0",
"maturity": "Adult Beast",
"my_id": "BP-0019",
"name": "",
"notes": "",
"photos": [],
"rack": {
"name": "ARS",
"row": "5",
"column": "2"
},
"sex": "F",
"sire_genetics": [
{
"name": "Pastel",
"trait": "Inc/Dominant"
},
{
"name": "Pinstripe",
"trait": "Inc/Dominant"
},
{
"name": "Desert Ghost",
"trait": "Recessive"
}
],
"sire_id": "",
"source": "Acquired",
"status": "On Loan",
"supplier_info": {
"ids": "3d2a1fa8-32f1-44a3-a1cd-0a35bd09600c",
"first_name": "Khalil",
"last_name": "Itani",
"email": "[email protected]"
},
"tags": []
}
],
"offset": 20,
"limit": 10,
"total": "111"
}
Params
| Field |
Type |
Description |
| sort_field |
string |
`name` default sort field
['my_id', 'feeding_qty', 'feeding_intervals', 'feeding_notify', 'fed_notification_type', 'name', 'sex', 'source', 'descriptor', 'full_dob', 'date_acquired', 'is_for_sale', 'sale_price', 'pricing_notes', 'buyer_notes', 'is_proven_breeder', 'notes', 'maturity', 'hold_customer', 'hold_notes', 'sold_date', 'sold_amount', 'sold_customer', 'sold_notes', 'display_currency', 'status', 'custom_status_notes']
|
| sort_dir |
string |
`asc` default sort order
['asc', 'desc']
|
| limit |
number |
default limit is `100` |
| page |
number |
paginated data |
| animal_type |
string or array |
filter records by animal type |
| status |
string or array |
filter records by status |
| is_for_sale |
number |
filter sale record. either 0 or 1 |
Definition
| Field |
Type |
Description |
| animal_type |
object |
| Field |
Type |
Description |
| ids |
uuid |
unique identifier of animal type |
| common_name |
string |
animal type common name |
| scientific_name |
string |
animal type scientific name |
| picture |
string |
full url of animal type picture |
|
| dam_genetics |
array |
| Field |
Type |
Description |
| name |
string |
- |
| trait |
string |
- |
|
| dam_id |
string |
|
| date_acquired |
date |
Y-m-d format |
| descriptor |
string |
|
| fed_notification_type |
string |
if `feeding_notify` is `true`
[ "Interval Days", "Week Days" ]
|
| fed_week_days |
array |
if `feeding_notify` is `true`
[ "Monday", "Tuesday", "WednesDay", "Thursday", "Friday", "Saturday", "Sunday" ]
|
| feeder |
object |
| Field |
Type |
Description |
| ids |
uuid |
unique identifier of feeder |
| name |
string |
- |
| size |
string |
- |
| weight |
double |
- |
| cost |
double |
- |
|
| feeding_intervals |
number |
if `feeding_notify` is `true`
Number of feeding intervals
|
| feeding_notify |
number |
Feeding notification status (1 for true, 0 for false) |
| feeding_qty |
number |
Feeding quantity |
| full_dob |
date |
Animal Dob |
| hold_info |
object |
if animal status `hold`
| Field |
Type |
Description |
| hold_notes |
string |
|
| hold_customer |
string |
|
|
| ids |
uuid |
Unique identifier for the data |
| is_for_sale |
number |
For sale status (1 for true, 0 for false) |
| is_proven_breeder |
number |
Proven breeder status (1 for true, 0 for false) |
| maturity |
string |
|
| my_id |
string |
User defined unique identifier for the animal |
| name |
string |
Name of the animal |
| notes |
string |
Note of the animal |
| photos |
array |
Array of URLs for photos |
| rack |
object |
| Field |
Type |
Description |
| name |
string |
Name of the rack |
| row |
number |
Row number of the rack |
| column |
number |
Column number of the rack |
|
| sale_info |
object |
if `is_for_sale` is `true`
| Field |
Type |
Description |
| sale_price |
double |
- |
| pricing_notes |
string |
- |
| buyer_notes |
string |
- |
|
| sex |
string |
["M", "F", "U"] |
| sire_genetics |
array |
| Field |
Type |
Description |
| name |
string |
- |
| trait |
string |
- |
|
| sire_id |
string |
|
| sold_info |
object |
if animal status `sold`
| Field |
Type |
Description |
| sold_date |
date |
|
| sold_amount |
double |
|
| sold_customer |
string |
|
| sold_notes |
string |
|
|
| source |
string |
["Produced", "Acquired"]
|
| supplier_info |
object |
| Field |
Type |
Description |
| first_name |
string |
|
| last_name |
string |
|
| email |
string |
|
| sold_notes |
string |
|
|
| status |
string |
["inactive", "active", "hold", "archived", "sold", "sold-archived"] |
| tags |
array |
|
Errors
| Code |
Message |
access_denied |
The resource owner or authorization server denied the request. |
insufficient_scope |
The requested scope is insufficient for accessing the requested resource. |
GET: Single Animal
https://husbandry.pro/api/v2/api.php/animals/{:ids}
Response
{
"animal_type": {
"ids": "1f970cc5-9ba9-453e-be72-c3e26df3c08a",
"common_name": "Ball Python",
"scientific_name": "Python regius",
"picture": "https://husbandry.pro/.../63fe01c1b6d2a_Grey-Grey.png"
},
"dam_genetics": [
{
"name": "Pinstripe",
"trait": "Inc/Dominant"
}
],
"dam_id": "",
"date_acquired": "2021-01-14",
"descriptor": "Fire Leopard het Clown",
"display_currency": "1",
"fed_notification_type": "1",
"fed_week_days": "",
"feeder": {
"ids": "8d39310f-390b-41a4-99b8-27856a5bd9ec",
"name": "FT Feeder Rat",
"size": "Weaned",
"weight": "70",
"cost": "2.20"
},
"feeding_intervals": "7",
"feeding_notify": "0",
"feeding_qty": "1",
"full_dob": "",
"ids": "c084d512-90f6-48f0-ba43-191518f2adff",
"is_for_sale": "0",
"is_proven_breeder": "0",
"maturity": "Adult Beast",
"my_id": "BP-0018",
"name": "",
"notes": "",
"photos": [],
"rack": {
"name": "ARS",
"row": "3",
"column": "2"
},
"sex": "F",
"sire_genetics": [
{
"name": "Leopard",
"trait": "Inc/Dominant"
},
{
"name": "Fire",
"trait": "Inc/Dominant"
},
{
"name": "Blade",
"trait": "Inc/Dominant"
},
{
"name": "Clown",
"trait": "Recessive"
}
],
"sire_id": "",
"source": "Acquired",
"status": "active",
"supplier_info": {
"ids": "3d2a1fa8-32f1-44a3-a1cd-0a35bd09600c",
"first_name": "Khalil",
"last_name": "Itani",
"email": "[email protected]"
},
"tags": []
}
Animal Browse Activities
Retrive paginated animal browse activities
https://husbandry.pro/api/v2/api.php/activities
Scope: activity.read
