API documentation

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 require authentication.
We use standard token-based authentication system. To authenticate, just provide your API token on the header of each request like so:
Authorization: Token 4804c2cb4d87a13146d4de029f407c82149f2ada
Be careful : the space between "Token" and the token is important.

Here is a full example using curl

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'

If you don't provide a token or if the token is invalid, the API will respond with a 401 HTTP code (Unauthorized) and will give you a "details" field in the response JSON to help you understand the problem.
{"detail":"Invalid token."} or {"detail":"Authentication credentials were not provided."}

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.
{"detail":"You do not have permission to perform this action."}

Throttling

For security reasons, the number of requests 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 :
{"detail":"Request was throttled. Expected available in 86368 seconds."}

Overview

Team

The team is the most fundamental concept in Yoplanning (which is a collaborative tool).
Almost all methods take a teamId parameter in the url. That means all the actions are relative to a team.

UUID

Lots of methods requires an "id" 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 resources, 2 endpoints are available :
- one to access a specific instance. The endpoint basically ends with {id}, for example :
/api/v3.1/teams/{teamId}/clients/{id}/

You can call these endpoints with the following http verbs :

GET : Retrieve the resource
PUT : Update the resource. For many endpoints, this will also create the resource if it does not exist
DELETE : Delete the resource

- one to access the instances manager : You call these endpoints with the following http verbs :
/api/v3.1/teams/{teamId}/clients

GET : get a list of all resources (see Pagination)
POST : create a new resource (The id will be generated 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 :

Retrieve the resource with a GET request
Modify the JSON data
Send a PUT request with the updated JSON

If you don't, the API may reject you because some nested resources require an ID that you don't give.
In addition, you may loose some data.

Online selling

For online selling purposes (retrieving products and availabilities), only 2 endpoints should be used:

/api/v3.1/teams/{teamId}/online-products/
/api/v3.1/teams/{teamId}/online-products/{productId}/availabilities/

Storing your ID

It might be useful to store your own id on each resource you manage, especially if you want to synchronize your system with Yoplanning.
For example, in case of synchronization 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 requests 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 results you want to retrieve per request. Default : 100 (which is also the maximum value)

For example :


		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:


		{  
		   "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"
		      }
		   ]
		}

Explanation:

 
		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 (lower than), __gt (greater than), __lte (lower than or equal), __gte (greater than or 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&birth_date__gt=1995-01-25

Please see each 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.
When you retrieve this resource (using a GET request), you will only retrieve the nested resources ids (here: staff ids).
To avoid sending more requests, 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.
/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 comma 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 expandable.
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.

Webhooks

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.

How does it work?
When subscribing to webhooks, you will give us a callback url and tell us on which event and for which team you want to be notified.
When this event is fired on this team, we will send a POST request on the callback url with data formatted like this :


{
    "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 provided is not valid

4xx errors include some data to help you identify what was the problem. Here is an example:
{"price":["This field is required."]}
Keys: The name of the fields that have wrong value.
Values: A list of string describing the errors corresponding to this field.