Player Onboarding & Verification

This guide walks through the full flow for checking whether a player is a verified member of your guild, and guiding them through verification if they are not.

Use this flow anywhere you need to gate a feature behind identity verification — for example, before allowing a player to join a Cash Game or access age-restricted content.

Flow Overview

flowchart TD
    A([Player attempts to access gated feature]) --> B{Is player a guild member?}
    B -- No --> C[Create GuildInvite via API]
    C --> D[Redirect player to GamerSafer with invite URL]
    D --> E{Player completes guild join?}
    E -- No / Abandoned --> Z([Block access])
    E -- Yes --> F[Receive guildInvite webhook\nsave guildMemberId]
    F --> G{Has verified document?}
    B -- Yes --> G
    G -- No / Pending --> H["Show 'Document required' popup"]
    H --> I[Redirect player to GamerSafer Documents deeplink]
    I --> J[Receive documentValidated webhook]
    J --> K([Grant access to gated feature])
    G -- Yes --> K

Step 1 — Check Guild Membership

When a player tries to access a gated feature, check whether you already have a guildMemberId stored for them.

Recommendation: store the guildMemberId returned by the guildInvite webhook in your database, linked to your internal player ID. This avoids a round-trip to the GamerSafer API on every check.

If the player is already a member, skip to Step 3.

Step 2 — Create a GuildInvite and Redirect

If the player is not yet a guild member, show a popup explaining that verification is required to access this feature.

When they confirm, call POST /guilds/invites from your backend:

POST /guilds/invites HTTP/1.1
Host: api.gamersafer.com
Authorization: Bearer <GUILD_TOKEN>
Content-Type: application/json

{
  "internalId": "your-internal-player-id",
  "webhookUrl": "https://your-backend.com/webhooks/gamersafer",
  "linkBack": "https://your-app.com/deeplink/back"
}

Parameter	Required	Description
`internalId`	No	Your internal player ID — returned in the webhook so you can match records
`webhookUrl`	No	URL GamerSafer will POST the `guildInvite` event to
`linkBack`	No	URL (or mobile deeplink) to redirect the player to after they complete the flow

Response:

{
  "qrCode": "data:image/png;base64,...",
  "qrCodePayload": "https://links.gamersafer.com/invite/..."
}

Use qrCodePayload to redirect the player directly (in-app), or render qrCode as a QR code for desktop flows.

Step 3 — Wait for the guildInvite Webhook

Once the player completes the join flow in the GamerSafer app, GamerSafer will POST to your webhookUrl:

{
  "event": "guildInvite",
  "payload": {
    "code": "123456",
    "guildMemberId": "01FC3GW10QG03E3FH3Q5ZPAYEN",
    "internalId": "your-internal-player-id"
  },
  "ageGroup": {
    "label": "ADULT",
    "confidence": "HIGH",
    "genderPrediction": "MALE"
  },
  "player": { "id": "01FC3GW10QG03E3FH3Q5ZPAYZ" }
}

Store the guildMemberId — you will need it for all subsequent API calls for this player.

Step 4 — Check Document Verification

After confirming guild membership, check whether the player has a verified document.

Recommendation: store a boolean flag in your database when you receive the documentValidated webhook. This avoids querying the GamerSafer API on every access attempt.

If the document is not yet verified or is still pending, show a popup and redirect the player to the GamerSafer Documents deeplink:

https://links.gamersafer.com/mydocuments

When their document is validated, you will receive a documentValidated webhook (see Webhooks).

Once both conditions are met — guild membership and verified document — grant the player access to the gated feature.