Horsefly Analytics API (BETA)

Download OpenAPI specification:Download

Introduction

The AI Recruitment Technologies Application Programming Interface (API) provides direct access to the Horsefly platform. It allows you to recreate the Horsefly experience within your own bespoke applications. Communication is via POST and json and results are returned as json. The API can be used to feed a custom developed application, a public website or just off-the-shelf software like Microsoft Excel.

Usage

Please find below a set of pre-prepared queries. These can be executed in-situ, via curl command or they can be copy and pasted into your own code base.

currency-api

Currency API

Get currency code from country code

Request

query Parameters

countryCode

required

string

country code

Responses

200

OK

201

Created

400

Invalid APIRequest supplied

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal server error

post/horsefly-currency/currencyCodeFromCountryCode

Request samples

horsefly-analytics-api

Horsefly Analytics API

About

Responses

200

OK

400

Invalid APIRequest supplied

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal server error

get/horsefly-api/about

Request samples

Insights on: universities, job titles, companies and keywords

Request

query Parameters

apiKey

string

apiKey

Request Body schema: application/json

currency required	string Standard ISO 4217 currency code
required	object (Filters)
required	Array of objects (Locations)
perspectiveField required	string Leave blank for overview. For insight provide one of:'educations', 'positions', 'companies', 'hardSkills' corresponding to universities, job titles, companies and keywords respectively. For full API provide a zero-length string.
required	object (SearchTags)
view required	string Leave blank for overview. For insight provide one of:'candidates', 'adverts', to view insights from the respective corpus. For full API provide a zero-length string.

Responses

200

OK

201

Created

400

Invalid APIRequest supplied

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal server error

post/horsefly-api/insight

Request samples

application/json

{"currency": "USD",
"filters": {"female": 1,
"male": 1,
"yoe0": 1,
"yoe1": 1,
"yoe2": 1
},
"locations": [{"city": "las vegas",
"country": "us",
"radius": 15,
"region": "nevada"
}
],
"perspectiveField": "educations",
"searchTags": {"searchGroup": [{"include": 1,
"keywords": [{"keyword": "barista"
},
{"keyword": "trainee barista"
}
]
}
]
},
"view": "candidates"
}

Overview of supply and demand, salary, gender, experience and (where applicable) ethnicity

Request

query Parameters

apiKey

string

apiKey

Request Body schema: application/json

currency required	string Standard ISO 4217 currency code
required	object (Filters)
required	Array of objects (Locations)
perspectiveField required	string Leave blank for overview. For insight provide one of:'educations', 'positions', 'companies', 'hardSkills' corresponding to universities, job titles, companies and keywords respectively. For full API provide a zero-length string.
required	object (SearchTags)
view required	string Leave blank for overview. For insight provide one of:'candidates', 'adverts', to view insights from the respective corpus. For full API provide a zero-length string.

Responses

200

OK

201

Created

400

Invalid APIRequest supplied

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal server error

post/horsefly-api/overview

Request samples

application/json

{"currency": "USD",
"filters": {"female": 1,
"male": 1,
"yoe0": 1,
"yoe1": 1,
"yoe2": 1
},
"locations": [{"city": "las vegas",
"country": "us",
"radius": 15,
"region": "nevada"
}
],
"perspectiveField": "educations",
"searchTags": {"searchGroup": [{"include": 1,
"keywords": [{"keyword": "barista"
},
{"keyword": "trainee barista"
}
]
}
]
},
"view": "candidates"
}

Difficulty to hire scores for a location based on ethnicity, gender and experience

Request

query Parameters

apiKey

string

apiKey

Request Body schema: application/json

currency required	string Standard ISO 4217 currency code
required	object (Filters)
required	Array of objects (Locations)
perspectiveField required	string Leave blank for overview. For insight provide one of:'educations', 'positions', 'companies', 'hardSkills' corresponding to universities, job titles, companies and keywords respectively. For full API provide a zero-length string.
required	object (SearchTags)
view required	string Leave blank for overview. For insight provide one of:'candidates', 'adverts', to view insights from the respective corpus. For full API provide a zero-length string.

Responses

200

OK

201

Created

400

Invalid APIRequest supplied

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal server error

post/horsefly-api/difficultyToHire

Request samples

application/json

{"currency": "USD",
"filters": {"female": 1,
"male": 1,
"yoe0": 1,
"yoe1": 1,
"yoe2": 1
},
"locations": [{"city": "las vegas",
"country": "us",
"radius": 15,
"region": "nevada"
}
],
"perspectiveField": "educations",
"searchTags": {"searchGroup": [{"include": 1,
"keywords": [{"keyword": "barista"
},
{"keyword": "trainee barista"
}
]
}
]
},
"view": "candidates"
}

Provides an AI impact score for provided roles.

Request

query Parameters

apiKey

string

apiKey

Request Body schema: application/json

currency required	string Standard ISO 4217 currency code
required	object (Filters)
required	Array of objects (Locations)
perspectiveField required	string Leave blank for overview. For insight provide one of:'educations', 'positions', 'companies', 'hardSkills' corresponding to universities, job titles, companies and keywords respectively. For full API provide a zero-length string.
required	object (SearchTags)
view required	string Leave blank for overview. For insight provide one of:'candidates', 'adverts', to view insights from the respective corpus. For full API provide a zero-length string.

Responses

200

OK

201

Created

400

Invalid APIRequest supplied

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal server error

post/horsefly-api/aiImpactScore

Request samples

application/json

{"currency": "USD",
"filters": {"female": 1,
"male": 1,
"yoe0": 1,
"yoe1": 1,
"yoe2": 1
},
"locations": [{"city": "las vegas",
"country": "us",
"radius": 15,
"region": "nevada"
}
],
"perspectiveField": "educations",
"searchTags": {"searchGroup": [{"include": 1,
"keywords": [{"keyword": "barista"
},
{"keyword": "trainee barista"
}
]
}
]
},
"view": "candidates"
}

Provides keywords parsed from a provided job description and job title

Request

query Parameters

apiKey

string

apiKey

Request Body schema: application/json

jobTitle required	string Job Title
jobDescription required	string A full job description

Responses

200

OK

201

Created

400

Invalid APIRequest supplied

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal server error

post/horsefly-api/searchBuilder

Request samples

application/json

{"jobTitle": "Software Engineer",
"jobDescription": "The role: We are seeking an experienced Senior Engineer with a strong background in web applications. Experience with PHP and Magento is preferred, but not mandatory."
}

API usage for a user based on their API key

Request

query Parameters

apiKey

required

string

apiKey

Responses

200

OK

201

Created

400

Invalid APIRequest supplied

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal server error

post/horsefly-api/apiUsage

Request samples

locations-api

Locations API

Get cities from country code

Request

query Parameters

countryCode

required

string

country code

Responses

200

OK

201

Created

400

Invalid APIRequest supplied

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal server error

post/horsefly-locations/citiesFromCountryCode

Request samples

Get cities from country code and region

Request

query Parameters

countryCode required	string country code
region required	string region name

Responses

200

OK

201

Created

400

Invalid APIRequest supplied

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal server error

post/horsefly-locations/citiesFromCountryCodeAndRegion

Request samples

Get country code from country name

Request

query Parameters

countryName

required

string

country name

Responses

200

OK

201

Created

400

Invalid APIRequest supplied

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal server error

post/horsefly-locations/countryCodeFromCountry

Request samples

List all regions from country code (regionalised countries only)

Request

query Parameters

countryCode

required

string

country code

Responses

200

OK

201

Created

400

Invalid APIRequest supplied

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal server error

post/horsefly-locations/regionsFromCountryCode

Request samples