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. 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://partner.open-api.magicline.com/v1/customers URL.

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.

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. We provide an offsetId parameter to control where the next chunk should start from. To fetch the next chunk use returned lastOffsetId in succeeding request. Last chunk is indicated by hasNext: false property value. Example response:

{
  "result": [
    {
      "id": 1210206595,
      "firstName": "Eduardo",
      "lastName": "Thomas",
      "dateOfBirth": "2018-01-01",
      "email": null,
      "gender": "UNISEX",
      "street": "Mörikestraße",
      "houseNumber": "27",
      "zipCode": "24113",
      "city": "Molfsee",
      "country": "DE",
      "status": "MEMBER",
      "cardNumbers": [
        "499799201"
      ]
    },
    {
      "id": 1210206596,
      "firstName": "Terrence",
      "lastName": "Hernandez",
      "dateOfBirth": "2018-01-01",
      "email": null,
      "gender": "UNISEX",
      "street": "Talstraße",
      "houseNumber": "144",
      "zipCode": "68259",
      "city": "Mannheim",
      "country": "DE",
      "status": "MEMBER",
      "cardNumbers": [
        "2644351101"
      ]
    }
  ],
  "lastOffsetId": 1210206596,
  "hasNext": true
}

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: