All the power of the Yoplanning ecosystem!
Introduction
The Yoplanning API is organized around REST.
Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors and success.
We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.
JSON is returned by all API methods.
Authentication
First of all, you must request an API token to be able to query the Yoplanning API. To do so, please contact us
Once you have your token in hands, you can start working with the API. All API methods requires authentication.
We use standard token-based authentication system. To authenticate, just provide your API token on the header of each request like this:
Authorization: Token 4804c2cb4d87a13146d4de029f407c82149f2ada
Be carefull : the space between "Token" and the token is important.
Here is a full example using curl
1
2
3
4
5
6
curl -H 'Content-Type: application/json' https://
yoplanning.pro/api/v3.1/teams/
5a90332e-568f-4980-9859-88a984844a4d/clients/8d23503e-041e-4180-98d1-641183bc5ead
-H 'Authorization: Token 4804c2cb4d87a13146d4de029f407c82149f2ada'
Permissions
When you have requested your API token, you have been granted specific permissions on a certain set of teams.
This means you probably cannot use all the API methods listed below.
If you call the Yoplanning API without permissions (for instance, you don't have permission to create session-groups on the team), the API will respond with a 403 HTTP code (Forbidden) with the following details.
1
2
{« detail »: »You do not have permission to perform this action. »}
Throttling
For security reason, the number of request you can perform is limited
You can send up to 5 requests/second and 1000 requests/day.
Beyond that rate, the server will respond with a 429 HTTP code (Too Many Requests) with the following details :
1
2
{« detail »: »Request was throttled. Expected available in 86368 seconds. »}
Overview
TEAM
The team is the most fondamental concept in yoplanning (which is a collaborative tool).
Almost all methods takes a teamId parameter in the url.
That means all the actions are relative to a team.
UUID
Lots of methods requires a “pk“ parameter in the url.
This is the unique identifier for the resource you are trying to retrieve / create / update / delete.
Yoplanning uses UUID (version 4) as unique identifier for all resources.
ENDPOINTS AND HTTP VERBS
For many ressources, 2 endpoints are available :
- one to access a specific instance.
The url basically ends with <pk>.
You can call these endpoints with the following http verbs :
● /api/v3.1/teams/<teamId>/clients/<pk>
GET : Retrieve the ressource
PUT : Update the ressource.
For many endpoints, this will also create the ressource if it does not exist
DELETE : Delete the ressource
- one to access the instances manager:
You call these endpoints with the folloing http verbs :
● /api/v3.1/teams/<teamId>/clients
GET : get a list of all ressources (see Pagination)
POST : create a new ressource (The id will be generate by the server)
All these actions are not available for all endpoints.
Please see each endpoint documentation to know which methods are allowed.
USING PUT PROPERLY
When you want to update a resource, you should always use the following workflow
1. Retrieve the resource with a GET request
2. Modify the JSON data
3. Send a PUT request with the updated JSON
If you don't, the API may reject you because some nested resource requires an ID that you don't give.
In addition, you may loose some data.
ONLINE SELLING
For online selling purpose (retrieving products and available session-groups), only 2 endpoints should be used:
● /api/v3.1/teams/<teamId>/online-products/
● /api/v3.1/teams/<teamId>/online-products/<productId>/session-groups/
STORING YOUR ID
It might be useful to store your own id on each resource you manage, especially if you want to synchronise your system with Yoplanning.
For example, in case of synchonisation problems on your side, these ids allow you to recover resources even if you lost the Yoplanning ID.
Therefore, you can store your ID in the external_reference fields in many resources (client, order, session_group, session, payment, ...)
This is not mandatory at all.
Pagination
For all API methods that provides a large list of resources, pagination is used.
That means all the results will not be given in a single request. You will have to perform several request to get the full list of resources
You can see that as "pages in a book".
For each request, you can use query parameters (query string) in the url to navigate through the result.
Two query parameters can be provided : "offset" and "limit".
offset => the starting point where you want to retrieve data (you can see this as a cursor). Default : 0
limit => the number of result you want to retrieve per request. Default : 100 (which is also the maximum value)
Here is a full example using curl
1
2
3
4
5
curl -H "Content-Type: application/json"
-L "https://yoplanning.pro/api/v3.1/teams/
5a90332e-568f-4980-9859-88a984844a4d/clients?
offset=20&limit=2" -H 'Authorization: Token
4804c2cb4d87a13146d4de029f407c82149f2ada'
Here is an example of response for methods using pagination:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{
« count »:53,
« next »: »https://yoplanning.pro/api/v3.1/teams/
5a90332e-568f-4980-9859-88a984844a4d/clients?limit=2&offset=22 »,
« previous »: »https://yoplanning.pro/api/v3.1/
teams/5a90332e-568f-4980-9859-88a984844a4d/clients?
limit=2&offset=18 »,
« results »:[
{
« first_name » : « Jack »,
« last_name » : « Ichan »,
« email » : « jack.ichan@gmail.com »,
« phone_number » : « +32684952685 »,
« birth_date » : « 1975-05-22 »,
« language » : « fr »,
« note » : « Pretty cool client :) »,
« street » : « rue du phare »,
« city » : « Brest »,
« postal_code » : « 29200 »,
« state » : null,
« country » : « FR »
« id »: »7db70b5c-5175-4ba8-
b471-78006940b79c »
},
{
« first_name »: »Loic »,
« last_name »: »Lepoivre »,
« email »:null,
« phone_number »:null,
« birth_date »:null,
« language »:null,
« note »:null,
"street":null,
"city":null,
"postal_code":null,
"state":null,
"country":null,
"id":"669763dd-3bad-47a9-ac37-02d915a90bbe"
}
]
}
count => the total number of resources
next => the url to use to retrieve the next page. If
there is no next page, the value will be null.
previous => the url to use to retrieve the previous
page. If there is no previous page, the value will be
null.
results => the list of resources
Filters
For some endpoints, you can filter the results by adding query parameters to the request.
The following request will give you only the clients with first name "Norbert".
https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/clients?offset=20&limit=2&first_name=Norbert
For date and numeric fields, you can filter using __lt (lowet than), __gt (greater than), __lte (lowet than equal), __gte (greater than equal).
The following request will give you only the clients with birth date greater than 1995-01-25.
https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/clients?offset=20&limit=2&birh_date__gt=1995-01-25
Please see the endpoint documentation to know which fields can be used as filters (filters allowed)
Expand fields
For some endpoints, the resource object contains nested resources.
For example, a session contains staff.
Whenyou retrieve this resource (using a GET request), you will only retrieve the nested resource ids (here, staffs ids).To avoid sending more request, you can use the expand mechanism of the API to retrieve the full nested object
To do so, just append a query parameter in the url : " expand=" with the name of the nested resource you want to expand.
The following request will give you only the clients with birth date greater than 1995-01-25.
api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/payments/c21010f4-0e68-435b-b076-480087a49db1?expand=operator
You can use a dot notation to go deeper in the object.
/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/orders?expand=items.voucher.product
You can also expand several nested objects using a coma notation
/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/orders?expand=items.voucher.product,payments.operator
Please refer to each endpoint documentation to know which field is expendable.
Note: When you retrieve an instance using a GET request on an instance endpoint, some nested objects may be expanded by default. This forced expand is sometimes necessary in order to allow you to provide this JSON in a PUT request.
Important: If you want to retrieve a resource in order to update it with a PUT request, you MUST NOT USE the expand mechanism.
WebHook
Webhooks are also called "web callback" or "HTTP push API".
It is a notification system
You can subscribe to webhooks in order to be notified when a particular event occurs (for example, each time a client is created).
In order to subscribe, please contact us.
When subscribing to weekhooks, you will give us a callback url and tell us on which event and for which team you want to be notified.
How does it work?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
« resource »:
{ « id »: « 8d23503e-041e-4180-98d1-641183bc5ead »,
« type »: « client »
},
« link »: « https://yoplanning.pro/api/v3.1/teams/
5a90332e-568f-4980-9859-88a984844a4d/clients/
8d23503e-041e-4180-98d1-641183bc5ead »,
« event »: « updated »
}
resource.id => the resource that have been created /
modified / deleted
resource.type => the type of resource (client / session /
member, etc…)
link => the url to use to retrieve the resource.
event => the event fired
When you receive a POST request on the callback url, you will be able to send a GET request to the Yoplanning API using the "link" field to retrieve the corresponding resource.
Don't forget to add authentication information when calling the API!
Important : When you receive a webhook, you can send a GET request to the API in order to retrieve the changes and update your system.
Then, never send a PUT request, it could lead to infinite loop.
Errors
Yoplanning uses HTTP response status codes to indicate the success or failure of your API requests.
In general, there are three status code ranges you can expect:
● 2xx success status codes confirm that your request worked as expected
● 4xx error status codes indicate an error because of the information provided (e.g., a required parameter was omitted)
● 5xx error status codes are rare and indicate an error with Yoplanning's servers. You can still get this error in some rare case if the data you provide are not valid
4xx errors include some data to help you identify what was the problem.
Here is an example:
1
{« price »:[« This field is required. »]}
Keys : The name of the fields that have wrong value
Value : A list of string describing the errors corresponding to this field.
API References
/api/v3.1/teams/
/api/v3.1/teams/
POST GET
For resource description and JSON, please see :
● /api/v3.1/teams/<teamId>/clients/<pk>
GET : Return all teams for which you have permissions.
See « Pagination » for more information about object list.
POST : Create a new team.
/api/v3.1/teams/<teamId>/online-products/
GET
This endpoint is used to retrieve all the products that can be sold online.
This resource is adapted to booking engine needs.
If the team you request is a dealer (reseller) for other teams, you will also get those other teams products. In that case, you might want to filter to retrieve only product of a specific team.
Query parameters :
All transalatable fields (like title, description, etc...) will be translated in the response
Default : en
Filters allowed :
Ex : 302, team_id, last_modified__lt, last_modified__gt
If you want to use last_modified filter, please provide a UTC datetime.
If you provide times, please use the following format in the url:
" 2019-05-23+10:53:00 " (the + is the standard space character for query strings)
● /api/v3.1/teams/<teamId>/online-products/
GET : retrieve all the products which can be sold online
Online Product object
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
{
« id »: »a47f7563-df65-4ced-b18a-14d79d004b0b »,
« title »: »Voile 3 jours »,
« last_modified »: »2018-06-03T18:30:00 »,
« description »: »Une super sortie voile »,
« private_session »: false,
« description_image »: »https://yoplanning.pro/
media/uploads/product/description/hd_Jpt8Wyv.jpg »,
« location »:{
« meeting_point »: »sur le quai »,
« address »: »44 route du moulin »
},
« participants »:{
« target »: »ALL », #Possible values :
« ALL », « CHILDREN », « ADULTS »
« expected_data »:[ #These are the data
that are expected for each participants (in addition to
their first_name and last_name) when creating a booking
{
« type »: »email », #possible value :
number, text, textarea, email, date, select
« label »: »Email », #The label to
display on the web page
« required »:false, #true if required,
false if optional
« field »: »email » #The name of the
field to send back to Yoplanning when creating a
booking
« options » : [« id » : « Weight »,
« name » : « Poids »] #only present for the
« select » type. « name » is translated and should ONLY
be use for display.
}
],
« level »: »ALL », #Possible values :
« ALL », « BEGINNER », « INTERMEDIATE », « ADVANCED »
"maximum":10 #The standard maximum
participant for a session of this product
},
"category":{
"id":304,
"name":"Bodyboard"
},
"sessions":{
"other_prices":[ #These are the special
prices like member
{
"label":"Child",
"price":{
"tax_excluded":"5.50",
"tax_included":"6.00"
}
}
],
"standard_price":{ #This is the
standard price of the product. Be carefull : this is
just an indication ! The real price is only accessible
in online-availabilities endpoint
"tax_excluded":"12.00",
"tax_included":"13.00"
}
},
"vouchers":{ #A voucher is a
ticket without date. You can sell at the following
price
"expiration":12,
"other_prices":[
{
"label":"Child",
"price":{
"tax_excluded":"40.50",
"tax_included":"49.00"
}
}
],
"standard_price":90.20
}
}
Tutorials
Here are some tutorials to help you go through your integrations:
Booking engine worflow : how to sell activities based on Yoplanning API
