# Retrieving your members

Look up the members of your creator group and their codes via the Creator Code API.

Look up the members of your creator group and their codes. Every route here uses your public API key, so it is safe to call from a game client.

<Aside type="note">
Your **public** API key is used when retrieving information about a specific member.
</Aside>

## All members

Return every member of your group with their details, including unique `id` and `code`. This is a
public-key route, so it is safe to call from a game client.

<ApiMethod method="GET" path="/manage/members" />

<Tabs syncKey="lang">
<TabItem label="cURL">

```bash
curl -X GET https://api.nexus.gg/v1/manage/members \
  -H "accept: application/json" \
  -H "X-SHARED-SECRET: nexus_pk_your_key_here"
```

</TabItem>
<TabItem label="JavaScript">

```js
const res = await fetch('https://api.nexus.gg/v1/manage/members', {
  headers: { 'X-SHARED-SECRET': process.env.NEXUS_PUBLIC_KEY },
});
const { members } = await res.json();
```

</TabItem>
<TabItem label="Python">

```python
import requests

res = requests.get(
    "https://api.nexus.gg/v1/manage/members",
    headers={"X-SHARED-SECRET": NEXUS_PUBLIC_KEY},
)
members = res.json()["members"]
```

</TabItem>
</Tabs>

The status should be `200 OK` with a JSON response body that looks something like this:

```jsonc
{
  "groupId": "CsRKC8uD0NLtyQ0LOt8Ru",
  "groupName": "Test Group",
  "codeTTLInDays": 90, // only included if set in the Nexus Dashboard
  "currentPage": 1,
  "currentPageSize": 100,
  "totalCount": 15,
  "members": [
    {
      "id": "9jd7RBR_B2BZ0uWO3_lgv",
      "name": "PopcornFrog",
      "logoImage": "https://cdn.nexus.gg/9jd7RBR_B2BZ0uWO3_lgv/images/logo-image.jpg",
      "profileImage": "https://cdn.nexus.gg/9jd7RBR_B2BZ0uWO3_lgv/images/profile-image.jpg",
      "codes": [{ "code": "popcornfrog", "isPrimary": true, "isGenerated": false, "isManaged": false }]
    },
    {
      "id": "CsRKC8uD0NLtyQ0LOt8Ru",
      "name": "samzorz",
      "logoImage": "https://cdn.nexus.gg/CsRKC8uD0NLtyQ0LOt8Ru/images/logo-image.jpg",
      "profileImage": "https://cdn.nexus.gg/CsRKC8uD0NLtyQ0LOt8Ru/images/profile-image.jpg",
      "codes": [{ "code": "samzorz", "isPrimary": true, "isGenerated": false, "isManaged": false }]
    },
    {
      "id": "zeHr0cmIuvB8zVSSOAb7u",
      "name": "generatedMember",
      "logoImage": "https://cdn.nexus.gg/zeHr0cmIuvB8zVSSOAb7u/images/logo-image.jpg",
      "profileImage": "https://cdn.nexus.gg/zeHr0cmIuvB8zVSSOAb7u/images/profile-image.jpg",
      "codes": [{ "code": "sj04ka", "isPrimary": true, "isGenerated": true, "isManaged": true }]
    },
    {
      "id": "QqC42pqB4TJfcX6KOw7wv",
      "name": "claimedMember",
      "playerId": "userUniqueIdentifier1",
      "logoImage": "https://cdn.nexus.gg/QqC42pqB4TJfcX6KOw7wv/images/logo-image.jpg",
      "profileImage": "https://cdn.nexus.gg/QqC42pqB4TJfcX6KOw7wv/images/profile-image.jpg",
      "codes": [
        { "code": "mynexus", "isPrimary": true, "isGenerated": false, "isManaged": false },
        { "code": "dl8apj1", "isPrimary": false, "isGenerated": true, "isManaged": false }
      ]
    }
  ]
}
```

Codes you generated that have not yet been claimed by a Nexus account are flagged `isManaged`.

<LinkCard
  title="View full reference"
  description="Every parameter, response field, and status code."
  href="/api/operations/getmembers/"
/>

## Specific members

### By your unique identifier (playerId)

Retrieve the referral code and history for a member associated with a specific `playerId`.

<ApiMethod method="GET" path="/manage/members/player/{playerId}" />

```bash
curl -X GET https://api.nexus.gg/v1/manage/members/player/userUniqueIdentifier1 \
  -H "accept: application/json" \
  -H "X-SHARED-SECRET: nexus_pk_your_key_here"
```

The status should be `200 OK` with a JSON response body that looks something like this:

```jsonc
{
  "groupId": "CsRKC8uD0NLtyQ0LOt8Ru",
  "groupName": "Test Group",
  "codeTTLInDays": 90, // only included if set in the Nexus Dashboard
  "id": "QqC42pqB4TJfcX6KOw7wv",
  "name": "claimedMember",
  "playerId": "userUniqueIdentifier1",
  "logoImage": "https://cdn.nexus.gg/QqC42pqB4TJfcX6KOw7wv/images/logo-image.jpg",
  "profileImage": "https://cdn.nexus.gg/QqC42pqB4TJfcX6KOw7wv/images/profile-image.jpg",
  "codes": [
    { "code": "mynexus", "isPrimary": true, "isGenerated": false, "isManaged": false },
    { "code": "dl8apj1", "isPrimary": false, "isGenerated": true, "isManaged": false }
  ]
}
```

<LinkCard title="View full reference" description="GET a member by your internal playerId." href="/api/operations/getmemberbyplayerid/" />

### By code or member ID

You can also retrieve a member by their `code` or `memberId`.

<ApiMethod method="GET" path="/manage/members/{memberCode}" />
<ApiMethod method="GET" path="/manage/members/id/{memberId}" />

<Tabs syncKey="lookup">
<TabItem label="By code">

```bash
curl -X GET https://api.nexus.gg/v1/manage/members/mynexus \
  -H "accept: application/json" \
  -H "X-SHARED-SECRET: nexus_pk_your_key_here"
```

</TabItem>
<TabItem label="By ID">

```bash
curl -X GET https://api.nexus.gg/v1/manage/members/id/QqC42pqB4TJfcX6KOw7wv \
  -H "accept: application/json" \
  -H "X-SHARED-SECRET: nexus_pk_your_key_here"
```

</TabItem>
</Tabs>

The status should be `200 OK` with a JSON response body in the same member shape as the playerId lookup:

```jsonc
{
  "groupId": "CsRKC8uD0NLtyQ0LOt8Ru",
  "groupName": "Test Group",
  "codeTTLInDays": 90, // only included if set in the Nexus Dashboard
  "id": "QqC42pqB4TJfcX6KOw7wv",
  "name": "claimedMember",
  "playerId": "userUniqueIdentifier1",
  "logoImage": "https://cdn.nexus.gg/QqC42pqB4TJfcX6KOw7wv/images/logo-image.jpg",
  "profileImage": "https://cdn.nexus.gg/QqC42pqB4TJfcX6KOw7wv/images/profile-image.jpg",
  "codes": [
    { "code": "mynexus", "isPrimary": true, "isGenerated": false, "isManaged": false },
    { "code": "dl8apj1", "isPrimary": false, "isGenerated": true, "isManaged": false }
  ]
}
```

<LinkCard title="View full reference" description="Look up a member by code." href="/api/operations/getmemberbycode/" />
<LinkCard title="View full reference" description="Look up a member by member ID." href="/api/operations/getmemberbyid/" />

### Code time to live (TTL)

We recommend persisting an entered code indefinitely (see our [UI & UX best practices](/best-practices/ui-and-ux/#make-creator-codes-persistent-once-entered)). However, each
member-retrieval route passes through a `codeTTLInDays` property to help you implement a time-to-live
system. Set it in your [Nexus Dashboard](https://www.nexus.gg/publisher/dashboard/creator-programs)
under your program's Configuration settings. It is passed through on every member-retrieval response,
so you can change or remove the TTL without shipping a new build of your application.

#### Code TTL implementation example

When a user enters a code, persist it with a timestamp. On render, look the member up by code via the
[By Code or Member ID](#by-code-or-member-id) route. If the response includes a `codeTTLInDays`, compare
it to the days since you saved the code. If the gap exceeds `codeTTLInDays`, clear the saved code and
require re-entry. Always account for there being no `codeTTLInDays` on the response, so you can remove
the TTL at any time.