Getting started

Create a Toornament account

To use the Toornament API, you first need to have a Toornament account and access to the Organizer dashboard. If you're new to Toornament, create an account and validate your email address. You can then access the Organizer Dashboard.

Create a project

You need to have a project in the Organizer dashboard, which is a container for tournaments and the basis for our subscription-based plans. If it is not the case, you just need to create a new project.

Your project needs a plan that includes an API Access. If you don't have a plan that includes an API access, contact us to discuss an API plan together.

Create an application

To access the API, you must have an active application. If you do not have one yet, you can create a new application in your project settings. You can find an application's credentials in its details. These credentials are to be kept secret, and will be used to perform API calls.

Note that the application can only access tournaments from the project. You can not access data from other projects.

Using the Toornament API requires you to provide credentials that authorize the access to your data. The credentials involve both authentication (API key) and authorization (OAuth 2 access token). The API key can be found in the application details. The access token is issued using the Client Credentials grant type in OAuth 2.

Getting an access token requires your application to call a specific endpoint. Your application must provide its OAuth 2 credentials and a scope to describe the actions that you wish to perform. The endpoint should then return a temporary access token limited to the requested scope.

For more information, see Authentication, Authorization, Scopes and OAuth 2 endpoint.

The Toornament API is based on the REST architectural style and uses the HTTP protocol. All resources are represented in JSON format and accessed using HTTP methods.

Identify endpoints

Before making any requests, you should identify the API and endpoints that will best match the needs of your project:

If you need more details on the different endpoints provided with the Toornament API, you can find more information in the Core concepts.

Perform requests

Requests are performed using HTTP requests. Because the Toornament API uses REST, you should always pay attention to the resource URI and request method.

When preparing your request, make sure to include the API key and access token in the HTTP request headers. If pagination is involved, you must provide an additional HTTP header to specify the range of data requested. (see Pagination for more information)

Process responses

Each request on the API will be followed by a response including a status code. This code will let you know whether the request was successful or not. (see Response codes for more information)

Depending on the resource and the method used, the response could also contain additional information related to the request. If pagination is involved, the response will also provide additional HTTP headers to specify the range of data returned (see Pagination for more information)

Webhooks are used if you need to be informed when certain events occur instead of having to constantly check if data has changed. The Webhook API provides a way for you to declare your own endpoints that will be notified of changes happening in your project.

Create a webhook

To create a webhook, you must first register your endpoint on the Webhook API. This process implies that your endpoint is reachable and ready to answer a verification request. This request will verify that you are the legitimate owner of that endpoint. It will also provide a security token, to be saved for later use, in order to ensure that further communication can not be tampered with.

Subscribe to events

When a webhook has been registered, it can subscribe to certain events related to a tournament or a project. When an event occurs, subscribed webhooks are informed of the occurrence. You can perform additional requests to other endpoints if you need more information to process the event. If your webhook could not be reached, the Webhook API will try again during the next 24 hours.

For more information about webhooks, see Webhooks.