Player-Aware Destinations API

The right endpoint to power the destination dropdown in your transfer or send UI. Returns only the games where this specific player already has a presence — typically a much shorter list than every reachable game on the network.

When to use this

Player-Aware Destinations

• You already know who the player is (signed in)
• You're rendering a transfer / send wizard
• You want a short, relevant list (places the user actually has a presence)
• You want to show "you have X balance there" hints

Available Destinations (the per-tenant endpoint)

• You don't have a specific player yet (admin tools, onboarding)
• You want every game your tenant could reach
• You're building dashboards, not user-facing UI

POST

/api/players/destinations

Resolve every reachable destination this player already has a presence on

Authentication

Authenticate as the source tenant (your tenant) — the same SDK key you use to initiate transfers and sends.

X-Game-Secret-Key: ivsdk_your_secret_key

Request Body

Field	Type	Required	Description
email	string	Yes	Player email. Lower-cased server-side.
phone	string	Yes	E.164 preferred (`+15551234567`); common formats are also canonicalized.

Both fields are required because the network-wide identity hash is computed from (email, phone) together. Email alone is not enough to disambiguate accounts that share an email address with a different phone (or vice versa).

Example request

curl -X POST https://invo.network/api/players/destinations \
  -H "X-Game-Secret-Key: ivsdk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "player@example.com",
    "phone": "+15551234567"
  }'

200 response

{
  "status": "success",
  "source_game_id": "337916575744",
  "source_game_name": "GTA-6",
  "transfer_mode": "universal",
  "destinations": [
    {
      "game_id": "97288428282",
      "game_name": "AtheraPlay",
      "tenant_type": "video_platform",
      "game_status": "live",
      "default_currency": {
        "currency_id": 17,
        "currency_name": "Athero Stars",
        "currency_symbol": "*"
      },
      "available_balance": "120.00",
      "last_active": "2026-04-29T13:10:09+00:00"
    }
  ]
}

• destinations is sorted by most-recent activity, then game name.
• transfer_mode reflects your tenant's policy: universal returns every live tenant the player exists on; linked intersects with your linked_game_ids allowlist.
• available_balance is in the destination's default currency.
• An empty destinations array is a normal result (player exists only on your tenant). Surface as "no other tenants yet," not as an error.

Errors

HTTP	When
400	Missing or invalid `email` / `phone`
401	Missing or invalid `X-Game-Secret-Key`
403	Source tenant has outgoing transfers disabled

Privacy & leak model

The caller is required to know (email, phone) for the player they're acting on — if they didn't, they couldn't initiate a transfer or send for that player anyway. The destinations we return are filtered to tenants that your tenant is already legally allowed to transfer to (per your universal_transfers / linked_game_ids policy). We never reveal a presence on a tenant the caller couldn't act against, so this endpoint is safe to surface in user-facing UI.

Use it the same way for sends

This single endpoint covers both self-transfer (player moves their own balance to a destination tenant) and player-to-player send (gift to another human). The destinations returned are valid for either flow — pick the matching game_id as target_game_id in your subsequent /initiate-transfer or /initiate-send call. For sends to a different human, run this lookup against the recipient's (email, phone), not the sender's.