Introduction
Do you want to link your website to your equicty - equstable account? Do you want to save time by having your horses information stored in equicty shared with your website in one click? Not only horse profile information such as age, pedigree, color, horse height, etc., but also your photos,videos can be made available on your website in real time!
Therefore equicty has developed an Application Programming Interface called API to allow you to built an automated connection between your website and your equicty stable management account.
The benefits of this great feature;
- Save you tremendous time by avoiding you to duplicate information on your business website ! Once a horse is created in equicty it will appear in real-time on your business website
- Make sure your business website is always up-to-date without any effort ! Having your latest horses arrived at your stable, new upload of videos or photos on existing horses etc updated in in real time
What kind of information can be shared between equicty and your website ?
Horse Identification information: Gender, Age, Date of Birth, Studbook, Colour, Horse Height
Horses pedigree: 3 generations
Horses pictures: Profile picture, miniature, and other pictures you have made public
Horses videos: videos you have made public
How to get started with the integration ?
STEP 1: Upgrade your equicty account with the "Website API" add-on feature. Read more..
STEP 2: Share following information with your webmaster (your website developer)
- Your unique API key. After upgrading your account you can find this key on following location on your account; Settings > My Stable > API key
VERY IMPORTANT; Please handle the key very securely ! Keep it very secure !
- Technical API integration documentation you can find below in this document
STEP 3: Your webmaster can start accessing the required information from your equicty account
STEP 4: When your webmaster has done the job you can start configuring your equicty account!
Configure which horses you want to have synchronised with your website by activating the earth symbol in the horse profile section.
Configure which photos or videos you want to share with your website by activating the earth symbol in the Media module
API Technical documentation (For the webmasters)
Authentication
Authenticate your account when using the API by including your secret API key in the request. The customer administrator can find the website API key under Settings -> My Stable -> Website API.
Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys.
Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.
Authenticate via bearer: headers in:
-
- Authorization: Bearer {{website api key}}
-
- Accept-Language: EN/FR/DE/NL (default EN)
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Errors
Equicty uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in
the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with the servers of equicty (exceptional).
To understand why a request is declined, see status codes below. HTTP status code summary
200-OK
400 - Bad Request
401 - Unauthorized
500 - Server Errors
Everything worked as expected.
The request was unacceptable, often due to missing a required parameter.
No valid API key provided.
Something went wrong on the server.
Basic JSON frame returned from API:
When is error, data have to looks like this:
{
“status” : false,
“msg” : “what was wrong” }
When is ok, data have to: {
“data” : {
//Other json data, arrays models etc
} }
Successful Request Failed Request
Demo example
http://demostable.equicty.com/
200 OK
400 Bad Request
Request list of public horses
Description: Function return list of public horses
Route: https://portal.equicty.com/equicty/api/public/web/horses Method: POST
Params in:
gender: STALLION/MARE/GELDING (optional filter)
headers in:
Authorization: Bearer {{website api key}}
Accept-Language: EN/FR/DE/NL (default EN)
Params out:
[
{
"id": 1,
"name": "horse name example", "age": 5,
"birthday": "07-03-2012",
"sex": "Gelding",
"studbook": "BWP",
"color": "Paint",
"height": 172, "heightunit": "cm" "horsetelex": false, "pedigree": {
"v": "father", "vv": "",
"vvv": "", "vvm": "", "vm": "", "vmv": "", "vmm": "", "m": "Mother", "mv": "", "mvv": "", "mvm": "", "mm": "", "mmv": "", "mmm": ""
},
"profile": "https://...jpg", "miniature": "https://...jpg
} ]
// Only for horses not synced to horesetelex
Request public horse details
Description: Function return details of a public horse
Route: https://portal.equicty.com/equicty/api/public/web/horses/{{horseid}} Method: GET
Params in:
headers in:
Authorization: Bearer {{website api key}}
Accept-Language: EN/FR/DE/NL (default EN)
Params out:
{
"id": 1,
"name": "horse name example", "age": 5,
"birthday": "07-03-2012",
"sex": "Gelding",
"studbook": "BWP",
"color": "Paint",
"height": 172, "heightunit": "cm", "horsetelex": false, "pedigree": {
"v": "father", "vv": "",
"vvv": "", "vvm": "", "vm": "", "vmv": "", "vmm": "", "m": "Mother", "mv": "", "mvv": "", "mvm": "", "mm": "", "mmv": "", "mmm": ""
},
"profile": "https://...jpg", "miniature": "https://...jpg", "videos": [
// Only for horses not synced to horesetelex
{
"name": "",
"module": "",
"mediaurl": "https://www.youtube.com/watch?v=b8-KqYAWJ4M", "miniatureurl": "https://i.ytimg.com/vi/b8-KqYAWJ4M/hqdefault.jpg"
} ],
"pictures": [ {
"name": "",
"module": "",
"mediaurl": "https://...4.png", "miniatureurl": "https://....png"
} ]
}
Request HorseTelex pedigree
Description: Function returns the horestelex pedigree of a public horse. This is only available for horses where “horsetelex” attribute is true. This return the html output and it is possible to override the color scheme. Remark: do not add the # character to the color value, this is done in the api!
Route: https://portal.equicty.com/equicty/api/public/web/horses/pedigree/{{horseid}} Method: POST
Params in:
{
: "ff0000", : "00ff00", : "0000ff"
}
headers in:
Authorization: Bearer {{website api key}} Accept-Language: EN/FR/DE/NL (default EN) Params out:
Html representation of the pedigree.
Logo integrated in the html output must be visible and may not be removed!
EQUICTY SAAS AGREEMENT article 4.3
“Customer agrees that, with any use of the SAASservice, the name, trademark and logo of EQUICTY and/or its suppliers (such as e.g. the HorseTelex database) shall be clearly visible and that Customer shall refrain from altering or removing any such notices from the products and services. “
"horse_textcolor" "mare_bgcolor" "mare_textcolor"
Sample code
List of public horses
<?php
// get list of public horses with filter gender
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://portal.equicty.com/equicty/api/public/web/horses", CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{\n\t\"gender\": \"\"\n}", CURLOPT_HTTPHEADER => array(
"authorization: Bearer {{ website api key }}", "cache-control: no-cache",
"content-type: application/json
), ));
$response = curl_exec($curl); $err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
HorseTelex pedigree
<?php
// get html output for the horstelex pedigree
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://portal.equicty.com/equicty/api/public/web/horses/pedigree/{{horse ID}}", CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS =>
"{\n\t\"horse_textcolor\":\"00AFA8\",\n\t\"mare_bgcolor\":\"efefef\",\n\t\"mare_textcolor\":\"000000\"\n}", CURLOPT_HTTPHEADER => array(
"authorization: Bearer {{ website api key }}", "cache-control: no-cache",
"content-type: application/json”
), ));
$response = curl_exec($curl); $err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
You have questions?
If you have any question or need help please send your request to support@equicty.com and inform us for which customer you are acting!