Player link notices

When a player unlinks an account in PlayerPal, PlayerPal can tell the affected operator or game provider straight away, so your platform stops showing the player as connected. The notice is a convenience, not a guarantee: your integration must also reconcile alias status on its own, because a notice can be missed.

In development: delivery is limited

Today notices are delivered only to a demonstration operator integration. Your platform will not receive them yet. Per-partner notice URLs and per-partner notice credentials are planned. Until then, reconcile alias status (step 4 below), which is available to every partner.

Events

Event	Sent when	Request	Status
Player link notice (status: revoked)	A player unlinks your operator or game provider integration in PlayerPal	POST /v1/player-link-notices on your endpoint	In development · demo

There are no other events today. Activity, facts and Points have no callbacks: check a batch with its status route instead.

How it works

• The Unlink completes in PlayerPal first. The notice is sent afterwards, and the player's Unlink never waits for, or fails because of, your endpoint.
• Unlinking an operator also revokes the game provider aliases issued through that operator's integrations. Each revoked alias produces its own notice.
• A repeated Unlink request does not send the notice again.

1Receive the notice

PlayerPal sends POST /v1/player-link-notices to your endpoint with a JSON body and content-type: application/json.

Field	Type	Meaning
audience_id	string, required	The public ID of the audience the alias was issued to: your operator ID, or the game provider integration's ID
player_alias	string, required	The alias you hold for this player: pp_plr_opr_… for operators, pp_plr_prv_… for game providers
alias_type	string, required	operator or provider_operator
status	string, required	Always revoked

The notice never contains PlayerPal's internal player ID or any personal data. Look the player up by player_alias.

POST /v1/player-link-notices

{
"audience_id": "pp_opr_XXXX",
"player_alias": "pp_plr_opr_XXXX",
"alias_type": "operator",
"status": "revoked"
}

2Authenticate it

Today a notice carries one credential: an x-api-key header with the integration key. Notices are not signed.

1. Compare x-api-key with your integration key in constant time.
2. Reject the request with 401 if it does not match.
3. Accept notices only over TLS, and keep the integration key server-side.

Planned

Signed notices with per-partner secrets are planned. Until then, the integration key is the only check.

Notice headers

POST /v1/player-link-notices
content-type: application/json
x-api-key: <your-integration-key>

3Respond quickly

Your handler should:

1. Find the alias by player_alias and audience_id, and mark it unlinked. Treat an unknown alias as success.
2. Return 204 (or any 2xx) within 2 seconds. Do any slower work afterwards.
3. Be idempotent: receiving the same notice twice must leave the same result.

Aspect	Current behaviour
Timeout	PlayerPal waits 2 seconds for your response
Success	Any 2xx status
Retries	None. A failed or timed-out notice is logged and not resent
Ordering	Not guaranteed across aliases
Delivery	Demonstration integration only (see above)

Your response204

HTTP/1.1 204 No Content

4Reconcile alias status

Available

GET/v1/aliases/{playerAlias}Status of a player alias issued to your audienceReference →

Because notices are limited and not retried, reconcile when you next display the player's link state, for example when they open their account page or launch a game from your lobby. Never call this per wager.

Send the integration key with x-operator-id (operators) or x-integration-id (game providers). See Authentication.

Response	What to do
200 { "status": "active" }	Keep the link
200 { "status": "revoked" }	Mark the link as unlinked, as you would for a notice
404 alias_not_found	Treat as unlinked
Network error or 5xx	Keep your last known state and try again later

PlayerPal being unreachable must never block play: show the last known state and move on.

✓

Checkpoint

For an alias you hold, you get 200 with status active. After the player unlinks, the same call returns revoked.

GET /v1/aliases/{playerAlias}curlNode.jsPythonPHPJavaC#

playerpal.sh

curl -sS "$API/v1/aliases/$ALIAS" \
  -H "x-api-key: $INTEGRATION_KEY" -H "x-operator-id: $OPERATOR_ID"
# 200 {"status":"active"} or {"status":"revoked"}

Response200

{ "status": "revoked" }

Alias not issued to you404

{
"statusCode": 404,
"message": "alias_not_found",
"error": "Not Found"
}

Related

GuideLink players

How players connect accounts and how aliases are issued.

→ReferenceIdempotency and errors

Every error code, including the alias status errors.

→GuideDesign for availability

Why link state never sits in the play path.

→