Skip to content

Players

Naming Convention Update

We are transitioning our naming conventions:

  • venue instead of tenant
  • player instead of user

New endpoints will use the updated terminology.

Get Player List

GET /api/v1/venues/{venue_id}/players

Returns a list of players from the venue (most recent first) using cursor-based pagination with a limit parameter and the response is a list object that wraps the results with additional metadata.

Parameters

Parameter Type Required Description
venue_id String Yes ID of the venue/club.
limit Int No Max objects to return (Max 100, default 20).
cursor_id String No Defines the place in the list. Use next_cursor_id from previous response.
include List [String] No Optional data to include:
BENEFITS
SPORTS
WALLETS

Response time

Please note that the response time of the request will depend on the values added to the include parameter.

Response (200)

A list object that contains an object with the following structure in its data field of type list.

Field Type Required Description
player_id String Yes ID the player.
name String Yes Full name of the player.
email String No Email address of the player.
phone String No Phone number of the player.
birth_date String No Birth date of the player. Format: YYYY-MM-DD.
gender String No Possible values:
MALE
FEMALE
HIDDEN
last_registration_date Date (UTC) Yes Date when the player last registered at this venue. Format: YYYY-MM-DDTHH:MM:SS
accepts_commercial_communications Boolean Yes true if the player has explicitly accepted to receive marketing communications from the venue. Otherwise, false.
sports List [Sport] No List of sports played by the player with their respective levels. See Sport Model below.
benefits List [Benefit] No List of benefits (categories & memberships) the player has at the venue. See Benefit Model below.
wallets List [Wallet] No List of wallets the player has at the venue. See Wallet Model below.

Response format

The fields sports, benefits and wallets will only be included in the response if they were explicitly requested using the include parameter.

Errors

Status Code Error Description
400 INVALID_CURSOR_ID Invalid cursor_id.
401 or 403 - Either you haven't set the authorization header or the token has expired.

Example

curl --request GET \
  --url "https://thirdparty.playtomic.io/api/v1/venue/<venue-id>/players?limit=4&include=BENEFITS,WALLETS,SPORTS" \
  --header "content-type: application/json" \
  --header "Authorization: Bearer <your-secret-token>"

{
    "has_more": true,
    "next_cursor_id": "AAAAAAAAAAAAAAAAAAAAAAAA",
    "last_modified": "2025-10-15T07:01:58",
    "data": [
        {
            "player_id": "123",
            "birth_date": null,
            "last_registration_date": "2025-05-21T09:28:45",
            "accepts_commercial_communications": false,
            "name": "Test player",
            "email": "testPlayer@email.com",
            "phone": "+34 123456789",
            "gender": null,
            "sports": [],
            "benefits": [
                {
                    "benefit_id": "acd6c2ba-c56f-4cb0-aad6-7e958a7ee3de",
                    "name": "TEST ADVANCE NO MEMBERSHIP",
                    "type": "ASSIGNED",
                    "expires_at": null
                }
            ],
            "wallets": []
        },
        {
            "player_id": "234",
            "birth_date": "1970-01-01",
            "last_registration_date": "2022-07-27T14:39:11",
            "accepts_commercial_communications": false,
            "name": "Test player 2",
            "email": "testPlayer2@email.com",
            "phone": "+34 223456789",
            "gender": "MALE",
            "sports": [],
            "benefits": [],
            "wallets": [
                {
                    "wallet_id": "amw:3aa9a616-c6d5-45ce-b2dd-3cf45e6805ba",
                    "name": "Club wallet",
                    "balance": "9987.5 EUR"
                }
            ]
        },
        {
            "player_id": "345",
            "birth_date": "1971-01-01",
            "last_registration_date": "2022-07-27T14:19:01",
            "accepts_commercial_communications": false,
            "name": "Some player",
            "email": "someplayer@email.com",
            "phone": "+46 1243252385923",
            "gender": "MALE",
            "sports": [],
            "benefits": [],
            "wallets": [
                {
                    "wallet_id": "amw:98323c06-e30f-4e68-be33-2644dbcb4c67",
                    "name": "Club wallet",
                    "balance": "12.5 EUR"
                }
            ]
        },
        {
            "player_id": "456",
            "birth_date": null,
            "last_registration_date": "2024-02-05T14:03:44",
            "accepts_commercial_communications": false,
            "name": "Some player 2",
            "email": "someplayer2@email.com",
            "phone": "+4 2243252385923",
            "gender": "MALE",
            "sports": [
                {
                    "sport_id": "PADEL",
                    "level_value": 2.20
                }
            ],
            "benefits": [
                {
                    "benefit_id": "8051cd7a-ec17-4f59-95a5-ebbd4aa5bd4c",
                    "name": "SIMPLE PRICE 50% DISCOUNT",
                    "type": "SOLD",
                    "expires_at": "2024-02-05T14:03:44"
                }
            ],
            "wallets": [
                {
                    "wallet_id": "amw:3361ce61-0a36-4951-862c-1e9b7b69a11f",
                    "name": "wallet app offers",
                    "balance": "1 EUR"
                },
                {
                    "wallet_id": "amw:0fb86581-381a-46db-9e9b-0f632b6e42ab",
                    "name": "test",
                    "balance": "100 EUR"
                }
            ]
        }
    ]
}

Get Single Player

GET /api/v1/venues/{venue_id}/players/{player_id}

Parameters

Parameter Type Required Description
venue_id String Yes ID of the venue/club.
player_id String Yes ID of the player.
include List [String] No Optional data to include:
BENEFITS
SPORTS
WALLETS

Response time

Please note that the response time of the request will depend on the values added to the include parameter.

Response (200)

Field Type Required Description
player_id String Yes ID the player.
name String Yes Full name of the player.
email String No Email address of the player.
phone String No Phone number of the player.
birth_date String No Birth date of the player. Format: YYYY-MM-DD.
gender String No Possible values:
MALE
FEMALE
HIDDEN
last_registration_date Date (UTC) Yes Date when the player last registered at this venue. Format: YYYY-MM-DDTHH:MM:SS
accepts_commercial_communications Boolean Yes true if the player has explicitly accepted to receive marketing communications from the venue. Otherwise, false.
sports List [Sport] No List of sports played by the player with their respective levels. See Sport Model below.
benefits List [Benefit] No List of benefits (categories & memberships) the player has at the venue. See Benefit Model below.
wallets List [Wallet] No List of wallets the player has at the venue. See Wallet Model below.

Response format

The fields sports, benefits and wallets will only be included in the response if they were explicitly requested using the include parameter.

Errors

Status Code Error Description
401 or 403 - Either you haven't set the authorization header or the token has expired.
404 - Player not found in the venue

Example

curl --request GET \
  --url "https://thirdparty.playtomic.io/api/v1/venue/<venue-id>/players/<player-id>?&include=BENEFITS,WALLETS,SPORTS" \
  --header "content-type: application/json" \
  --header "Authorization: Bearer <your-secret-token>"

{
    "player_id": "<player-id>",
    "birth_date": null,
    "last_registration_date": "2024-02-05T14:03:44",
    "accepts_commercial_communications": false,
    "name": "Some player 2",
    "email": "someplayer2@email.com",
    "phone": "+4 2243252385923",
    "gender": "MALE",
    "sports": [
        {
            "sport_id": "PADEL",
            "level_value": 2.20
        }
    ],
    "benefits": [
        {
            "benefit_id": "8051cd7a-ec17-4f59-95a5-ebbd4aa5bd4c",
            "name": "SIMPLE PRICE 50% DISCOUNT",
            "type": "SOLD",
            "expires_at": "2024-02-05T14:03:44"
        }
    ],
    "wallets": [
        {
            "wallet_id": "amw:3361ce61-0a36-4951-862c-1e9b7b69a11f",
            "name": "wallet app offers",
            "balance": "1 EUR"
        },
        {
            "wallet_id": "amw:0fb86581-381a-46db-9e9b-0f632b6e42ab",
            "name": "test",
            "balance": "100 EUR"
        }
    ]
}

Models

Sport Model

Field Type Required Description
sport_id String Yes Possible values:
PADEL
TENNIS
FOOTBALL7
FUTSAL
FOOTBALL_OTHERS
PADBOL
SQUASH
BADMINTON
PICKLEBALL
BEACH_TENNIS
BEACH_VOLLEY
BASKETBALL
VOLLEYBALL
CRICKET
TABLE_TENNIS
level_value Float No Level of the player in this sport.

Benefit Model

Field Type Required Description
benefit_id String Yes ID of the benefit.
name String Yes Name of the benefit.
type String Yes Possible values:
ASSIGNED: when a manager has assigned this benefit to the player
SOLD: when a player has purchased the benefit via Playtomic app
expires_at Date (UTC) No Expiration date of the benefit. For benefits of type ASSIGNED, the expires_at field indicates when the benefit will expire (if applicable). For benefits of type SOLD, this field represents the end date of the subscription period. Format: YYYY-MM-DDTHH:MM:SS

Wallet Model

Field Type Required Description
wallet_id String Yes ID of the wallet.
name String Yes Name of the wallet.
balance String [Money] Yes Current balance in the wallet. Format: amount currency_code, ie. 10 EUR or 25 USD.