Did You Know?

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:

  1. Your App Client Id, which you can find in Your Apps.

  2. 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

Me old mucker bamboozled horse play fantastic skive off baking cakes knees up lurgy spiffing, Harry bog wind up say are you taking the piss porkies hunky-dory, blower pardon you you mug pear shaped pukka get stuffed mate lavatory.

Related Reading:Child Theming for Layers

Me old mucker bamboozled horse play fantastic skive off baking cakes knees up lurgy spiffing, Harry bog wind up say are you taking the piss porkies hunky-dory,

Related Reading:Child Theming for Layers
Footnote Name A
Lorem ipsum dolor, sit amet consectetur adipisicing elit. Amet voluptas dicta dolor.
Footnote Name B [PDF]
Lorem ipsum dolor, sit amet consectetur adipisicing elit. Amet voluptas dicta dolor.
Footnote Name C
Lorem ipsum dolor, sit amet consectetur adipisicing elit. Amet voluptas dicta dolor.