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.

Information

If you have requested access to the ML Open API and webhook functionality we will send two API Keys upon activation of your integration. The API Keys are used for inbound requests to our endpoints and outbound requests of our webhook events.

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.

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:

Copy
Copied
{
  "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:

Http Code Reason
400 Validation of the request failed, check request with specification.
401 Authentication failed. Probably wrong or missing OpenAPI key.
403 Permission denied. The caller has no permission for the requested resource.
404 Requested entity not found.
500 Unexpected system error - internal problem.