Magicline Connect API (1.0.0)

Download OpenAPI specification:Download

URL: https://developer.magicline.com/

Scope of this API

This API can be used to integrate Magicline operations into third party clients like websites or apps.

Following operations are supported

  • Online contract conclusion
  • Trial session slot booking
  • Lead creation

Campaigns

List your marketing campaigns

List all campaigns

Request
query Parameters
studioId
required
integer <int64>
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/campaign

Contracts

Cancel contracts

List rate bundles (german wording: Angebote)

Request
query Parameters
studioId
required
integer <int64>

The Id of the studio to fetch the rate bundles from

Example: studioId=1
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/rate-bundle

Create a new customer and a new contract

Request
Request Body schema: application/json
required
studioId
required
integer <int64>
referralId
integer <int64>
required
object (ConnectApiContractDataDto)
required
object (ConnectApiCreatePublicCustomerDto)
landingPageConfigurationId
integer <int64>
voucherCode
string

Only vouchers of type 'Credit' or 'Discount' are supported here.

offerUuid
string <uuid>
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

post/connect/v1/rate-bundle
Request samples
application/json
{
  • "studioId": 0,
  • "referralId": 0,
  • "contract": {
    },
  • "customer": {
    },
  • "landingPageConfigurationId": 0,
  • "voucherCode": "string",
  • "offerUuid": "5d19bb70-d72b-45ae-9b5e-c4257877bdbb"
}

getActiveContracts

Request
query Parameters
recaptchaToken
required
string

client generated Google reCAPTCHA token

Request Body schema: application/json
required
firstname
required
string
lastname
required
string
dateOfBirth
required
string <date>
customerNumber
string
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

post/connect/v1/contracts
Request samples
application/json
{
  • "firstname": "string",
  • "lastname": "string",
  • "dateOfBirth": "2019-08-24",
  • "customerNumber": "string"
}

cancelContract

Request
query Parameters
recaptchaToken
required
string

client generated Google reCAPTCHA token

Request Body schema: application/json
required
firstname
required
string
lastname
required
string
dateOfBirth
required
string <date>
customerNumber
required
string
contractId
required
integer <int64>
cancellationType
required
string
Enum: "ORDINARY_CANCELLATION" "EXTRAORDINARY_CANCELLATION"
cancelationReasonId
integer <int64>
cancellationDate
required
string <date>
additionalInformation
string
confirmationEmail
string
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

post/connect/v1/contracts/cancel
Request samples
application/json
{
  • "firstname": "string",
  • "lastname": "string",
  • "dateOfBirth": "2019-08-24",
  • "customerNumber": "string",
  • "contractId": 0,
  • "cancellationType": "ORDINARY_CANCELLATION",
  • "cancelationReasonId": 0,
  • "cancellationDate": "2019-08-24",
  • "additionalInformation": "string",
  • "confirmationEmail": "string"
}

cancelContractManual

Request
query Parameters
recaptchaToken
required
string

client generated Google reCAPTCHA token

Request Body schema: application/json
required
firstname
required
string
lastname
required
string
dateOfBirth
required
string <date>
customerNumber
string
additionalInformation
string
studioId
integer <int64>
cancellationDateType
required
string
Enum: "NEXT_POSSIBLE_CANCELLATION_DATE" "ABSOLUTE_CANCELLATION_DATE"
cancellationDate
string <date>
cancelationReasonId
integer <int64>
cancellationType
required
string
Enum: "ORDINARY_CANCELLATION" "EXTRAORDINARY_CANCELLATION"
confirmationEmail
string
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

post/connect/v1/contracts/cancel-request
Request samples
application/json
{
  • "firstname": "string",
  • "lastname": "string",
  • "dateOfBirth": "2019-08-24",
  • "customerNumber": "string",
  • "additionalInformation": "string",
  • "studioId": 0,
  • "cancellationDateType": "NEXT_POSSIBLE_CANCELLATION_DATE",
  • "cancellationDate": "2019-08-24",
  • "cancelationReasonId": 0,
  • "cancellationType": "ORDINARY_CANCELLATION",
  • "confirmationEmail": "string"
}

getActiveStudiosInGermanyV2

Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v2/contracts/studios

getStudioInfo

Request
path Parameters
studioId
required
integer <int64>
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/contracts/studios/{studioId}

Terminal

/terminal

getCustomerDataByCodiceFiscale

Request
query Parameters
codiceFiscale
required
string
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/terminal/customer-data-by-codicefiscale

TrialSessions

Allow prospects to book a trial session

Book a trial session

Book a free slot. Might return errorCode CONFLICT if configured resources are overbooked for this slot. In this case its advised to reload free slots and let the user select a different slot. If you get a validation error make sure all required fields are filled. Required fields are returned by the /config/validation endpoint.

Request
Request Body schema: application/json
required
studioId
required
integer <int64>
startDateTime
required
string <date-time>
required
object (CommonTrialSessionLeadCustomerDto)
note
string [ 0 .. 300 ] characters
referrerId
integer <int64>
participants
integer <int32>
sourceCampaignId
integer <int64>
referralCode
string [ 0 .. 300 ] characters
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

post/connect/v1/trialsession/book
Request samples
application/json
{
  • "studioId": 1,
  • "startDateTime": "2019-04-15T07:00:00Z",
  • "leadCustomer": {
    },
  • "note": "become fit",
  • "referrerId": 10,
  • "participants": 2,
  • "sourceCampaignId": 2,
  • "referralCode": "ABCXYZ"
}

Get free slots for a trial session

Returns free slots for a studio where a trial session appointment can be booked.

Request
query Parameters
studioId
required
integer <int64>
Example: studioId=1
startDate
required
string <date>
Example: startDate=2021-05-15
endDate
required
string <date>
Example: endDate=2021-05-21
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/trialsession

Get mandatory field configuration

Returns the configuration which needs to be considered e.g. for form fields and their validation.

Request
query Parameters
studioId
required
integer <int64>
Example: studioId=1
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/trialsession/config/validation

Referral

Additional referral information for member creation

List all referrals by studioId

Request
query Parameters
studioId
required
integer <int64>

Studio Id

Example: studioId=1
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/referral

CreditCard Tokenization

Store credit cards for new members

Initiate Tokenization

Request
Request Body schema: application/json
required
paymentMethod
required
string

Payment Method, is obtained from Adyen card component and must be serialized to string

browserInfo
required
string

Browser Info object, is obtained from Adyen card component and must be serialized to string

studioId
required
integer <int64>

Studio Id

returnUrl
required
string

Return url for redirects. If user is redirected to banking page, he will be redirected to this url after authentication.

origin
required
string

Origin, obtained via window.location.origin

Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

post/connect/v2/creditcard/tokenization/initiate
Request samples
application/json
{
  • "paymentMethod": "string",
  • "browserInfo": "string",
  • "studioId": 0,
  • "returnUrl": "string",
  • "origin": "string"
}

Complete Tokenization

Request
path Parameters
tokenizationReference
required
string

Tokenization reference you'll get via initiate endpoint

Request Body schema: application/json
required
redirectResult
string

Redirect result

threeDSResult
string

3DS Result

Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

post/connect/v1/creditcard/tokenization/{tokenizationReference}/complete
Request samples
application/json
{
  • "redirectResult": "string",
  • "threeDSResult": "string"
}

Load payment methods

Request
query Parameters
studioId
required
integer <int64>

Studio Id

Example: studioId=1
countryCode
required
string

Country code

Example: countryCode=DE
locale
required
string

Locale

Example: locale=de-DE
Responses
200

Get payment methods, the contained paymentMethodsJson must be deserialized and passed to the Adyen web component

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v2/creditcard/tokenization/payment-methods

Get Tokenization state

Request
path Parameters
tokenizationReference
required
string
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/creditcard/tokenization/{tokenizationReference}/state

Image

Allow prospect to upload image

generatePreSignedUrlForPreUpload

Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/prospectimage/uploadurl

Promotions

Getting information about external promotion participation

confirmCustomerParticipation

Request
query Parameters
payload
required
string
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

post/connect/v1/promotion/confirm-participation

AddressData

/addressdata

getProvinceInformation

Request
query Parameters
zipCode
required
string
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/addressdata/italy/province

ContractVoucher

/contractvoucher

Redeem a ContractVoucher. Only Vouchers of type 'Rate' are supported here.

Request
path Parameters
contractVoucherCode
required
string
Request Body schema: application/json
required
organizationUnitId
integer <int64>
contractStartDate
string <date>
contractStartPreuseDate
string <date>
object (ConnectApiCreatePublicCustomerDto)
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

post/connect/v1/contractvoucher/{contractVoucherCode}/redeem
Request samples
application/json
{
  • "organizationUnitId": 0,
  • "contractStartDate": "2019-08-24",
  • "contractStartPreuseDate": "2019-08-24",
  • "customerDto": {
    }
}

Validates a ContractVoucher and returns basic voucher information to display. Only Vouchers of type 'Rate' are supported here.

Request
path Parameters
contractVoucherCode
required
string
query Parameters
organizationUnitId
required
integer <int64>
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/contractvoucher/{contractVoucherCode}/validate

Validation

/validation

Validates the taxId against country based validation rules.

For some countries additional customer related attributes might be needed for that. Country will be derived from given studioId.

Request
Request Body schema: application/json
required
studioId
required
integer <int64>

Is needed to determine country specific validation rules

firstname
required
string
lastname
required
string
taxId
required
string

Is country specific, like CodiceFisacale in Italy

dateOfBirth
required
string <date>
placeOfBirth
string

addition for Italy if customer is national

countryOfBirth
string

addition for Italy if customer isn't national

Enum: "UNDEFINED" "AC" "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AN" "AO" "AQ" "AR" "AS" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BU" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CP" "CR" "CS" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DG" "DJ" "DK" "DM" "DO" "DZ" "EA" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "EU" "EZ" "FI" "FJ" "FK" "FM" "FO" "FR" "FX" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GU" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "IC" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MH" "MK" "ML" "MM" "MN" "MO" "MP" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NT" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PR" "PS" "PT" "PW" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SF" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SU" "SV" "SX" "SY" "SZ" "TA" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TP" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UK" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VI" "VN" "VU" "WF" "WS" "XI" "XU" "XK" "YE" "YT" "YU" "ZA" "ZM" "ZR" "ZW"
gender
string

User will be assigned as UNISEX if no gender is set.

Enum: "MALE" "FEMALE" "UNISEX"
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

post/connect/v1/validation/taxId
Request samples
application/json
{
  • "studioId": 0,
  • "firstname": "string",
  • "lastname": "string",
  • "taxId": "string",
  • "dateOfBirth": "2019-08-24",
  • "placeOfBirth": "string",
  • "countryOfBirth": "UNDEFINED",
  • "gender": "MALE"
}

Previews

getPreview

Request
query Parameters
landingPageConfigurationId
integer <int64>
checkoutPageConfigurationId
integer <int64>
Request Body schema: application/json
required
studioId
required
integer <int64>
referralId
integer <int64>
required
object (ConnectApiContractDataDto)
required
object (ConnectApiCreatePublicCustomerDto)
landingPageConfigurationId
integer <int64>
voucherCode
string

Only vouchers of type 'Credit' or 'Discount' are supported here.

offerUuid
string <uuid>
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

post/connect/v2/preview
Request samples
application/json
{
  • "studioId": 0,
  • "referralId": 0,
  • "contract": {
    },
  • "customer": {
    },
  • "landingPageConfigurationId": 0,
  • "voucherCode": "string",
  • "offerUuid": "5d19bb70-d72b-45ae-9b5e-c4257877bdbb"
}

getPreview_1

Request
query Parameters
landingPageConfigurationId
integer <int64>
checkoutPageConfigurationId
integer <int64>
Request Body schema: application/json
required
studioId
required
integer <int64>
referralId
integer <int64>
required
object (ConnectApiContractDataDto)
required
object (ConnectApiCreatePublicCustomerDto)
landingPageConfigurationId
integer <int64>
voucherCode
string

Only vouchers of type 'Credit' or 'Discount' are supported here.

offerUuid
string <uuid>
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

post/connect/v1/preview
Request samples
application/json
{
  • "studioId": 0,
  • "referralId": 0,
  • "contract": {
    },
  • "customer": {
    },
  • "landingPageConfigurationId": 0,
  • "voucherCode": "string",
  • "offerUuid": "5d19bb70-d72b-45ae-9b5e-c4257877bdbb"
}

Leads

Create leads for prospective customers

Request
Request Body schema: application/json
required
studioId
required
integer <int64>
firstname
required
string [ 0 .. 100 ] characters
firstname2
string [ 0 .. 100 ] characters

addition for Turkey

lastname
required
string [ 0 .. 100 ] characters
lastname2
string [ 0 .. 100 ] characters

addition for Spain

taxId
string [ 0 .. 300 ] characters

addition for Spain and Italy

dateOfBirth
string <date>
email
string [ 0 .. 300 ] characters
gender
string

User will be assigned as UNISEX if no gender is set.

Enum: "MALE" "FEMALE" "UNISEX"
phone
string [ 0 .. 300 ] characters
street
string [ 0 .. 300 ] characters
streetType
string [ 0 .. 300 ] characters

addition for Spain (e.g. calle)

streetBlock
string [ 0 .. 300 ] characters

addition for Spain

portal
string [ 0 .. 300 ] characters

addition for Spain

stairway
string [ 0 .. 300 ] characters

addition for Spain

floor
string [ 0 .. 300 ] characters

addition for Spain

door
string [ 0 .. 300 ] characters

addition for Spain

province
string [ 0 .. 300 ] characters

addition for southern Europe countries (e.g. Madrid)

additionalAddressInformation
string [ 0 .. 300 ] characters

addition for Spain

houseNumber
string [ 0 .. 100 ] characters
city
string [ 0 .. 300 ] characters
zipCode
string [ 0 .. 100 ] characters
countryCode
string [ 0 .. 300 ] characters
locale
string [ 0 .. 300 ] characters

locale of customer as ISO 639-1 two-letter language and country code (e.g. es_ES or de_DE)

notes
string [ 0 .. 1000 ] characters
sourceCampaignId
integer <int64>
object (PublicApiPrivacyConfigurationDto)

Data privacy configuration for marketing purposes. Deprecated. Use communicationPreferences instead.

Array of objects (CustomerCommunicationPreferencesData)

Communication preferences for the customer. If specified, the list must contain an element for each message category.

Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

post/connect/v1/lead
Request samples
application/json
{
  • "studioId": 0,
  • "firstname": "string",
  • "firstname2": "string",
  • "lastname": "string",
  • "lastname2": "string",
  • "taxId": "string",
  • "dateOfBirth": "2019-08-24",
  • "email": "string",
  • "gender": "MALE",
  • "phone": "string",
  • "street": "Raboisen",
  • "streetType": "string",
  • "streetBlock": "string",
  • "portal": "string",
  • "stairway": "string",
  • "floor": "string",
  • "door": "string",
  • "province": "string",
  • "additionalAddressInformation": "string",
  • "houseNumber": "3-4",
  • "city": "Hamburg",
  • "zipCode": "22099",
  • "countryCode": "DE",
  • "locale": "string",
  • "notes": "any notes about this lead",
  • "sourceCampaignId": 0,
  • "privacyConfiguration": {
    },
  • "communicationPreferences": [
    ]
}

Returns information about an existing lead record

Request
path Parameters
uuid
required
string <uuid>
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/lead/{uuid}

Studios

List all studios

You can add optional filters. Parameters addressSearchQuery and studioTags are combined by AND

Request
query Parameters
studioTags
Array of strings

Filter by identifier of StudioTag (german wording: Standort Code). Dynamic attribute configured at studio (e.g for Brands or Locations). Multiple Tags are combined by OR.

addressSearchQuery
string

Search prefix for zipCode or city of studio address.

Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v2/studio

Fetch information for one studio

Request
path Parameters
studioId
required
integer <int64>
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v2/studio/{studioId}

Fetch detail information for one studio

Request
path Parameters
studioId
required
integer <int64>
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v2/studio/details/{studioId}

Get utilization for the studio.

Return information about the utilization of this studio. Needs to be enabled for public view in the configuration.

Request
path Parameters
studioId
required
integer <int64>
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/studio/{studioId}/utilization

getSepaAgreementText

Request
path Parameters
studioId
required
integer <int64>
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/studio/{studioId}/sepa/agreement

getSepaAgreementTextForRateBundle

Request
path Parameters
studioId
required
integer <int64>
rateBundleId
required
integer <int64>
query Parameters
language
string

Language to pick the right translation (IETF BCP 47 language tags)

Example: language=de-DE
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/studio/{studioId}/rate/{rateBundleId}/sepa/agreement

Get the studio's default communication settings.

Get the studio's default communication settings. The returned list contains an entry for each existing message category.

Request
path Parameters
studioId
required
integer <int64>
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/studio/{studioId}/communication-settings

I18n

Returns a list of tuples with every available country code and the localized country name

Request
query Parameters
locale
required
string
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/i18n/countries

FeatureCheck

Lists all active features of the organization unit

Request
query Parameters
organizationUnitId
required
integer <int64>
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/featurecheck/activefeatures

BankAccount

validateIbanAndLookupBic

Request
query Parameters
iban
required
string
organizationUnitId
integer <int64>
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/bankaccount

validateAccountHolderName

Request
query Parameters
accountHolder
required
string
Responses
200

OK

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

get/connect/v1/bankaccount/validate/accountholder