Introduction to the Springest API

Gewijzigd op Do, 26 Okt, 2023 om 12:30 PM

The Springest API is a REST-ful API. This documentation will explain you how you can communicate with it. If you have any problems or requests, please do contact us.

We've written some example scripts in PHP and Ruby in case you find it hard to get started.

Hosts

For each country that we operate in, our API is accessed through a different host. You'll need a separate API key for each host.

CountryHost address
Netherlandshttps://api.springest.nl
United Kingdomhttps://api.springest.co.uk
Belgium (Flanders)https://api.nl.springest.be
Germanyhttps://api.springest.de
Globalhttps://api.springest.com
Our API is as stated per country and not per domain
 so it Is possible to call the Go Domains of that country. 
Per Go always use 'nameofgo.api.go.host'
See example of our Dutch demo Go domain.
https://demo.api.go.springest.nl<br>

End points

Trainings - courses, training, elearning and associated dataInstitutes - data on education providers
Categories - the main ~21 categories Springest is categorised inSubjects - ~1000 specific subjects Springest is divided in
Reviews - ratings and reviews per course or instituteConversions - course bookings and information requests for providers
LearnMatch job / article matching - our "magic" matching API that returns relevant courses based on your input   Certificates and certifications - user certificates and the certifications they belong to.
Features with limited access:
Bookings Create - Create bookings in our system
Bookings Get - Get all bookings for your organisation
Webhooks for Conversions End point - Use webhooks to get latest updates per site for conversions
Autocomplete (search suggestions) - Create a "quick search" widget in your intranet.Webhooks for Trainings End point - Use webhooks to get latest updates per site for trainings (mainly for courseboards etc)
Users - Create user accounts  Cancel bookings - cancel bookings made in our system

Supported data formats

We provide both XML and JSON formatted data but only fully support .json  
We do accept XML requests in the xml request body if they are formatted like JSON requests or when they are provided in the url or via query params.

For brevity and readability we use only XML output in the examples in the API documentation.

Example of XML or JSON request.

{   "users": [{     "email": ...,     "external_id": ....   }] }

Response status codes

While using our API you can encounter the following response status codes:

StatusDescription
200 OKThe request was correct
400 Bad RequestYou either tried to request an invalid resource, or used a parameter incorrectly
401 You're not authorisedYou need to supply valid authentication credentials (ie. an API key)
403 ForbiddenYou don't have the right privileges to access this method
404 Not FoundThe resource that you try to reach does not exist
405 Forbidden
The method received in the request-line is known but endpoint most likely not existing/correctly called
500 Server ErrorSomething went wrong on our side

Authentication

Authentication is fairly simple with an API key that you can request from us
Please append your API key to every request you make, e.g. GET /trainings/1234.xml?api_key=YOURAPIKEY

Rate limiting

Please be aware that we've capped the amount of requests you can make to our API to 4000 requests per hour.

Access Levels

Not all data is accessible through the API. Additionally, depending on the type of partnership, certain fields will not be accessible.

Pagination

All the requests that have multiple results are paginated. You can set the page size by adding the size parameter to your request, e.g. to return 12 items per page, make the following request: GET /institutes.xml?size=12&api_key=YOURAPIKEY

You can set the page you need with the offset parameter, e.g. to get the third page of a list of institutes, using a page size of 12 institutes per page, make the following request: GET /institutes.xml?size=12&offset=24&api_key=YOURAPIKEY

 Pagination parameters 
ParameterTypeRequiredValuesDefaultDescription
offsetIntegerNox > 00Used to indicate starting point of pagination
sizeIntegerNo1 <= x <= 3010Number of results per page

Documentation conventions

{text}
Means text that needs to be replaced by your own data
<text>
Means that something is optional

API Requests:

If you'd like to request an API key please send an email to datasupport@springest.com with the following details:

  • Your name and email address
  • The name of your organization
  • The URL of your organization
  • What you would like to do with our API

FAQ: 

 ‚Üí Is import only the action when a new provider is added to the platform? Or also when a provider, that is already visible in the API overview, does an XML update?

An import means an update of all products for a provider based on the XML-feed with training information. This means that all products from this provider are being updated and have new information.

‚ÜíHow much delay do we expect when multiple changes on the same ID happen? When does this happen?

"Springest will delay JSON and bundle information to prevent multiple changes on same ID (duplicate work)".  Every update gets sent as fast as possible. If there are 2 individual updates (so not 2 different changes in 1 single update) right after each other, we sent 2 webhooks.

Was dit artikel nuttig?

Dat is fantastisch!

Hartelijk dank voor uw beoordeling

Sorry dat we u niet konden helpen

Hartelijk dank voor uw beoordeling

Laat ons weten hoe we dit artikel kunnen verbeteren!

Selecteer tenminste een van de redenen
CAPTCHA-verificatie is vereist.

Feedback verzonden

We stellen uw moeite op prijs en zullen proberen het artikel te verbeteren