# Players

> POST /v1/players/:id and GET /v1/players/:id/profile

Source: https://docs.onari.xyz/docs/api/players

Players are created automatically with their first event. These endpoints are for setting a referrer in advance and for reading a player's progress in your own app.

## Create a player or set their referrer

```http
POST https://api.onari.xyz/v1/players/{player_id}
```

```json
{ "referred_by": "user_51f0" }
```

`referred_by` is optional and only set once; a player can't refer themselves.

```json
{ "player_id": "user_8a21", "referred_by": "user_51f0" }
```

## Read a player's profile

```http
GET https://api.onari.xyz/v1/players/{player_id}/profile
```

```json
{
  "player_id": "user_8a21",
  "first_seen_at": "2026-09-02T09:00:00Z",
  "last_seen_at": "2026-10-20T08:41:10Z",
  "campaigns": [
    { "id": "6f1c…", "name": "October challenge", "type": "challenge", "progress": 2, "goal": 3, "wins": 0, "ends_at": "2026-11-01T00:00:00Z" }
  ],
  "rewards": [
    { "id": "a91e…", "campaign_id": "9c3d…", "kind": "voucher", "value": 200000, "currency": "NGN", "code": "SAVE-7QX4-M9", "perk": null, "status": "delivered", "created_at": "2026-10-02T12:00:00Z" }
  ]
}
```

`campaigns` only includes running campaigns the player is taking part in. A player Onari hasn't seen yet returns `404 player_not_found`.

Most apps don't need this: the [Rewards Hub](/docs/rewards-hub) shows all of it to the player.