# Build a Custom Advocate Experience with GraphQL
We advise most users to use the built-in widgets and [widget editor](https://help.impact.com/en/support/solutions/articles/155000000314-customize-program-widgets) to power the Advocate experience, but in some cases, building your own Advocate experience using data pulled in via [GraphQL](https://integrations.impact.com/impact-brand/docs/graphql-reference) is recommended. The best implementation path for your program will be discussed with your onboarding team. These are some situations in which a custom Advocate participant experience may be the right choice:
* Your company has a strict Content Security Policy (CSP) that prevents our custom JavaScript from rendering on the page.
* You're building a mobile app natively and need an advanced degree of control over widget creation.
* You want to load the widget on the server or back-end, rather than on the front-end.
#### Build, test, or run GraphQL queries and mutations
You can build and test GraphQL queries and mutations as well as explore our GraphQL documentation within your impact.com account.
To get started:
1. In your impact.com account, from the top navigation bar, select  **\[User profile]** → [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml).
2. In the *Advocate Settings* section, select **GraphQL**.
3. Use the interface to build, test, or run queries, or explore our documentation.
{% stepper %}
{% step %}
### Authenticate
You will need a [GraphQL client](https://graphql.org/code/#graphql-clients) to begin.
The endpoint URL is `https://app.referralsaasquatch.com/api/v1/{tenant_alias}/graphql`. You can find your tenant alias in the impact.com platform:
1. From the top navigation bar, select  **\[User profile]** → [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml) .
2. Under *Advocate Settings*, select **General**.
3. Retrieve your tenant alias from the *Tenant Details* section at the top of the page.
To simplify authentication, we recommend making GraphQL calls authorized as the end user. You'll need to generate a [JSON Web Token](https://integrations.impact.com/impact-brand/docs/json-web-tokens) for your user on the server, using your tenant's [API key](/rest-apis/api-quick-start/create-an-api-key.md). Use the header `Authorization: Bearer {JWT}`.
{% endstep %}
{% step %}
### Build GraphQL queries
{% hint style="success" %}
**Note:** Basic auth is required when making GraphQL calls.
{% endhint %}
The following queries and mutations are commonly used when building a custom experience.
#### Look up the user
The easiest way to get data in a custom experience is to use the special `viewer` property to look up the user that is currently authorized.
#### GraphQL Query
{% tabs %}
{% tab title="GraphQL" %}
```graphql
{
viewer {
... on User {
firstName
lastName
}
}
}
```
{% endtab %}
{% endtabs %}
#### Example
{% tabs %}
{% tab title="JSON" %}
```json
{
"viewer": {
"firstName": "Carrie",
"lastName": "Oakey"
}
}
```
{% endtab %}
{% endtabs %}
### Display a list of rewards
You can look up a list of rewards to show people what they've earned from your programs.
* `prettyValue` vs `value`: When building custom widgets it's usually best to use the `prettyValue` for rewards, since that will format and localize the reward value into something readable. Note that there are also pretty fields for available and expired values.
* `value` vs `availableValue`: The value of a reward may change due to it being expired, or canceled, or redeemed. If you want to show a sense of progress, you can show a lifetime earned amount.
#### GraphQL Query
{% tabs %}
{% tab title="GraphQL" %}
```graphql
{
viewer {
... on User {
firstName
lastName
rewards {
data {
prettyValue
prettyAvailableValue
}
}
}
}
}
```
{% endtab %}
{% endtabs %}
#### Example
{% tabs %}
{% tab title="JSON" %}
```json
{
"viewer": {
"firstName": "Carrie",
"lastName": "Oakey",
"rewards": {
"data": {
"prettyValue": "$10.00",
"prettyAvailableValue": "$4.75"
}
}
}
}
```
{% endtab %}
{% endtabs %}
### Show who referred the participant
If someone has been referred, showing them "You were referred by `{name}`" in the user interface is common. To look that up, use the `referredByReferral` connection to find out more about the referral.
#### GraphQL Query
{% tabs %}
{% tab title="GraphQL" %}
```graphql
{
viewer {
... on User {
firstName
lastName
referredByReferral(programId: "referral") {
referrerUser {
firstName
lastName
}
}
}
}
}
```
{% endtab %}
{% endtabs %}
#### Example
{% tabs %}
{% tab title="JSON" %}
```json
{
"viewer": {
"firstName": "Sansa",
"lastName": "Stark",
"referredByReferral": {
"referrerUser": {
"firstName": "Jon",
"lastName": "Snow"
}
}
}
}
```
{% endtab %}
{% endtabs %}
### Display list of referrals
To show someone their list of referrals, and any rewards earned because of those referrals, use the referrals connection on a user.
Note that you'll need to include your `programId` in this call only if one user is making referrals across different referral programs, and you want to filter them out.
#### GraphQL Query
{% tabs %}
{% tab title="GraphQL" %}
```graphql
{
viewer {
... on User {
firstName
lastName
referrals(filter: {programId_eq: "referral"}, limit: 3) {
data {
referrerUser {
firstName
lastName
}
}
totalCount
count
}
}
}
}
```
{% endtab %}
{% endtabs %}
#### Example
{% tabs %}
{% tab title="JSON" %}
```json
{
"viewer": {
"firstName": "Carrie",
"lastName": "Oakey",
"referrals": {
"data": [
{
"referrerUser": {
"firstName": "Noah",
"lastName": "Lott"
}
},
{
"referrerUser": {
"firstName": "Olivia",
"lastName": "Sutton"
}
},
{
"referrerUser": {
"firstName": "Earl",
"lastName": "Bird"
}
}
],
"totalCount": 1021,
"count": 3
}
}
}
```
{% endtab %}
{% endtabs %}
### Update a participant's information
You can also do a complete upsert, instead of using the user upsert from [UTT](https://integrations.impact.com/impact-brand/docs/install-the-utt) or our [REST API](https://integrations.impact.com/impact-brand/docs/saasquatch-rest-api-1). Only the fields that are included are updated, so you can add new fields, or add new segments, without removing or overriding previous values.
#### GraphQL Mutation
{% tabs %}
{% tab title="GraphQL" %}
```graphql
mutation {
upsertUser(userInput: {
id: "",
accountId: "",
lastName: "Lott",
segments: ["Platinum"],
customFields: {
VIP: true
}
}) {
firstName
lastName
segments
customFields
}
}
```
{% endtab %}
{% endtabs %}
#### Example
{% tabs %}
{% tab title="JSON" %}
```json
{
"upsertUser": {
"firstName": "Carrie",
"lastName": "Lott",
"segments": [
"Platinum"
],
"customFields": {
"VIP": true
}
}
}
```
{% endtab %}
{% endtabs %}
### Look up reward configuration
You can advertise what people will earn from your program by looking up the program by `id`, and then looking up the program's rewards. Every program has a different set of reward keys.
#### GraphQL Query
{% tabs %}
{% tab title="GraphQL" %}
```graphql
{
viewer {
... on User {
firstName
lastName
}
}
program(id: "referral") {
rewards {
prettyValue
}
tierOneOnly: reward(key: "referrerTier1") {
prettyValue
}
}
}
```
{% endtab %}
{% endtabs %}
#### Example
{% tabs %}
{% tab title="JSON" %}
```json
{
"viewer": {
"firstName": "Carrie",
"lastName": "Oakey"
},
"program": {
"rewards": [
{
"key": "referredReward",
"prettyValue": "$10.00"
},
{
"key": "referrerTier1",
"prettyValue": "$20.00"
}
],
"tierOneOnly": {
"prettyValue": "$20.00"
}
}
}
```
{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}
## Other queries and mutations
See our GraphQL explorer in your impact.com account for a full list of the available queries and mutations.
1. In your impact.com account, from the top navigation bar, select  **\[User profile]** → [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml).
2. In the *Advocate Settings* section, select **GraphQL**.
3. Use the interface to build, test, or run queries, or explore our documentation.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://integrations.impact.com/integration-guides/for-brands/advocate/build-a-custom-advocate-experience-with-graphql.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.