magicline-api

name

magicline-api

description

Magicline fitness studio management API reference — covers OpenAPI, Connect API, and Device API for customer management, memberships, classes, appointments, payments, and device integrations. Use this skill whenever the user mentions Magicline, works with Magicline APIs, builds integrations for fitness studios using Magicline, references endpoints like /v1/customers or /v1/memberships, or needs help with Magicline-specific patterns like preview/execute flows, dry-run device operations, or Connect API contract conclusion. Also use when you see API keys with X-API-KEY headers in a Magicline context, or the user references redocly.sportalliance.com documentation.

Magicline API Reference

Magicline provides APIs for managing fitness studios — customers, memberships, classes, appointments, payments, and device integrations. This skill helps you navigate the API ecosystem and build correct integrations.

Choosing the Right API

API	Use When	Base URL (Demo)	Auth
OpenAPI	Back-office operations, full CRUD, studio management	https://open-api-demo.open-api.magicline.com	X-API-KEY header
Connect API	Public-facing integrations (websites, member apps) — contract signup, trial booking, lead capture	https://connectdemo.api.magicline.com	X-API-KEY header
Device API	Hardware integrations — card readers, vending machines, timed equipment	https://open-api-demo.devices.magicline.com	Authorization: Bearer <token>

Decision guide:

• Building a member-facing website or app? → Connect API
• Building internal tools, admin dashboards, or data sync? → OpenAPI
• Integrating physical hardware (turnstiles, vending, solarium)? → Device API

Reference Documentation

All endpoint-level documentation lives in the references/ directory. Navigate to the right file based on what the user needs:

OpenAPI Endpoints

Overview: references/magicline/apis/magicline/openapi/openapi.md General info (auth, pagination, rate limits): references/magicline/apis/magicline/openapi/general-information.md

Domain	Path	Key Operations
Customers	references/magicline/apis/magicline/openapi/openapi/customers/	CRUD, search, access mediums, contracts, benefits, documents
Memberships	references/magicline/apis/magicline/openapi/openapi/memberships/	Offers, signup (preview + execute), switch, cancel
Membership Self-Service	references/magicline/apis/magicline/openapi/openapi/membership-self-service/	Contract cancel, idle periods, additional modules
Classes	references/magicline/apis/magicline/openapi/openapi/classes/	List classes, get slots, book, cancel, validate
Appointments	references/magicline/apis/magicline/openapi/openapi/appointments/	Bookable appointments, slots, book, validate, delete
Trial Offers	references/magicline/apis/magicline/openapi/openapi/trial-offers/	Trial config, lead customers, trial bookings
Customer Accounts	references/magicline/apis/magicline/openapi/openapi/customers-account/	Balance, transactions, payments, payment instruments
Customer Self-Service	references/magicline/apis/magicline/openapi/openapi/customers-self-service/	Contact/address/master/payment data amendments
Communication	references/magicline/apis/magicline/openapi/openapi/customers-communication/	Threads, preferences
Finance	references/magicline/apis/magicline/openapi/openapi/finance/	Debt collection, exports, transfers
Studios	references/magicline/apis/magicline/openapi/openapi/studios/	Studio info, utilization, tags
Employees	references/magicline/apis/magicline/openapi/openapi/employees/	List, get by ID
Devices	references/magicline/apis/magicline/openapi/openapi/devices/	List devices, activate
Leads	references/magicline/apis/magicline/openapi/openapi/leads/	Config, validate, create
Cross-Studio	references/magicline/apis/magicline/openapi/openapi/cross-studio/	Multi-location customer lookup, checkin history
Checkin Vouchers	references/magicline/apis/magicline/openapi/openapi/checkin-vouchers/	Redeem vouchers

Connect API Endpoints

Overview: references/magicline/apis/magicline/connectapi/connectapi.md

Domain	Path	Key Operations
Contracts	references/magicline/apis/magicline/connectapi/connectapi/contracts/	Rate bundles, create customer+contract, cancel
Trial Sessions	references/magicline/apis/magicline/connectapi/connectapi/trialsessions/	Bookable slots, book, lead config
Credit Card Tokenization	references/magicline/apis/magicline/connectapi/connectapi/creditcard-tokenization/	Initiate, complete, state, payment methods
Bank Account	references/magicline/apis/magicline/connectapi/connectapi/bankaccount/	IBAN validation, BIC lookup
Studios	references/magicline/apis/magicline/connectapi/connectapi/studios/	List, details, SEPA text, legal links, utilization
Contract Vouchers	references/magicline/apis/magicline/connectapi/connectapi/contractvoucher/	Validate, redeem
Leads	references/magicline/apis/magicline/connectapi/connectapi/leads/	Create, get by UUID
Campaigns	references/magicline/apis/magicline/connectapi/connectapi/campaigns/	List active campaigns
Referrals	references/magicline/apis/magicline/connectapi/connectapi/referral/	List by studio
Validation	references/magicline/apis/magicline/connectapi/connectapi/validation/	Tax ID validation

Device API Endpoints

Overview: references/magicline/apis/magicline/deviceapi/deviceapi.md General info (auth, device setup, timeouts): references/magicline/apis/magicline/deviceapi/general-information.md

Domain	Path	Key Operations
Access Control	references/magicline/apis/magicline/deviceapi/deviceapi/access/	Card reader identification
Vending	references/magicline/apis/magicline/deviceapi/deviceapi/vending/	Identification, sale, revalue (top-up)
Time-based	references/magicline/apis/magicline/deviceapi/deviceapi/time/	Identification, pricing, usage

Key Patterns

Authentication

• OpenAPI & Connect API: Send X-API-KEY: <key> header. Keys are per-studio, received via activation email.
• Device API: First activate device via OpenAPI (POST /v1/devices/{deviceId}/activate), then use the returned Bearer token.
• HEAD requests (OpenAPI only): Return 200 if API key is valid, 401 if not. No business logic executed.

Preview-then-Execute (Memberships)

Financial operations should be previewed before executing. This lets you show the user costs/impacts before committing:

1. POST /v1/memberships/signup/preview → returns cost breakdown
2. Show preview to user for confirmation
3. POST /v1/memberships/signup → executes the signup

Dry-Run (Device API)

Device operations use shouldExecuteAction to separate validation from execution:

1. Call with shouldExecuteAction: false → validates the operation (dry-run)
2. Perform physical action (dispense product, open gate)
3. Call with shouldExecuteAction: true → commits the transaction

Vending operations also require a transactionId (UUID) for concurrency control — it locks the customer to one device at a time.

Pagination (OpenAPI)

Two patterns depending on endpoint:

• ID-based offset: offset is the last record's ID. Check hasNext for more pages.
• Slice-based offset: offset = previous offset + sliceSize. Check hasNext for more pages.

Always use the offset value from the response for the next request.

Error Handling

All APIs return consistent error responses:

{
  "errorMessage": "Human-readable message (locale-aware)",
  "errorCode": "Translation key",
  "traceId": "Datadog trace ID",
  "reference": "parent.child"
}

Code	Meaning
400	Validation failed
401	Auth failed (wrong/missing API key)
403	Insufficient permissions
404	Entity not found
409	Business logic conflict
429	Rate limited (default: 1000 req/min per endpoint)
500	Internal error
503	Database under load — retry with exponential backoff

Accept-Language Header

Pass Accept-Language header to get error messages in the desired language. Supported: cs, de, en, es, fr, hu, it, nb, nl, pl, ro, ru, sl, sv, tr. Country variants: de-CH, de-LI, en-CA, en-GB, en-US, fr-LU.

Common Data Formats

• Dates: ISO-8601 (2026-02-01)
• Date-times: ISO-8601 with timezone (2022-06-15T23:59:59.999+02:00[Europe/Berlin])
• Phone numbers: International format ([phone])
• Gender: MALE, FEMALE, UNISEX
• Customer status: MEMBER, PROSPECT, FORMER_MEMBER
• Access mediums: CARD_NUMBER, PIN, BARCODE, WALLET_PASS

Common Workflows

Look up a customer

1. Read references/magicline/apis/magicline/openapi/openapi/customers/getcustomerbyid.md for by-ID lookup
2. Read references/magicline/apis/magicline/openapi/openapi/customers/getcustomerby.md for lookup by email/card/etc.
3. Read references/magicline/apis/magicline/openapi/openapi/customers/searchcustomers.md for search

Sign up a new membership

1. Read references/magicline/apis/magicline/openapi/openapi/memberships/ directory for all membership endpoints
2. Flow: Get offers → Preview signup → Execute signup

Book a class

1. GET /v1/classes → list available classes
2. GET /v1/classes/{classId}/slots → get time slots
3. POST /v1/classes/booking/validate → check bookability
4. POST /v1/classes/booking/book → book the slot Read endpoint files in references/magicline/apis/magicline/openapi/openapi/classes/

Integrate a vending device

1. Read references/magicline/apis/magicline/deviceapi/general-information.md for device setup and timeout config
2. Flow: Identification → Dry-run sale → Physical dispense → Commit sale Read endpoint files in references/magicline/apis/magicline/deviceapi/deviceapi/vending/

Online contract conclusion (Connect API)

1. Get studio details and rate bundles
2. Collect customer data
3. Handle payment (SEPA or credit card tokenization)
4. Create customer and contract Read endpoint files in references/magicline/apis/magicline/connectapi/connectapi/contracts/

OpenAPI Specs

Download full specs for code generation:

• OpenAPI: https://redocly.sportalliance.com/_spec/apis/magicline/openapi/openapi.yaml
• Connect API: https://redocly.sportalliance.com/_spec/apis/magicline/connectapi/connectapi.yaml
• Device API: https://redocly.sportalliance.com/_spec/apis/magicline/deviceapi/deviceapi.yaml

How to Use This Skill

When helping with a Magicline integration task:

1. Identify the API using the decision guide above
2. Navigate to the right reference file using the domain tables
3. Read the specific endpoint file(s) relevant to the task — each file contains full parameter specs, response fields, and examples
4. Apply the relevant patterns (preview/execute, dry-run, pagination) based on the operation type
5. Use the common workflows as starting templates for multi-step integrations

Read only the files you need — don't load the entire reference corpus into context.