General Information

The Magicline Open API allows Third Party applications to access our data in a common and standardized manner. You can use this API to get customers, contracts and other information. We use OpenAPI 3.0. specifications for all our endpoints.

Authentication

The Magicline Open API uses persistent key authentication, separate for every studio in Magicline. Keys are generated automatically when a studio owner requests an integration with your App. Upon activation, you will receive an email with OpenAPI studio keys and the base URL. In order to authenticate properly you have to send the OpenAPI key in x-api-key header. We will validate the key and check whether it is valid and matches the current studio.

API requests

All API requests must be made over HTTPS. The https://<tenant_name>.open-api.magicline.com/v1 URL is the request base URL. The complete URL varies depending on the accessed resource.

For example, to get a list of customers from a specific facility, you must make an HTTP GET request to the https://<tenant_name>.open-api.magicline.com/v1/customers URL.

The base URL, including the <tenant_name>, is part of the activation email and must always match the corresponding x-api-key. If you have registered webhooks you must look up the base URL by the x-api-key header you receive with every webhook event.

Image handling

Please take into consideration that all URLs with an image to download will expire after a specified time. The exact expiration time can be found documented in the endpoint response field.

Rate limit

All Open API endpoints have a rate limit. Every endpoint has a separate request counter. The default rate limit is 1000 requests per minute. After exceeding the limit, every request for the next minute will be denied with a 429 response code.

Data chunking

Certain GET calls, especially bulk requests, may return a large number of records. To make handling large payloads easier, we provide a way to control the maximum number of responses through data chunking. There are two different ways this is achieved, explained below. But in short: If you use the returned offset value from the response in your next request, you should always get continuous results.

In the first example, theoffset reflects the exact id where the next chunk should start from. To fetch the next chunk use returned offset in succeeding request. Last chunk is indicated by hasNext: false property value. Example response:

{
  "result": [
    {
      "id": 1210206595,
      "firstName": "Eduardo",
      "lastName": "Thomas"
    },
    {
      "id": 1210206596,
      "firstName": "Terrence",
      "lastName": "Hernandez"
    }
  ],
  "offset": "1210206596",
  "hasNext": true
} 

In this example, the next chunk would be requested by calling GET /endpoint?offset=1210206596

Theoffset parameter can also be calculated as sum of the givensliceSize value and the last given offset, reflecting an actual paginating of the results. For example, if your request contains the offset 0 and a sliceSize of 2, the returned offset will be 2. You may take this value for the next request (offset 2, sliceSize 2) to get the next chunk of results, with a returned offset of 4, and so on. Last chunk is indicated by hasNext: false property value. Example for the first chunk with a sliceSize of 2:

{
  "result": [
    {
      "firstName": "Eduardo",
      "lastName": "Thomas"
    },
    {
      "firstName": "Terrence",
      "lastName": "Hernandez"
    }
  ],
  "offset": "2",
  "hasNext": true
}

In this example, the next chunk would be requested by calling GET /endpoint?offset=2

Error Handling

The ML Open API uses HTTP Status codes to reflect a successful or unsuccessful request. 2XX status codes represent a successful request, 4XX/5XX status codes represent an error. If you receive an error status code, check the body for an error code and message. Table of error codes:

Multipart/form-data requests

Some endpoints require a multipart/form-data request, meaning that the request body is a combination of json and binary data. In this case, the content type of the request must be set to multipart/form-data and the json data request part must be of type application/json. The binary data must be sent as a separate part of the request. Here is a curl example of a multipart/form-data request (In this example the json data request part is called 'data' and the binary data request part is called document):

curl --location 'https://example.magicline.com/v1/memberships/1283046050/self-service/idle-periods' \
--header 'x-api-key: *****************************' \
--header 'Content-Type: multipart/form-data' \
--form 'data="{\"startDate\": \"2024-10-24\",\"temporalUnit\": \"MONTH\",\"termValue\": 1,\"reasonId\": 1}";type=application/json' \
--form 'document=@"/path/to/file´"'