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 and 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;
}
Integration with Public API
openapi: "3.0.0"
info:
version: 1.0.0
title: Stable Management Public REST API v2
license:
name: MIT
servers:
- url: /equicty/api/
paths:
/public/web/horse:
post:
summary: Create a new horse
operationId: createHorse
tags:
- Horse
security:
- EquictyAuthenticationBearer: [ ]
requestBody:
description: create horse request
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpsertHorseRequest"
responses:
'200':
description: Horse details
content:
application/json:
schema:
$ref: '#/components/schemas/HorseDetails'
'400':
description: validation errors
content:
application/json:
schema:
oneOf:
- $ref: "#/components/responses/GenericErrorResponse"
- $ref: "#/components/responses/ValidationErrorResponse"
'401':
$ref: "#/components/responses/GenericErrorResponse"
'500':
$ref: "#/components/responses/GenericErrorResponse"
/public/web/horse/{horseId}:
put:
summary: Update an existing horse
operationId: editHorse
tags:
- Horse
security:
- EquictyAuthenticationBearer: [ ]
parameters:
- name: horseId
in: path
required: true
description: ID of the horse to update
schema:
type: integer
format: int32
requestBody:
description: edit horse request
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpsertHorseRequest"
responses:
'200':
description: Horse details
content:
application/json:
schema:
$ref: '#/components/schemas/HorseDetails'
'400':
description: validation errors
content:
application/json:
schema:
oneOf:
- $ref: "#/components/responses/GenericErrorResponse"
- $ref: "#/components/responses/ValidationErrorResponse"
'401':
$ref: "#/components/responses/GenericErrorResponse"
'500':
$ref: "#/components/responses/GenericErrorResponse"
/public/web/horses/{horse_id}:
get:
summary: Get single horse details
operationId: getHorseDetails
tags:
- Horse
security:
- EquictyAuthenticationBearer: [ ]
parameters:
- name: horse_id
in: path
required: true
description: ID of the horse to get details
schema:
type: integer
format: int32
- name: include_additional_info
in: query
required: false
schema:
type: boolean
default: false
description: if set to true - FullHorseDetails are returned, HorseDetailsWithMedia otherwise
responses:
'200':
description: Horse details
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/HorseDetailsWithMedia'
- $ref: '#/components/schemas/FullHorseDetails'
'400':
description: validation errors
content:
application/json:
schema:
oneOf:
- $ref: "#/components/responses/GenericErrorResponse"
- $ref: "#/components/responses/ValidationErrorResponse"
'401':
$ref: "#/components/responses/GenericErrorResponse"
'500':
$ref: "#/components/responses/GenericErrorResponse"
/public/web/horses/:
post:
summary: Get all horses
operationId: getAllHorses
tags:
- Horse
security:
- EquictyAuthenticationBearer: [ ]
parameters:
- name: include_additional_info
in: query
required: false
schema:
type: boolean
default: false
description: if set to true - FullHorseDetailsWithoutMedia are returned, HorseDetails otherwise
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
gender:
type: string
enum: [UNKNOWN, MARE, GELDING, STALLION, FILLY, COLT]
description: horse gender filter
responses:
'200':
description: Horse details
content:
application/json:
schema:
type: array
items:
oneOf:
- $ref: '#/components/schemas/HorseDetails'
- $ref: '#/components/schemas/FullHorseDetailsWithoutMedia'
'400':
description: validation errors
content:
application/json:
schema:
oneOf:
- $ref: "#/components/responses/GenericErrorResponse"
- $ref: "#/components/responses/ValidationErrorResponse"
'401':
$ref: "#/components/responses/GenericErrorResponse"
'500':
$ref: "#/components/responses/GenericErrorResponse"
components:
schemas:
UpsertHorseRequest:
type: object
required:
- name
- stableId
properties:
name:
type: string
nullable: false
sku:
type: string
nullable: true
minLength: 1
maxLength: 30
registration_number:
type: string
nullable: false
location:
type: string
nullable: true
birth_date:
type: string
example: "20-03-2024"
nullable: true
HorseDetails:
type: object
properties:
id:
type: string
name:
type: string
official_name:
type: string
nick_name:
type: string
age:
type: integer
format: int32
birth_date:
type: string
example: "20-03-2024"
sex:
type: string
studbook:
type: string
color:
type: string
height:
type: integer
format: int32
heightunit:
type: string
breeder:
type: string
pedigree:
type: string
nullable: true
horsetelex:
type: boolean
description: flag indicating if the horse is synced with horsetelex
profile:
type: string
description: horse's profile picture url
miniature:
type: string
description: horse's miniature picture url
HorseMediaDetails:
type: object
properties:
level:
type: string
info:
type: string
videos:
type: array
items:
$ref: '#/components/schemas/MediaDetails'
pictures:
type: array
items:
$ref: '#/components/schemas/MediaDetails'
AdditionalDetails:
type: object
properties:
level:
type: string
sku:
type: string
breeding_associations:
type: array
items:
type: string
semen_availability:
type: array
items:
type: string
wffs_test_result:
type: string
semen_price:
type: string
sales_content:
type: string
disciplines:
type: array
items:
type: string
FullHorseDetails:
allOf:
- $ref: '#/components/schemas/HorseDetails'
- $ref: '#/components/schemas/HorseMediaDetails'
- $ref: '#/components/schemas/AdditionalDetails'
HorseDetailsWithMedia:
allOf:
- $ref: '#/components/schemas/HorseDetails'
- $ref: '#/components/schemas/HorseMediaDetails'
FullHorseDetailsWithoutMedia:
allOf:
- $ref: '#/components/schemas/HorseDetails'
- $ref: '#/components/schemas/AdditionalDetails'
MediaDetails:
type: object
properties:
name:
type: string
module:
type: string
mediaurl:
type: string
description: url pointing to the media file
miniatureurl:
type: string
description: url pointing to the media file's miniature
responses:
GenericErrorResponse:
description: generic error
content:
application/json:
schema:
type: object
required:
- status
- msg
properties:
status:
type: boolean
msg:
type: string
ValidationErrorResponse:
description: validation errors
content:
application/json:
schema:
type: object
required:
- status
- msg
- errors
properties:
status:
type: integer
format: int32
msg:
type: string
errors:
type: array
items:
type: object
properties:
message:
type: string
fieldName:
type: string
field:
type: string
rejectedValue:
nullable: true
description: This value can be of any type, depending on the type of the field that failed validation
securitySchemes:
EquictyAuthenticationBearer:
type: http
scheme: bearer
You have questions?
If you have any question or need help please send your request to [email protected] and inform us for which customer you are acting!