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;


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

  1. Horse Identification information: Gender, Age, Date of Birth, Studbook, Colour, Horse Height 

  2. Horses pedigree: 3 generations 

  3. Horses pictures: Profile picture, miniature, and other pictures you have made public            

  4. 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!