> For the complete documentation index, see [llms.txt](https://docs.terragon.io/documents/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terragon.io/documents/terragon-api-document/referral.md).

# Referral

Player referral system

## List referral codes

> Retrieve a list of player's referral codes

```json
{"openapi":"3.0.0","info":{"title":"Terragon API Document","version":"1.0.0"},"tags":[{"name":"Referral","description":"Player referral system"}],"servers":[{"url":"https://api.terragon.io/player/api","description":"Staging server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"PaginationMeta":{"type":"object","properties":{"current_page":{"type":"integer","description":"Current page number"},"last_page":{"type":"integer","description":"Last page number"},"per_page":{"type":"integer","description":"Number of items per page"},"total":{"type":"integer","description":"Total number of items"},"data":{"type":"array","description":"Collection of items for the current page","items":{"type":"object"}}}},"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}}}}},"paths":{"/v1/referrals/codes":{"get":{"tags":["Referral"],"summary":"List referral codes","description":"Retrieve a list of player's referral codes","operationId":"listReferralCodes","parameters":[{"name":"page","in":"query","required":false,"description":"Page number for pagination","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","required":false,"description":"Number of items per page","schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"Referral codes retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginationMeta"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Create referral code

> Create a new referral code

```json
{"openapi":"3.0.0","info":{"title":"Terragon API Document","version":"1.0.0"},"tags":[{"name":"Referral","description":"Player referral system"}],"servers":[{"url":"https://api.terragon.io/player/api","description":"Staging server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ReferralCode":{"type":"object","properties":{"code":{"type":"string","description":"Referral code"}}},"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}}},"ValidationError":{"type":"object","properties":{"message":{"type":"string","description":"Error message"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Validation errors by field"}}}}},"paths":{"/v1/referrals/codes":{"post":{"tags":["Referral"],"summary":"Create referral code","description":"Create a new referral code","operationId":"createReferralCode","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Preferred referral code (optional, system will generate if not provided)"}}}}}},"responses":{"201":{"description":"Referral code created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralCode"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}}}}}
```

## List referees

> Retrieve a list of players who signed up using player's referral codes

```json
{"openapi":"3.0.0","info":{"title":"Terragon API Document","version":"1.0.0"},"tags":[{"name":"Referral","description":"Player referral system"}],"servers":[{"url":"https://api.terragon.io/player/api","description":"Staging server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"PaginationMeta":{"type":"object","properties":{"current_page":{"type":"integer","description":"Current page number"},"last_page":{"type":"integer","description":"Last page number"},"per_page":{"type":"integer","description":"Number of items per page"},"total":{"type":"integer","description":"Total number of items"},"data":{"type":"array","description":"Collection of items for the current page","items":{"type":"object"}}}},"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}}}}},"paths":{"/v1/referrals/referees":{"get":{"tags":["Referral"],"summary":"List referees","description":"Retrieve a list of players who signed up using player's referral codes","operationId":"listReferees","parameters":[{"name":"page","in":"query","required":false,"description":"Page number for pagination","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","required":false,"description":"Number of items per page","schema":{"type":"integer","default":10}},{"name":"code","in":"query","required":false,"description":"Filter by specific referral code","schema":{"type":"string"}}],"responses":{"200":{"description":"Referees retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginationMeta"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Referral history

> Retrieve a history of referral rewards

```json
{"openapi":"3.0.0","info":{"title":"Terragon API Document","version":"1.0.0"},"tags":[{"name":"Referral","description":"Player referral system"}],"servers":[{"url":"https://api.terragon.io/player/api","description":"Staging server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"PaginationMeta":{"type":"object","properties":{"current_page":{"type":"integer","description":"Current page number"},"last_page":{"type":"integer","description":"Last page number"},"per_page":{"type":"integer","description":"Number of items per page"},"total":{"type":"integer","description":"Total number of items"},"data":{"type":"array","description":"Collection of items for the current page","items":{"type":"object"}}}},"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}}}}},"paths":{"/v1/referrals/history":{"get":{"tags":["Referral"],"summary":"Referral history","description":"Retrieve a history of referral rewards","operationId":"getReferralHistory","parameters":[{"name":"page","in":"query","required":false,"description":"Page number for pagination","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","required":false,"description":"Number of items per page","schema":{"type":"integer","default":10}},{"name":"from_date","in":"query","required":false,"description":"Filter by start date (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"to_date","in":"query","required":false,"description":"Filter by end date (YYYY-MM-DD)","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Referral history retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginationMeta"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```