virtuagym
A typed Python client for the Virtuagym API — v1 (api key + club secret) and v3 (OAuth client credentials) — with sync and async clients.
- Typed models — every response is validated onto frozen pydantic models: responses that don't match the schema fail loudly instead of corrupting your data.
- Battle-tested against the live API — the behavior of every endpoint (pagination cursors, envelope quirks, type inconsistencies) was verified live; see API-FINDINGS for everything the docs don't tell you.
- Pagination handled — iterate lazily page by page, or fetch everything with one call. Duplicate rows caused by the API's inclusive cursors are deduplicated for you.
- Sync and async —
VirtuaGymClientV1/VirtuaGymClientV3on httpx's sync client,AsyncVirtuaGymClientV1/AsyncVirtuaGymClientV3on its async client, identical method surfaces. - Sibling packages: Node.js/TypeScript and PHP.
Installation
pip install virtuagym
Requires Python 3.10+.
API v1 (api key + club secret)
You need three values, all found in Virtuagym under Business settings → Business Info → Advanced: your API key, the "Club Key" (club secret), and your club id.
from virtuagym import VirtuaGymClientV1
client = VirtuaGymClientV1(
api_key="...",
club_secret="...",
club_id=12345,
)
# Lazily, page by page — each HTTP request only happens when you ask for the next page
for page in client.members():
print(f"received {len(page)} members")
# Or collect every page into a single list
members = client.all_members()
# Incremental sync (timestamp in ms)
changed = client.all_members(sync_from=last_sync_timestamp)
# Single member with membership instances embedded
member = client.member(7302399, with_="memberships")
# Mutations re-fetch and return the canonical record
created = client.create_member(
{"firstname": "John", "lastname": "Doe", "email": "john@example.com"}
)
updated = client.update_member(created.member_id, {"gender": "f"})
upserted = client.create_or_update_member(
{"external_id": "1ABC234567", "firstname": "John", "lastname": "Doe"}
)
The full v1 surface: employees, members, activate_user, events, membership_instances / membership_definitions / create_membership_instance, event_participants (bookings), club_taxes, income_categories, invoices, visits, member_notes, member_credits / add_member_credits, assign_workout, bodymetrics. Every list endpoint has a lazy iterator (members()) and a collector (all_members()). Mutation payloads are plain dicts with the API's wire-format keys.
Worth knowing (all verified live): single-resource GETs 404 with statuscode 420; the notes endpoint is capped at the newest 500 rows; notes and credits use seconds for sync_from while most endpoints use milliseconds; credits rows have no unique id and page-boundary duplicates are deduplicated for you.
API v3 (OAuth)
The v3 API is a separate stack behind gateway.services.virtuagym.com, authenticated with OAuth client credentials (register via api@virtuagym.com). Tokens are requested and renewed automatically (club-bound, ~30 min lifetime). Which v3 resources you can reach depends on the scopes Virtuagym registered for your client — without the right scope the API answers a misleading 401 Token not valid..
import time
from virtuagym import VirtuaGymClientV3
client = VirtuaGymClientV3(
client_id="...",
client_secret="...",
club_id=12345,
)
# Leads — the live API serializes EVERY lead field as a string
leads = client.all_leads()
lead = client.lead(751563)
created = client.create_lead({"firstname": "Jane", "lastname": "Doe", "email": "jane@example.com"})
client.update_lead(created.lead_id, {"status_id": 12}) # Closed won
# Schedule (requires the schedule_public_api_club_<club_id> scope)
now = int(time.time() * 1000)
week = 7 * 24 * 3600 * 1000
events = client.all_events(date_start=now, date_end=now + week, event_type="appointment")
bookings = client.all_event_bookings(date_start=now, date_end=now + week, member_id=42)
result = client.create_booking(events[0].event_id, {"member_id": 42})
# Inspect result.bookings[0].reason — see BOOKING_REASON_CODES in
# virtuagym.v3.models. NOTE: a member without the required credit type is
# booked UNPAID rather than rejected — check payment_info if payment matters.
client.update_booking(events[0].event_id, {"member_id": 42, "presence": True})
client.cancel_booking(events[0].event_id, member_id=42, refund=False)
Note: occurrences of a recurring event share the same event_id and differ only in datetime_start — use event_id + datetime_start as the occurrence key.
Async
Both clients have async twins with identical surfaces:
from virtuagym import AsyncVirtuaGymClientV1
client = AsyncVirtuaGymClientV1(api_key="...", club_secret="...", club_id=12345)
async for page in client.members():
...
members = await client.all_members()
Error handling
from virtuagym import VirtuaGymApiError, VirtuaGymV3ApiError
try:
client.member(999)
except VirtuaGymApiError as e:
# v1: in-band API errors (reported with HTTP 200), real-HTTP-status
# errors, and envelope failures.
print(e.statuscode, e.statusmessage) # e.g. 420 'Not found.'
VirtuaGymApiError(v1) —statuscode,statusmessage, optionalerrorspayload.VirtuaGymV3ApiError(v3) — real HTTP status inhttp_status, invalid field names infields. On a 401 the client refreshes the token and retries once before raising.pydantic.ValidationError— the response did not match the documented schema, naming the exact offending field.
Development
pip install -e .[dev]
pytest # unit tests (offline, mocked HTTP)
ruff check . && ruff format --check . && mypy
# Smoke tests against the live API (read-only):
cp .env.example .env # then fill in your credentials
pytest -m smoke
License
Metadata
Release files for virtuagym 1.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| virtuagym-1.0.2.tar.gz | 29.8 kB | With provenance | Details for virtuagym-1.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| virtuagym-1.0.2-py3-none-any.whl | Python 3 | none | any | Details for virtuagym-1.0.2-py3-none-any.whl |
Total release size: 62.2 kB
Release files / virtuagym-1.0.2.tar.gz
| Download URL | virtuagym-1.0.2.tar.gz |
|---|---|
| Size | 29.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f2119be9be5542cc2c2aef965ea7303215323350aca70cfe002dc5b2e01062f7
|
|
BLAKE2b-256 checksum How to use checksums |
99d4424a8ea4389e2c6cb71faf7472a456095a087975dba432fde6374e5cdcb3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.
Transparency logRelease files / virtuagym-1.0.2-py3-none-any.whl
| Download URL | virtuagym-1.0.2-py3-none-any.whl |
|---|---|
| Size | 32.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f3a7d7c3b9c068e14b6511ee12f50e8746ec583a9f8f532c2469f1a4e7ab00c7
|
|
BLAKE2b-256 checksum How to use checksums |
ec97e13cd0174df91d8bdc8ce2c7e09448b10b74c1e00356ba4cedfcfb32218e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.
Transparency logSecurity for virtuagym 1.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for virtuagym-1.0.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.