Becoming familiar with Synerise API Reference

Our API reference is an extensive source of knowledge that keeps growing and receiving regular updates.

Take a few minutes to become familiar with the format of the reference and how to navigate it.

For the purpose of this article, we make the following distinctions:

  • A service is short for a microservice that exposes endpoints for your usage.
  • An endpoint is a resource available at a URL, within a service.
  • A method is the HTTP method used with the endpoint, for example GET or POST. An endpoint may expose more than one method under the same URL.

When reading the API reference itself, you may encounter the word endpoint used in the “HTTP method + URL” meaning.

When you access the main page of the API Reference, you will see tiles that represent logical categories.

Click a tile to see its subcategories as bars.
These bars correspond directly to the subcategories displayed in the left panel of each category's reference page. Once you access a reference page, you don't need to return to the bar view to see another subcategory - instead, click that category in the left panel.

Note: The “Authentication” section is not a subcategory. It's a description of the JWT authorization method, included in every category.
Image shows the relation between bars and subcategories
The bars and the subcategories in the reference page are the same.

Reading the reference page

Browsing methods

Overview of a method
Overview of a method's basic information
  1. Clicking the Synerise logo takes you to the API Reference home page.
  2. The buttons on the right lead to other resources.
  3. The methods are grouped into logical subcategories.
  4. Each method has a title and an icon that shows the method type.
  5. The description offers some basic information about the method's usage.
    To learn more about permissions, read this article.
  6. The Authorizations field informs about the type of authorization used by the method. Some methods do not require authorization.
  7. This is the path of the method. Click to see the full URL.

Basic information

Example path parameters
  1. The Parameters section includes the headers, path parameters, and query parameters that occur in this method.
  2. Required entities and fields are marked this way.
  3. This is the name of the entity.
  4. This is the type of the entity.
  5. This is a list of allowed values, if applicable.
  6. The description offers more detailed information about the entity.
Tip: If a default value is listed, it's usually assumed by the backend unless you provide a different one.

Reading request and response body schemas

Fragment of a request body definition

The Request body schema section outlines the JSON body of the request, if applicable.

  1. The arrow means that the entity is an object or an array. Click it to expand the details.
  2. Some entities have longer descriptions that are initially collapsed for easier browsing. Click to expand.
  3. The buttons toggle between different schemas of an entity. “One of” means that you can only pick one, “Any of” means that you can pick any combination. If restrictions exist, they are mentioned in the description.

To see the schema of a response, click the bar. The schema expands:

Response schema

Request and response samples

The samples visualize the schema and offer help in a few programming languages.

Important: The samples are auto-generated from the schema and do not take into account relations between fields. If there are logical relations between fields, they are outlined in the body description.
Code and response samples
😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.